Consultar CNPJ por API é tarefa básica de quase todo sistema B2B brasileiro: validação de cadastro, emissão de NF-e, análise de fornecedor, KYC em fintechs. O problema é escolher entre as opções disponíveis — cada uma com limites, dados e políticas de uso diferentes. Este guia compara as 8 principais APIs de consulta de CNPJ em 2026, com exemplos de código em PHP, Python e JavaScript, validação de dígito verificador e estratégias para lidar com rate limit em produção.
O que é uma API de consulta de CNPJ?
Uma API de consulta de CNPJ é um webservice que recebe um número de CNPJ via requisição HTTP e retorna os dados cadastrais da empresa em JSON: razão social, situação na Receita Federal, endereço, CNAEs, quadro societário e regime tributário. Em vez de acessar o site da Receita e resolver CAPTCHA, sua aplicação consulta os dados de forma automatizada, em milissegundos.
Os dados têm origem na base pública de CNPJ da Receita Federal, que é disponibilizada em arquivos abertos. Cada provedor processa, indexa e atualiza essa base com frequência própria. É aí que as diferenças entre os serviços aparecem.
Quais dados uma API de CNPJ retorna
- Identificação: razão social, nome fantasia, data de abertura, porte
- Situação cadastral: ativa, suspensa, inapta ou baixada, com data e motivo
- Endereço completo: logradouro, número, bairro, município, UF e CEP
- Atividades: CNAE principal e secundários com descrição
- Quadro societário (QSA): sócios, qualificação e CPF parcial
- Natureza jurídica e capital social: LTDA, SA, MEI, EI, com valor declarado
- Regime tributário: opção pelo Simples Nacional e MEI, com datas
- Situação especial: recuperação judicial, falência ou liquidação, quando houver
Nem todo provedor entrega tudo. Simples Nacional, Inscrição Estadual (Sintegra) e dados de contato costumam ficar nos planos pagos. Verifique o payload de exemplo na documentação antes de fechar a escolha.
As 8 principais APIs de CNPJ comparadas
| API | Limite gratuito | Autenticação | Simples/IE | Plano pago |
|---|---|---|---|---|
| Hub do Desenvolvedor | teste grátis | token | ✅ incluso | 20+ APIs num plano único |
| ReceitaWS | 3 req/min | nenhuma (free) | pago | a partir de planos mensais |
| BrasilAPI | uso razoável | nenhuma | ❌ | não há |
| CNPJá | 5 req/min | nenhuma (open) | pago | por volume + dados extras |
| minhaReceita | ilimitado (self-host) | você define | ❌ | open source, sua infra |
| OpenCNPJ | uso razoável | nenhuma | ❌ | não há |
| CNPJ.ws | 3 req/min | nenhuma (pública) | pago | até 2.000 req/min |
| Serpro | — | OAuth2 | ✅ | oficial, cobrança por consulta |
Hub do Desenvolvedor
A API de CNPJ do Hub do Desenvolvedor retorna o cadastro completo, incluindo Simples Nacional e quadro societário, e faz parte de um catálogo com mais de 20 webservices (CPF, CEP, frete, DDD) acessados com a mesma credencial. Pra quem precisa de mais de uma consulta no mesmo sistema, o custo consolidado costuma ser menor do que contratar provedores separados.
ReceitaWS
Veterana do mercado, tem endpoint gratuito sem autenticação limitado a 3 requisições por minuto. Serve bem pra protótipos. Em produção, o limite obriga fila ou upgrade pro plano comercial.
BrasilAPI
Projeto open source mantido pela comunidade que agrega CEP, CNPJ, bancos e feriados. A rota /api/cnpj/v1/{cnpj} usa a base do projeto minhaReceita. Gratuita e sem autenticação, mas sem SLA. Evite usá-la como fonte única em fluxo crítico.
CNPJá
A API aberta atende 5 consultas por minuto sem cadastro. Os planos pagos agregam dados que poucos têm: Sintegra (IE), SUFRAMA, comprovante de inscrição em PDF e geocodificação do endereço.
minhaReceita
Solução open source pra rodar na sua infraestrutura: um container Docker que baixa a base pública da Receita e expõe uma API HTTP. Sem limite de requisições e sem dependência de terceiros, em troca do trabalho de manter a base atualizada (a Receita publica novos arquivos mensalmente).
OpenCNPJ
Alternativa gratuita e sem autenticação, com proposta parecida com a do OpenCEP: simplicidade e resposta direta da base pública. Boa opção de fallback.
CNPJ.ws
A API pública permite 3 consultas por minuto. A versão comercial escala até 2.000 requisições por minuto com filtros por CNAE, UF e situação cadastral, úteis pra enriquecimento de bases grandes.
Serpro
É a opção oficial do governo, com dados direto da fonte. Autenticação OAuth2 e cobrança por consulta. Faz sentido quando o requisito é compliance estrito ou contrato com órgão público.
Como consultar CNPJ via API na prática
Os exemplos abaixo usam a BrasilAPI por não exigir token, mas a estrutura é a mesma em qualquer provedor: GET com o CNPJ na URL, resposta em JSON.
JavaScript (fetch)
const cnpj = '19131243000197'; // só dígitos
const res = await fetch(`https://brasilapi.com.br/api/cnpj/v1/${cnpj}`);
if (!res.ok) throw new Error(`Consulta falhou: ${res.status}`);
const empresa = await res.json();
console.log(empresa.razao_social, empresa.descricao_situacao_cadastral);Python (requests)
import requests
def consultar_cnpj(cnpj: str) -> dict:
cnpj = ''.join(filter(str.isdigit, cnpj))
r = requests.get(f'https://brasilapi.com.br/api/cnpj/v1/{cnpj}', timeout=5)
r.raise_for_status()
return r.json()
empresa = consultar_cnpj('19.131.243/0001-97')
print(empresa['razao_social'], empresa['cnae_fiscal_descricao'])PHP (cURL)
$cnpj = preg_replace('/\D/', '', '19.131.243/0001-97');
$ch = curl_init("https://brasilapi.com.br/api/cnpj/v1/{$cnpj}");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$resposta = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 200) {
throw new Exception("Consulta falhou: HTTP {$status}");
}
$empresa = json_decode($resposta, true);
echo $empresa['razao_social'];Em todos os casos, trate o 404 (CNPJ não encontrado) e o 429 (limite excedido) de forma distinta: o primeiro é resposta definitiva, o segundo pede nova tentativa depois de aguardar.
Valide o CNPJ antes de consultar
CNPJ com dígito verificador errado nunca vai existir na base. Validar localmente antes da requisição elimina chamadas perdidas e dá feedback imediato no formulário:
function validarCNPJ(cnpj) {
cnpj = cnpj.replace(/\D/g, '');
if (cnpj.length !== 14 || /^(\d)\1{13}$/.test(cnpj)) return false;
const calcDV = (base) => {
let peso = base.length - 7, soma = 0;
for (const d of base) {
soma += d * peso--;
if (peso < 2) peso = 9;
}
const resto = soma % 11;
return resto < 2 ? 0 : 11 - resto;
};
const dv1 = calcDV(cnpj.slice(0, 12));
const dv2 = calcDV(cnpj.slice(0, 12) + dv1);
return cnpj.endsWith(`${dv1}${dv2}`);
}Atenção: o CNPJ alfanumérico chegou
A partir de julho de 2026, a Receita Federal passa a emitir CNPJs alfanuméricos: os 12 primeiros caracteres podem conter letras e números, e os 2 dígitos verificadores continuam numéricos. O cálculo do DV muda pouco: cada caractere é convertido pelo código ASCII menos 48 (assim "A" vale 17) e o resto do algoritmo permanece. Se o seu sistema valida CNPJ com regex ^\d{14}$, ele vai rejeitar cadastros legítimos. Revise validações, máscaras de input e colunas numéricas no banco de dados antes da virada.
Rate limit, cache e retry em produção
Três práticas resolvem a maior parte dos problemas de integração com APIs de CNPJ:
- Cache com TTL longo: dados cadastrais mudam pouco. Guardar a resposta por 7 a 30 dias (Redis ou tabela local) corta a maioria das consultas repetidas, algo comum quando o mesmo cliente edita o cadastro várias vezes.
- Fila com controle de vazão: pra enriquecer uma base com milhares de CNPJs numa API de 3 req/min, processe via fila respeitando o limite, em vez de disparar tudo e colecionar erros 429.
- Retry com backoff exponencial: em falha de rede ou 429, espere 1s, depois 2s, 4s, com limite de tentativas. Honre o header
Retry-Afterquando a API enviar.
Um padrão que funciona bem é o mesmo usado com APIs de CEP: definir uma fonte primária e uma de fallback. Se a primária retornar erro ou estourar o tempo limite, a consulta cai pra segunda fonte antes de falhar pro usuário.
API gratuita ou paga: quando migrar
APIs gratuitas atendem bem protótipos, projetos pessoais e validações esporádicas. Os sinais de que chegou a hora de migrar pra um plano pago são concretos:
- Volume acima de algumas centenas de consultas por dia, onde 3-5 req/min viram gargalo
- Consulta dentro de fluxo crítico (checkout, emissão de NF-e, abertura de conta), onde indisponibilidade custa venda
- Necessidade de Simples Nacional, Inscrição Estadual ou comprovantes pra compliance
- Exigência de SLA e suporte, coisa que APIs comunitárias não oferecem
O custo de entrada é baixo: planos profissionais partem de algumas dezenas de reais por mês, menos do que uma hora de retrabalho causada por cadastro errado.
Perguntas frequentes
Existe API gratuita da Receita Federal pra consultar CNPJ?
A Receita Federal não oferece API pública gratuita de consulta individual. O que existe é a base de dados abertos de CNPJ, publicada em arquivos mensais, que serviços como BrasilAPI, minhaReceita e OpenCNPJ processam e expõem via API. A opção oficial paga é a API do Serpro.
Qual o limite das APIs gratuitas de CNPJ?
ReceitaWS e CNPJ.ws limitam a 3 requisições por minuto no plano gratuito; a CNPJá permite 5. BrasilAPI e OpenCNPJ não publicam limite fixo, mas bloqueiam abuso. Pra volume contínuo, a alternativa é plano pago ou hospedar o minhaReceita na sua infraestrutura.
Como consultar Simples Nacional e Inscrição Estadual via API?
Simples Nacional vem incluso em provedores como o Hub do Desenvolvedor e nos planos pagos da ReceitaWS e CNPJá. Inscrição Estadual (Sintegra) é mais restrita: poucos provedores cobrem todos os estados, e o dado costuma ser cobrado à parte.
Posso usar API de CNPJ em projeto comercial?
Sim, mas leia a política de cada serviço. As APIs comunitárias gratuitas aceitam uso comercial moderado e proíbem revenda dos dados. Pra produto com volume, o plano pago elimina a zona cinzenta e garante suporte.
Qual a diferença entre ReceitaWS, BrasilAPI e a API do Hub do Desenvolvedor?
ReceitaWS é serviço dedicado a CNPJ com free tier de 3 req/min. BrasilAPI é projeto open source gratuito que agrega várias APIs brasileiras, sem SLA. O Hub do Desenvolvedor é serviço pago que reúne CNPJ com Simples Nacional e mais de 20 outras APIs (CPF, CEP, frete) numa única credencial e plano.
Conclusão
A escolha da API de CNPJ depende do estágio do projeto: BrasilAPI ou OpenCNPJ pra começar sem fricção, minhaReceita pra quem quer independência total, e um provedor com SLA quando a consulta entra no caminho crítico do negócio. Em qualquer cenário, valide o CNPJ localmente (já preparado pro formato alfanumérico de 2026), implemente cache com TTL longo e trate 429 com backoff. São três medidas simples que separam uma integração frágil de uma que aguenta produção.
