Tutoriais

Como consultar CNPJ em JavaScript e TypeScript

Um fetch para cnpj.wortic.com/cnpj/{numero} traz a ficha da empresa em JSON, sem biblioteca e sem chave, no Node.js, no Next.js, no Deno, no Bun e no navegador.

Por Equipe Wortic 5 min de leitura
Mãos digitando em um notebook ao lado de uma xícara de café, em uma mesa de madeira

Para consultar um CNPJ em JavaScript ou TypeScript, chame fetch("https://cnpj.wortic.com/cnpj/" + cnpj) e leia o JSON da resposta. Não precisa de biblioteca, cadastro nem chave: o fetch já vem no Node.js a partir da versão 18, no Deno, no Bun e em todos os navegadores. A API é a da Wortic, gratuita, com os dados abertos do CNPJ publicados pela Receita Federal e 60 consultas por minuto por IP.

O exemplo mínimo

Este código roda como está num arquivo .mjs do Node.js ou num componente de servidor do Next.js:

const resposta = await fetch("https://cnpj.wortic.com/cnpj/37853407000171");
const empresa = await resposta.json();
console.log(empresa.razao_social, empresa.situacao.descricao);

A resposta traz razão social, nome fantasia, situação na Receita com a data de início, abertura, atividade principal e secundárias (CNAE), natureza jurídica, porte, capital social, Simples, MEI, endereço com o código IBGE da cidade, telefone e e-mail públicos. O CNPJ pode ir com ou sem pontuação, e o formato alfanumérico, com letras, também é aceito.

A versão em TypeScript, pronta para produção

Num projeto de verdade vale tipar a resposta e tratar o limite. Esta função faz as duas coisas e foi testada contra a API:

type Empresa = {
  cnpj: string;
  razao_social: string;
  nome_fantasia: string;
  situacao: { codigo: number; descricao: string; desde: string };
  cnae_principal: { codigo: string; descricao: string };
};

const API = "https://cnpj.wortic.com/cnpj/";

export async function consultarCnpj(cnpj: string): Promise<Empresa> {
  const resposta = await fetch(API + encodeURIComponent(cnpj));
  if (resposta.status === 429) {
    const espera = resposta.headers.get("retry-after") ?? "60";
    throw new Error(`Limite atingido: tente de novo em ${espera} s`);
  }
  if (!resposta.ok) {
    const { erro } = await resposta.json();
    throw new Error(erro?.mensagem ?? `HTTP ${resposta.status}`);
  }
  return resposta.json();
}

Quando o CNPJ tem dígito errado, a API responde 400 com o código cnpj_invalido. Quando o número é válido mas não está na base, responde 404 com nao_encontrado. Os dois erros chegam no mesmo formato, com erro.codigo e erro.mensagem, então a mesma função trata todos.

Autocompletar a empresa pelo nome

Quem não sabe o CNPJ digita o nome. A rota /empresas?nome=&uf= pede pelo menos 4 letras e devolve até 50 empresas ativas, cada uma com CNPJ, razão social, nome fantasia, cidade, estado e se é matriz:

const busca = new URLSearchParams({ nome: "magazine luiza", uf: "SP" });
const url = `https://cnpj.wortic.com/empresas?${busca}`;
const { empresas } = await (await fetch(url)).json();

Num campo de busca, espere a pessoa parar de digitar por uns 300 ms antes de chamar a API. Assim o formulário fica rápido e a conta fica longe do limite.

Next.js, Remix, Astro e React

Faça a consulta no servidor: num Route Handler ou numa Server Action do Next.js, num loader do Remix ou numa rota do Astro. O componente React recebe só os campos que vai mostrar. Isso guarda a chave fora do navegador quando você passar a usar a do plano e deixa a resposta pronta para o cache do próprio framework.

A resposta já diz por quanto tempo pode ser guardada. Uma ficha consultada hoje não precisa ser consultada de novo daqui a cinco minutos.

Quando 60 por minuto não bastam

Sem chave, cada IP faz 60 consultas por minuto, e quem insiste acima disso é bloqueado por um tempo que cresce. Quem assina a Wortic recebe uma chave com 1 milhão de consultas por mês em cada API, mandada no cabeçalho x-api-key. A mesma chave libera a busca avançada: empresas por atividade, estado, cidade, porte, capital, data de abertura e raio em quilômetros, com resposta em JSON, CSV ou jsonW.

Para guardar milhares de fichas no próprio sistema, o pacote @wortictecnologia/jsonw, com os tipos do TypeScript, grava as respostas num arquivo jsonW e busca por CNPJ em 0,196 ms num arquivo de 1 milhão de linhas.

Perguntas frequentes

Preciso instalar alguma biblioteca para consultar CNPJ em JavaScript?

Não. O fetch já vem no Node.js 18 em diante, no Deno, no Bun e nos navegadores. Basta chamar https://cnpj.wortic.com/cnpj/{numero}.

Como tratar o limite de consultas no código?

Quando a API responde 429, leia o cabeçalho retry-after e espere esse número de segundos antes de tentar de novo. Abaixo de 60 consultas por minuto por IP, o bloqueio não acontece.

Devo consultar a API pelo navegador ou pelo servidor?

Pelo servidor: Route Handler ou Server Action no Next.js, loader no Remix, rota no Astro. Assim a chave do plano nunca vai ao navegador e a resposta entra no cache do framework.

Fontes

Conheça: API de CNPJ grátis da Wortic.

Imagem: Foto de Pixabay no Pexels (https://www.pexels.com/license/).

Quer isso funcionando na sua empresa?

Um consultor da Wortic olha o seu caso e mostra o caminho, sem compromisso.

Falar com um consultor

Equipe editorial

Equipe editorial da Wortic especializada em automacao, IA, ERP, CRM e crescimento operacional.

  • Automacao com IA
  • Gestao empresarial
  • CRM
  • ERP
  • Marketing digital

Isso funcionando no seu negócio.

Um consultor mostra o sistema do seu ramo, com a IA dentro.