Documentação do cnpj.ia.br

A API REST em https://api.cnpj.ia.br e o servidor MCP em https://mcp.cnpj.ia.br usam a mesma chave, criada em app.cnpj.ia.br. Toda resposta de consulta e de busca traz meta.data_as_of, a data da base da Receita Federal servida, e meta.credits_charged, o custo da chamada. O plano Free dá 60 créditos por mês.

Comece pelo início rápido

Quatro passos: criar a chave, fazer a primeira consulta, ler a resposta e conferir o uso. Leva menos tempo do que ler esta página.

• Início rápido: a primeira consulta em curl, Python, Node, PHP, Ruby, Go e n8n.
• Autenticação: Authorization: Bearer, escopo da chave, rotação e revogação.

Referência

• Consulta por CNPJ: GET /v1/cnpjs/{cnpj} com perfil basic (1 crédito) ou full (6 créditos).
• Busca de empresas: GET /v1/cnpjs com filtros por UF, município, CNAE, porte, situação, Simples, MEI, natureza jurídica, capital e data de abertura.
• Campos da resposta: todos os campos dos dois perfis, com tipo, nulabilidade, descrição e tabelas de códigos.
• Referência gerada do OpenAPI: uma página por operação, com parâmetros, respostas, headers e créditos.

Operação

• Créditos, franquia e rate limit: pesos por operação, franquia mensal, requisições por minuto, pacotes e GET /v1/usage.
• Erros e retentativas: envelope de erro, os códigos estáveis, Retry-After e quando repetir a chamada.
• Servidor MCP: configuração para Claude, Cursor, Windsurf e OpenAI, as quatro ferramentas e seus custos.

Dados e uso

• CNPJ alfanumérico: o novo formato, o dígito verificador e o que muda na API.
• Dados e frescor: de onde vêm os dados, o ciclo mensal e o que é derivado.
• Privacidade e uso aceitável: o que a API entrega, o que nunca entrega e o que você pode fazer com os contatos.

Mudanças

• Changelog: toda mudança na API, nas docs e na base, com data.
• Versionamento: o que é estável em /v1 e como uma mudança incompatível seria anunciada.

Por caso de uso

Guias por caso de uso e comparações com alternativas conhecidas.

• Para agentes

• Para automação

• Para CRM

• Para onboarding

• vs ReceitaWS

• vs BrasilAPI

Empresa e suporte

• Sobre: quem constrói o cnpj.ia.br e a relação com a Oportunidados.
• Segurança: como reportar uma vulnerabilidade, o que está no escopo e em quais idiomas.
• Contato: o canal de suporte e o que informar para acelerar o atendimento — a começar pelo request_id da resposta.

Arquivos de máquina

O contrato está em openapi.json (versão 1.0.0-draft.3). Há também uma coleção Postman, o llms.txt e a tabela de preços em Markdown. Toda página das docs tem uma versão em Markdown no mesmo endereço com .md no final.