Uma consulta.
Dados de todas as fontes.

Sua primeira chamada

1. Entre na Conta e crie uma chave. Ela só aparece uma vez.
2. Guarde-a como variável de ambiente no seu servidor.
3. Envie Authorization: Bearer em cada consulta.

curl --fail-with-body \
  -H "Authorization: Bearer $CNPJ_API_KEY" \
  https://api.cnpj.ai/v2/estabelecimentos/02709449000159/full

A mesma chave funciona na v1 e na v2. Use-a no backend: não a inclua em código de navegador ou aplicativo distribuído. As consultas não habilitam CORS para uso direto no navegador.

import os
import requests

resposta = requests.get(
    "https://api.cnpj.ai/v2/estabelecimentos/02709449000159/full",
    headers={"Authorization": f"Bearer {os.environ['CNPJ_API_KEY']}"},
    timeout=30,
)
resposta.raise_for_status()
consulta = resposta.json()
print(consulta["dados"]["estabelecimento"]["cnpj"])
print(consulta["meta"]["disponibilidade"])

Teste a API no Postman

As versões v1 e v2 estão na mesma collection, separadas em pastas, com chamadas prontas e exemplos de respostas.

1. Use Adicionar ao Postman e confirme Fork Collection no seu workspace. Ou baixe a collection e selecione o JSON em Import.
2. Nas variáveis da collection, preencha o valor local de api_key com a chave criada na Conta, sem o prefixo Bearer. Mantenha o valor compartilhado vazio.
3. Abra v2 → Comece aqui e envie uma consulta. Para usar a versão anterior, abra a pasta v1; a chave é a mesma.

O workspace público oficial também oferece o environment opcional cnpj.ai — Produção. Se fizer um fork e selecioná-lo, preencha api_key no valor local do environment: ele tem prioridade sobre a collection, mesmo quando está vazio. Mantenha o valor compartilhado da chave vazio.

A collection oficial acompanha as atualizações da API. Em um fork existente, use Pull changes para receber novidades. O download do JSON é uma cópia pontual.

A URL de produção e os CNPJs de exemplo já vêm preenchidos. Use o aplicativo desktop do Postman ou o Desktop Agent no Postman web para enviar as chamadas.

Empresa ou estabelecimento

Identificadores sem máscara, numéricos ou alfanuméricos. Letras são normalizadas para maiúsculas. O CNPJ completo precisa ter verificadores válidos. Cada rota exige o comprimento indicado; um estabelecimento inexistente retorna 404, mesmo que a empresa exista.

As mesmas modalidades estão disponíveis em estabelecimentos. Fontes com CNPJ completo são filtradas pelo estabelecimento consultado. Habilitação aduaneira só identifica o CNPJ básico: aparece com escopo: "empresa", inclusive na consulta de um estabelecimento.

Fontes de registros públicos

Acrescente /fontes/{fonte} à URL da empresa ou do estabelecimento. O bloco no full e a resposta do endpoint específico têm o mesmo formato.

O catálogo JSON de fontes é público e não consome chamadas. Cada consulta informa a disponibilidade real da carga, competência, cobertura, data de carga e origem por fonte. Uma fonte suportada pode estar indisponível ou desatualizada.

Registros de fontes diferentes podem se referir ao mesmo processo. O full preserva os registros individuais; não some CNEP e leniência como ocorrências distintas. No PNCP, o valor global pertence ao contrato e não informa a parcela de um subcontratado.

No BNDES, documento_fonte, cnpj_vinculado e metodo_vinculo distinguem publicação e inferência. Os dados incluem atribuição, licença ODbL 1.0 e metodologia. Um subcrédito não equivale necessariamente a um contrato. Os retornos são factuais e não produzem score ou certidão.

Todos os registros, por páginas

O parâmetro limite aceita de 1 a 100 itens por coleção; o padrão é 20. Cada coleção retorna itens, total, proximo_cursor e proxima_url. No full, o limite se aplica separadamente a cada coleção.

Continue pela proxima_url, relativa a https://api.cnpj.ai, enviando a mesma autenticação. O link aponta para a coleção específica, não para outra página do full. proxima_url: null indica o fim.

GET /v2/empresas/02709449/estabelecimentos?limite=20
GET /v2/empresas/02709449/socios?limite=20
GET /v2/empresas/02709449/fontes/pgfn?limite=20

Use o cursor e o limite exatamente como vierem no link. O cursor pertence à coleção, documento e fotografia da base. Se a carga mudar, a API retorna 409 fotografia_alterada: reinicie a paginação sem cursor e descarte a sequência anterior. A ordem é estável dentro da fotografia; não implica relevância ou recência.

Como interpretar o retorno

dados.empresa

Cadastro compartilhado, socios paginados e simples (ou null).

dados.estabelecimento

Objeto único na consulta de CNPJ completo.

dados.estabelecimentos

Coleção paginada na consulta de empresa.

dados.registros_publicos

Presente no full: grupos temáticos com as páginas de cada fonte.

meta

Versão, release, recurso, documento normalizado, competência da Receita, fotografia, identificador de requisição e disponibilidade completa/parcial.

No endpoint específico de uma fonte, dados é diretamente a página daquela fonte. Cada página contém status, escopo, documento, competencia, carregada_em, cobertura_inicio, desatualizada e proveniencia, além dos itens e da paginação.

O full pode retornar HTTP 200 com meta.disponibilidade: "parcial": confira cada fonte. desatualizada: true indica uma carga marcada como antiga; null indica que essa informação não está disponível. As competências são próprias de cada fonte, não uma data única de atualização de todos os dados.

Campos cadastrais usam os nomes da Receita, com códigos como strings e descrições em descricoes. Datas cadastrais são ISO ou null. Datas e históricos dos registros públicos preservam a representação armazenada pela fonte; a PGFN usa AAAAMMDD e o PNCP também possui timestamps ISO. Valores monetários preservam a precisão disponível na carga. Simples/MEI podem ser true, false ou null (não informado). Documentos mascarados permanecem mascarados.

O OpenAPI interativo descreve os campos de todas as fontes. Veja também um exemplo completo com dados fictícios.

Gratuita, com consumo previsível

60 chamadas por minuto por conta, compartilhadas entre v1, v2 e até 5 chaves ativas. Sem cartão e sem cota mensal inicial. Basic, full ou página de uma fonte contam como uma chamada cada.

Chamadas admitidas contam inclusive em 400, 404, 409 e falhas posteriores à admissão. Bloqueios por limite aparecem separadamente. O histórico na Conta identifica versão e endpoint; documentação e gerenciamento de chaves não consomem a cota.

As respostas incluem X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Em 429, respeite Retry-After. Existe também proteção por IP.

Erros: 400 entrada/parâmetro/cursor inválido; 401 chave ausente, inválida ou revogada; 404 recurso não encontrado; 409 fotografia alterada; 429 limite; 503 serviço temporariamente indisponível.

Versionamento

A release 2.0.0 introduz os recursos separados, basic/full e fontes paginadas. A documentação da v1 e o OpenAPI v1 continuam disponíveis. A v1 preserva seu contrato 1.0.1; a migração é explícita para as URLs v2.