Como consultar CNPJ via API em JavaScript.
Aprenda a consultar CNPJ via API em JavaScript com fetch: código pronto, leitura do JSON, tratamento de erros e boas práticas. API de CNPJ grátis, sem chave e sem cadastro.
Por que usar a API do openCNPJ em JavaScript
Com JavaScript, você pode consultar o CNPJ direto no navegador, por exemplo para preencher um formulário de cadastro enquanto o usuário digita, ou no servidor com Node.js. A API libera CORS, então não é preciso proxy.
- Grátis, sem chave de acesso e sem cadastro.
- Resposta em JSON com razão social, situação cadastral, endereço, CNAEs, sócios e Simples Nacional.
- Aceita o CNPJ numérico e o novo CNPJ alfanumérico.
- Limite de 10 requisições por segundo por IP.
O que você precisa
Um navegador moderno ou Node.js 18+, que já têm fetch nativo. Nenhuma biblioteca é necessária.
Consultar um CNPJ em JavaScript
O endpoint é GET https://api.opencnpj.com.br/cnpj/{cnpj}. Envie o CNPJ com 14 caracteres, sem pontos, barra ou hífen. O exemplo abaixo consulta o CNPJ 06.990.590/0001-23:
const cnpj = '06990590000123';
const resposta = await fetch(`https://api.opencnpj.com.br/cnpj/${cnpj}`);
if (!resposta.ok) {
throw new Error(`HTTP ${resposta.status}`);
}
const empresa = await resposta.json();
console.log(empresa.razao_social);
console.log(empresa.estabelecimento.situacao_cadastral);Funciona no navegador e no Node.js 18+ (fetch nativo).
Remover a máscara do CNPJ
Se o CNPJ vem formatado (06.990.590/0001-23) de um formulário, banco de dados ou planilha, limpe a pontuação antes de montar a URL. A mesma regra funciona para o CNPJ alfanumérico:
function limparCnpj(cnpj) {
return cnpj.replace(/[^0-9a-z]/gi, '').toUpperCase();
}
const cnpj = limparCnpj('06.990.590/0001-23'); // "06990590000123"
Campos mais usados da resposta
| Campo | Conteúdo |
|---|---|
razao_social | Nome empresarial |
estabelecimento.nome_fantasia | Nome fantasia |
estabelecimento.situacao_cadastral | Ativa, Suspensa, Inapta, Baixada ou Nula |
estabelecimento.atividade_principal | CNAE principal, com código e descrição |
estabelecimento.cidade.nome e estabelecimento.estado.sigla | Município e UF |
estabelecimento.cep, logradouro, numero, bairro | Endereço |
simples.simples e simples.mei | Opção pelo Simples Nacional e MEI |
socios | Quadro de sócios e administradores |
A lista completa de campos está na documentação da API.
Tratando erros
Verifique o status HTTP antes de ler o JSON. JavaScript: use resposta.status.
| Status | O que significa | O que fazer |
|---|---|---|
200 | CNPJ encontrado | Ler o JSON |
400 | Formato de CNPJ inválido | Conferir os 14 caracteres |
404 | CNPJ não encontrado na base | Informar ao usuário |
429 | Limite de requisições excedido | Aguardar e tentar de novo |
500 | Erro interno | Tentar novamente mais tarde |
Os erros também vêm em JSON, com os campos status, titulo e detalhes.
Boas práticas
- Defina um timeout na requisição, por exemplo com um
AbortSignal.timeout(10000)nofetch. - Guarde o resultado em cache se o mesmo CNPJ for consultado com frequência.
- Em processamentos em lote, respeite o limite de 10 requisições por segundo.
- Os dados refletem a base pública mais recente processada e não substituem certidões oficiais.
Perguntas frequentes
A API de CNPJ do openCNPJ é gratuita?
Sim, 100% grátis. Não há chave de acesso nem cadastro. O limite é de 10 requisições por segundo por IP.
Posso chamar a API de CNPJ direto do navegador?
Sim. A API responde com Access-Control-Allow-Origin: *, então o fetch funciona em qualquer site, sem proxy e sem chave exposta (não há chave).
Funciona com TypeScript, React ou Vue?
Sim. O código é o mesmo: um fetch para https://api.opencnpj.com.br/cnpj/{cnpj}. Em TypeScript, crie uma interface com os campos que você usa, como razao_social e estabelecimento.
De onde vêm os dados do CNPJ?
Dos dados abertos do CNPJ publicados pela Receita Federal, complementados por bases públicas. Os dados podem ter defasagem e não substituem certidões oficiais. Veja a origem dos dados.