Começar agora

1. Obtenha uma chave

O fluxo comercial de emissão de chaves ainda está a confirmar. Enquanto ele não estiver disponível, a equipe operadora cria a chave e a entrega uma única vez por canal seguro. Nunca envie chaves por issue, commit ou log.

Salve a credencial em uma variável de ambiente:

export CNPJ_API_KEY='cnpj_live_SUBSTITUA'
export CNPJ_API_BASE_URL='https://api.seudominio.com'

Para desenvolvimento local, use http://localhost:8000 como URL base e uma chave de ambiente development, quando API_REQUIRE_KEY=true.

2. Faça a primeira chamada

O CNPJ deve conter 14 dígitos sem pontuação. Este exemplo usa o endpoint real de perfil cadastral:

curl --fail-with-body \
  "$CNPJ_API_BASE_URL/v1/cnpjs/00000000000191" \
  -H "X-API-Key: $CNPJ_API_KEY"

Python

import os
import requests

base_url = os.environ["CNPJ_API_BASE_URL"]
api_key = os.environ["CNPJ_API_KEY"]

response = requests.get(
    f"{base_url}/v1/cnpjs/00000000000191",
    headers={"X-API-Key": api_key},
    timeout=10,
)
response.raise_for_status()
perfil = response.json()
print(perfil["empresa"]["razao_social"])

JavaScript / TypeScript

const baseUrl = process.env.CNPJ_API_BASE_URL!;
const apiKey = process.env.CNPJ_API_KEY!;

const response = await fetch(`${baseUrl}/v1/cnpjs/00000000000191`, {
  headers: { 'X-API-Key': apiKey },
  signal: AbortSignal.timeout(10_000),
});

if (!response.ok) {
  throw new Error(`CNPJ API: ${response.status} ${await response.text()}`);
}

const perfil = await response.json();
console.log(perfil.empresa.razao_social);

Não coloque uma chave secreta em código executado no navegador. Em frontend, faça a chamada por um backend sob seu controle.

3. Interprete a resposta

{
  "cnpj": "00000000000191",
  "empresa": {
    "cnpj_basico": "00000000",
    "razao_social": "...",
    "porte_empresa": "..."
  },
  "estabelecimento": {
    "cnpj_completo": "00000000000191",
    "situacao_cadastral": "...",
    "cnae_fiscal_principal": "...",
    "uf": "DF"
  },
  "simples": null,
  "resumos": {
    "estabelecimentos": {
      "total": 1,
      "href": "/v1/cnpjs/00000000000191/estabelecimentos"
    }
  },
  "fontes": {
    "cnpj": { "status": "disponivel", "versao": "..." }
  },
  "snapshot_fingerprint": "..."
}

empresa representa a raiz de oito dígitos;
estabelecimento representa o CNPJ completo consultado;
simples pode ser null;
resumos aponta para as coleções relacionadas;
fontes informa disponibilidade e versão do snapshot;
snapshot_fingerprint muda quando as versões publicadas mudam.

4. Evolua a integração

Use ETag/If-None-Match, trate 429 com espera indicada por Retry-After e diferencie uma lista vazia de fonte.status: "indisponivel". Veja erros, paginação e boas práticas.