Consulta de CNPJ em lote por API

Uma planilha de fornecedores, uma carteira de clientes ou uma importação de cadastro: com POST /companies/lookup você confere até 100 CNPJs em uma só chamada e recebe tudo em JSON.

Por que a consulta em lote existe

Quem busca "consulta CNPJ em lote" normalmente tem uma lista: as linhas de uma planilha, um arquivo de remessa, a base de fornecedores que o financeiro quer higienizar antes do fechamento. Digitar um CNPJ por vez no portal não escala, e disparar milhares de chamadas isoladas contra uma API torna o código mais frágil. A consulta em lote resolve o meio do caminho: você envia até 100 itens, a resposta volta na mesma ordem e o seu programa trata o resultado de uma vez.

Como a chamada funciona

POST /companies/lookup recebe uma lista de itens, cada um com o país e o identificador da empresa. Para o Brasil, o identificador é o CNPJ, com ou sem pontuação, ou os oito dígitos da raiz. O limite é de 100 itens por chamada.

curl -X POST 'https://api.prometiam.com/functions/v1/risk-api/companies/lookup' \
  -H 'Authorization: Bearer rk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"items": [
        {"country": "BR", "company_number": "33.000.167/0001-01"},
        {"country": "BR", "company_number": "00.000.000/0001-91"}
      ]}'

O corpo exato dos itens e o formato da resposta estão na documentação da API. Os resultados ficam em data, um por item e na ordem do pedido: o status do item (found ou not_found) e, em company, o mesmo objeto de empresa de uma consulta individual, com company_name, local_status, legal_form e o activity_code em CNAE 2.3.

Exemplo em Python: de uma planilha para um lote

import csv
import requests

BASE = 'https://api.prometiam.com/functions/v1/risk-api'
H = {'Authorization': 'Bearer rk_live_...'}

cnpjs = [linha['cnpj'] for linha in csv.DictReader(open('fornecedores.csv', encoding='utf-8'))]
for i in range(0, len(cnpjs), 100):
    lote = cnpjs[i:i + 100]
    r = requests.post(f'{BASE}/companies/lookup', headers=H, timeout=60,
                      json={'items': [{'country': 'BR', 'company_number': c} for c in lote]})
    r.raise_for_status()
    for item in r.json()['data']:
        e = item['company']
        print(item['status'], e['company_name'] if e else None)

Quanto custa e o que acontece com a cota

• Cada item do lote conta como uma consulta e custa 1 crédito, como na consulta individual; uma chamada de 100 itens custa 100 créditos.
• Um lote que ultrapassa a cota do mês é recusado de antemão, com o erro 429 batch_exceeds_quota e o campo max_items_now, que diz quantos itens ainda cabem. Nada é consumido por um lote recusado.
• Erros não custam créditos.
• No teste gratuito de 14 dias você tem 500 créditos, o que dá para validar cerca de cinco lotes completos; é preciso informar um cartão, e nada é cobrado durante o teste.

O teste gratuito dura 14 dias e inclui 500 créditos; é preciso informar um cartão, mas nada é cobrado durante o teste. Depois, o plano Starter custa € 9,99 por mês com 1.000 créditos, o Professional € 29,99 com 10.000 e o Scale € 99,99 com 50.000; o Enterprise tem preço sob consulta. Consultar um registro de empresa custa 1 crédito, cerca de € 0,01 no Starter e a partir de € 0,002 no Scale. Os preços são públicos e o plano anual dá dois meses grátis.

Quando um CNPJ não volta no lote

Um item sem resultado não prova que a empresa não existe. A Prometiam serve só pessoas jurídicas: o MEI, o empresário individual, as filiais, as entidades sem fins lucrativos e os órgãos públicos não aparecem. CNPJs com dígitos verificadores incorretos também não retornam registro. Limpe e valide a lista antes, com o validador de CNPJ, que aceita o formato alfanumérico.

Depois do lote: acompanhar mudanças

Se a lista é uma carteira que você precisa acompanhar, POST /monitor envia um webhook quando a situação cadastral de uma empresa muda. A fonte é a Receita, com um arquivo por mês, então a leitura é mensal. Para uma decisão urgente, confirme o cartão CNPJ na Receita.

O que não cobrimos no Brasil

• Só pessoas jurídicas: o empresário individual, o MEI e as demais pessoas físicas nunca são servidos. A EIRELI é servida.
• Sem quadro societário (QSA), sem sócios e sem administradores, e sem telefone nem e-mail de contato.
• Sem número de IVA: o Brasil não tem um número de IVA ligado ao CNPJ, e uma busca com vat= é recusada.
• Sem avisos de insolvência: o Brasil não é um dos doze mercados de insolvência. Recuperação judicial, falência e liquidação aparecem na situação especial e no status.
• Demonstrações financeiras apenas de companhias abertas (CVM), a partir do plano Scale; as demais empresas não têm demonstrações.
• A atividade é a CNAE 2.3 (BR-CNAE-2.3), não a NACE, e nenhum código NACE é derivado dela.
• Uma empresa por raiz de CNPJ, com o CNPJ da matriz; filiais, entidades sem fins lucrativos, órgãos públicos e sucursais de empresas estrangeiras não são servidos.

Contains data from the Cadastro Nacional da Pessoa Jurídica (CNPJ), Receita Federal do Brasil, published as open data (CC BY). Adapted by Prometiam.

Páginas relacionadas

• API de consulta de CNPJ
• Validador de CNPJ
• CNPJ alfanumérico
• Conferir fornecedores antes da NF-e
• Documentação da API
• Preços

Começar o teste gratuito de 14 dias · Documentação da API

O teste dura 14 dias e inclui 500 créditos. É necessário informar um cartão; nada é cobrado durante o teste e, depois, vale o plano Starter (€ 9,99 por mês), salvo cancelamento.