Como consumir a API de CNPJ em Node.js?

Prepare o ambiente

Use Node.js 22 ou superior. Crie uma pasta de exemplo e prepare o cliente HTTP.

1# fetch já está disponível no Node.js 22; nenhuma dependência adicional.

Configure chave e projeto

Crie uma chave de Desenvolvimento no painel. O ping deste guia usa dev_mode=true: simula a resposta sem cobrança. A chave pública identifica sua integração; o segredo fica em uma variável de ambiente no servidor.

Defina as três variáveis no ambiente do terminal. Os valores abaixo são marcadores: substitua pela sua chave e pelo identificador real do projeto.

1$env:AFD_PUBLIC_KEY="afd_test_pk_..."
2$env:AFD_SECRET_KEY="seu_segredo_de_desenvolvimento"
3$env:AFD_PROJECT_ID="proj_..."

1export AFD_PUBLIC_KEY="afd_test_pk_..."
2export AFD_SECRET_KEY="seu_segredo_de_desenvolvimento"
3export AFD_PROJECT_ID="proj_..."

A autenticação HTTP Basic codifica public_key:secret_key em Base64. O cabeçalho X-Project-Id seleciona o projeto. Na consulta pública de CNPJ, nenhum desses cabeçalhos é necessário.

Execute a primeira chamada

Salve o exemplo em integracao.mjs. Ele faz duas chamadas: primeiro o ping autenticado em DEV; depois a consulta real e aberta do CNPJ de exemplo.

1import { randomUUID } from "node:crypto";
2
3async function read(response) {
4  const payload = await response.json();
5  if (!response.ok || !payload.success) {
6    throw new Error(JSON.stringify({ http: response.status,
7      codes: (payload.errors || []).map(e => e.code),
8      retryAfter: response.headers.get("Retry-After") }));
9  }
10  return payload;
11}
12const { AFD_PUBLIC_KEY, AFD_SECRET_KEY, AFD_PROJECT_ID } = process.env;
13if (!AFD_PUBLIC_KEY || !AFD_SECRET_KEY || !AFD_PROJECT_ID) {
14  throw new Error("Configure as três variáveis de ambiente.");
15}
16const operationKey = randomUUID();
17const ping = await fetch("https://api.apifordevs.com/api/v1/ping/billable?dev_mode=true", {
18  headers: {
19    Authorization: "Basic " + Buffer.from(AFD_PUBLIC_KEY + ":" + AFD_SECRET_KEY).toString("base64"),
20    "X-Project-Id": AFD_PROJECT_ID,
21    "Idempotency-Key": operationKey,
22  }, signal: AbortSignal.timeout(30000),
23});
24console.log(await read(ping));
25// Consulta real, pública e sem autenticação.
26const response = await fetch("https://api.apifordevs.com/api/v1/cnpj/00000000007951", { signal: AbortSignal.timeout(30000) });
27console.log((await read(response)).data[0]);

1node integracao.mjs

Leia a resposta e os erros

O envelope inclui success, code, errors, header, data_count e data. No CNPJ, o primeiro resultado fica em data[0]. Confira found e reference_month antes de usar os campos.

Trate o status HTTP e errors[].code. Um CNPJ inválido retorna erro de validação; um CNPJ fora da base pode responder com sucesso e found: false. Ao receber HTTP 429, aguarde o período indicado em Retry-After. Não repita erros de validação sem corrigir a entrada.

Repita com segurança

O exemplo cria uma chave de operação. Nos endpoints que aceitam Idempotency-Key, reutilize o mesmo valor ao repetir a mesma operação lógica após uma falha de conexão. Uma operação nova recebe outra chave. Confira no detalhe do endpoint a janela e o comportamento de idempotência; o cabeçalho não transforma uma API sem suporte em idempotente.

Para testar esse comportamento, mantenha o valor de operationKey ou operation_key entre duas tentativas da mesma requisição. Não gere outro UUID dentro do loop de repetição. Respeite os limites mesmo quando repetir a operação.