API consulta CNPJ e dados abertos da Receita Federal

Quem precisa consultar CNPJ em escala - validar cadastro de clientes, enriquecer um CRM, alimentar um antifraude - cedo ou tarde busca uma api consulta cnpj. Antes de escolher um provedor, vale entender de onde os dados vêm: praticamente todas as APIs do mercado, gratuitas ou pagas, começam nos mesmos arquivos públicos que a Receita Federal libera todo mês.

Esta página explica os dados abertos cnpj, o layout dos arquivos, como montar sua própria base, quais são as opções de API pública, o formato do JSON devolvido e as boas práticas que evitam bloqueio por excesso de requisições. Se você só precisa de uma consulta pontual, use a ferramenta no topo desta página.

O que são os dados abertos do CNPJ

O Cadastro Nacional da Pessoa Jurídica é um registro público. Por determinação legal, boa parte das informações cadastrais das empresas brasileiras é de divulgação obrigatória - razão social, endereço, atividade econômica, natureza jurídica, situação cadastral e composição societária das pessoas jurídicas. A Receita Federal cumpre essa obrigação publicando o cadastro inteiro em arquivos abertos, sem necessidade de login, contrato ou pagamento.

Esses arquivos são a matéria-prima de todo o ecossistema de consulta de CNPJ no Brasil. Sites de consulta, plataformas de crédito, ferramentas de prospecção e integrações internas de empresas partem da mesma fonte. A diferença entre eles está em três coisas: com que frequência recarregam, como normalizam os campos e o que entregam por cima do dado bruto.

Por que isso importa para a sua integração

Se o seu caso de uso é conferir se um fornecedor existe e qual é o CNAE dele, a defasagem mensal é irrelevante. Se o caso de uso é bloquear pagamento a empresa com CNPJ baixado ontem, a defasagem é fatal. Definir a tolerância a atraso é a primeira decisão de arquitetura, antes de escolher provedor ou escrever qualquer linha de código.

Arquivos mensais e volume de dados

A publicação segue um ciclo mensal e é organizada em conjuntos de arquivos compactados. Cada conjunto é quebrado em vários pedaços numerados, porque um único arquivo com dezenas de milhões de linhas seria inviável de baixar. Os dados vêm em csv delimitado, com codificação latina e sem cabeçalho - o nome das colunas está no dicionário de dados, não no arquivo.

Somados, os arquivos passam de 85 GB descompactados. Compactados ocupam uma fração disso, mas o download completo ainda leva horas em conexões domésticas e o processo de descompactação é sensível a disco lento. Planeje a janela de carga com folga: quem tenta importar tudo em uma madrugada costuma descobrir que precisa de duas.

Layout das tabelas do cadastro

Entender o layout é o que separa uma importação que funciona de um amontoado de colunas desalinhadas. A estrutura gira em torno de uma chave simples: os oito primeiros dígitos do CNPJ, a chamada raiz ou CNPJ básico. Empresa, sócios e opção pelo Simples são registrados por raiz. Já os estabelecimentos são registrados pela combinação de raiz, ordem e dígito verificador - que juntos formam o CNPJ de catorze dígitos.

Empresas

• CNPJ básico - a raiz de oito dígitos, chave de ligação;
• Razão social ou nome empresarial;
• Código da natureza jurídica, que remete à tabela auxiliar;
• Qualificação do responsável;
• Capital social declarado, em valor numérico;
• Porte da empresa, em código: micro, pequeno, demais;
• Ente federativo responsável, preenchido apenas para órgãos públicos.

Estabelecimentos

É o arquivo mais rico e o mais pesado. Traz o identificador de matriz ou filial, nome fantasia, código e data da situacao cadastral, motivo da situação, data de início da atividade, cnae fiscal principal, lista de CNAEs secundários separados por vírgula, endereço completo com CEP e código de município, dois telefones, fax, endereço eletrônico de contato e a situação especial, quando existe.

Um detalhe que derruba muita importação: a coluna de CNAEs secundários pode conter centenas de códigos concatenados na mesma célula. Trate esse campo como lista, não como número, e normalize para uma tabela filha se você pretende filtrar por atividade secundária. A leitura desses códigos está explicada em detalhe no guia de consulta de CNAE.

Sócios

Cada linha representa um integrante do qsa - o quadro societário e de administradores. Traz o identificador do tipo de sócio, nome ou razão social, documento parcialmente mascarado, código de qualificação, data de entrada na sociedade, país, representante legal e faixa etária. O detalhamento de como interpretar essas qualificações está na página de quadro societário.

Simples e SIMEI

Tabela enxuta e muito útil: informa se a raiz é optante pelo simples nacional, com data de opção e de exclusão, e se é optante pelo simei, o regime de recolhimento do microempreendedor individual. É por essa tabela que se identifica com segurança um CNPJ de MEI, assunto tratado na página de consulta MEI.

Tabelas auxiliares

São arquivos pequenos de domínio: CNAE, município, país, natureza jurídica, qualificação de sócio e motivo de situação cadastral. Sem eles você só tem números. Carregue-as primeiro e transforme em tabelas de lookup no banco - a junção fica trivial e a API devolve descrições legíveis em vez de códigos.

API consulta CNPJ: as opções públicas

Quem pesquisa por consulta cnpj api encontra dezenas de endereços prometendo o mesmo dado. Na prática existem apenas três arquiteturas por trás de todos eles, e entender qual você está usando evita surpresa em produção.

Existem hoje três caminhos para obter dados de CNPJ por HTTP, e a escolha depende de volume, criticidade e orçamento.

Como funcionam as APIs públicas gratuitas

Uma api consulta cnpj gratuita típica é um serviço rest que recebe o número do CNPJ na própria URL e devolve um objeto JSON. Não exige chave de acesso, aceita apenas o método GET e impõe um limite de chamadas por minuto por endereço IP. É simples de integrar e perfeita para começar - desde que você aceite três limitações estruturais.

• Sem garantia de disponibilidade. São serviços mantidos de forma voluntária ou como vitrine de um produto pago. Podem sair do ar sem aviso;
• Limite de requisições baixo. Faixas de três a sessenta chamadas por minuto são comuns. Uma carga de dez mil CNPJs pode levar horas;
• Defasagem dos dados. Herdada da publicação mensal, com raras exceções que consultam a fonte ao vivo.

Exemplo de chamada e resposta JSON

O formato mais comum de uma api de consulta cnpj é um recurso REST com o número na URL, sem pontuação. A chamada é um GET simples sobre http, sem corpo e sem credenciais:

GET https://api.exemplo.com.br/cnpj/00000000000191
Accept: application/json
User-Agent: minha-aplicacao/1.0 ([email protected])

A resposta de um json consulta cnpj segue, em linhas gerais, este desenho - os nomes mudam de provedor para provedor, mas o conteúdo é o mesmo do cadastro:

{
  "cnpj": "00000000000191",
  "razao_social": "EMPRESA EXEMPLO S.A.",
  "nome_fantasia": "EXEMPLO",
  "matriz_filial": "MATRIZ",
  "situacao_cadastral": "ATIVA",
  "data_situacao_cadastral": "2005-11-03",
  "motivo_situacao_cadastral": "SEM MOTIVO",
  "data_inicio_atividade": "1966-08-15",
  "natureza_juridica": "2038 - Sociedade de Economia Mista",
  "porte": "DEMAIS",
  "capital_social": 90000000000.00,
  "cnae_principal": {
    "codigo": "6422100",
    "descricao": "Bancos multiplos, com carteira comercial"
  },
  "cnaes_secundarios": [
    { "codigo": "6499999", "descricao": "Outras atividades de servicos financeiros" }
  ],
  "endereco": {
    "logradouro": "SETOR BANCARIO SUL QUADRA 1",
    "numero": "S/N",
    "complemento": "BLOCO A",
    "bairro": "ASA SUL",
    "cep": "70073900",
    "municipio": "BRASILIA",
    "uf": "DF"
  },
  "telefone": "6134939002",
  "email": "[email protected]",
  "simples": { "optante": false, "data_opcao": null },
  "simei":   { "optante": false, "data_opcao": null },
  "qsa": [
    { "nome": "FULANO DE TAL", "qualificacao": "Diretor", "data_entrada": "2023-04-01" }
  ],
  "atualizado_em": "2026-07-01"
}

Campos retornados e o que fazer com eles

Como montar sua própria base

Se o volume passa de alguns milhares de consultas por dia, ou se você precisa filtrar por CNAE, por município ou por nome, deixar de depender de terceiros compensa. O processo é um etl clássico: extrair os arquivos, transformar os códigos em descrições e carregar tudo em um banco relacional. Postgresql é a escolha mais comum pelo comando de carga em massa e pelos índices parciais.

Roteiro resumido

1. Baixe os arquivos do mês corrente e registre a data de publicação em uma tabela de controle;
2. Descompacte em uma área de staging - não no volume do banco;
3. Carregue as tabelas auxiliares primeiro; elas são pequenas e validam o encoding;
4. Carregue empresas, estabelecimentos, sócios e Simples com tudo como texto, sem índice;
5. Converta tipos em uma segunda passada: datas, valor de capital, códigos numéricos;
6. Crie os índices por CNPJ completo, raiz, CNAE principal, município e situação;
7. Normalize os CNAEs secundários em tabela filha, se for filtrar por eles;
8. Faça a troca atômica: carregue em esquema novo e renomeie ao final, para não deixar a API fora do ar.

Custo real de manter a base

Disco é o item óbvio, mas o custo escondido é operacional: alguém precisa acompanhar a publicação mensal, tratar mudanças de layout, monitorar a carga e validar totais. Times pequenos frequentemente começam com base própria e voltam para API paga depois de duas ou três recargas problemáticas. Faça a conta considerando as horas, não só a infraestrutura.

Boas práticas de integração

Cache em camadas

Dado de CNPJ muda pouco. Guardar a resposta por um período longo é a otimização de maior impacto em qualquer integração:

• Cache de aplicação em memória, para os CNPJs consultados repetidamente na mesma sessão;
• Cache persistente em banco ou armazenamento de chave e valor, com validade medida em dias ou semanas;
• Cache negativo para CNPJ inexistente, com validade menor - o número pode ser atribuído no futuro.

Respeitar o rate limit

• Enfileire as chamadas em vez de disparar tudo em paralelo;
• Limite a concorrência a um valor fixo e conservador;
• Ao receber HTTP 429, espere com recuo exponencial e um pouco de aleatoriedade;
• Respeite o cabeçalho Retry-After quando o provedor enviar;
• Identifique-se no User-Agent com nome da aplicação e contato.

Validar antes de chamar

Todo CNPJ tem dois dígitos verificadores calculáveis localmente. Rodar essa verificação antes da chamada elimina digitação errada sem gastar cota. A lógica está explicada na página do validador de CNPJ.

Processamento assíncrono

Para lotes, use fila e retorne ao usuário um identificador de processamento, não a resposta síncrona. Se o seu sistema precisa avisar outro serviço ao terminar, um webhook de conclusão é mais eficiente que fazer o cliente ficar consultando o status em laço.

Tratamento de erros e de CNPJ inexistente

CNPJ inexistente não é sempre inexistente

Um 404 em base derivada dos dados abertos pode significar simplesmente que o CNPJ foi criado depois da última extração mensal. Empresas abertas nas últimas semanas caem nessa categoria com frequência. Se a decisão do seu sistema depende disso, ofereça ao usuário um caminho de conferência manual em vez de recusar o cadastro de imediato - e explique a defasagem na mensagem de erro.

Uso comercial e licenciamento

Os dados do CNPJ são públicos e sua divulgação é obrigatória por lei. Na prática, isso permite reutilização ampla, inclusive comercial: consolidar, enriquecer, revender acesso e distribuir em produtos. Ainda assim, há limites que valem atenção.

• Não simule vínculo oficial. Deixe claro que o serviço é independente e que a fonte é a base pública. Este site, por exemplo, não tem qualquer vínculo com a Receita Federal;
• Cite a origem e a data. Publicar a data de extração é boa prática e reduz reclamação sobre dado desatualizado;
• Cuidado com pessoa física. Nomes de sócios são dados pessoais. A lgpd se aplica ao tratamento, mesmo que a origem seja pública: registre a finalidade, limite a retenção e atenda a pedidos de titulares;
• Não reconstitua documentos oficiais. Reproduzir a aparência de um comprovante de inscrição pode induzir a erro. Explique como emitir no portal oficial em vez de imitar o documento.

Alternativas pagas

Quando a operação é crítica, o caminho gratuito deixa de servir. As opções pagas se dividem em três perfis:

Como escolher

1. Estime o volume mensal real, não o de pico imaginado;
2. Defina a tolerância a defasagem em dias;
3. Verifique se você precisa de busca por nome ou só por número;
4. Teste a resposta com CNPJs conhecidos, incluindo empresas baixadas e filiais;
5. Confira o que acontece quando o provedor fica fora do ar - e tenha um plano B.

Perguntas frequentes