API de CNPJ para automação

Automação de cadastro, enriquecimento ou prospecção precisa de uma API que responda sempre no mesmo formato, cobre o que declarou e diga com clareza quando repetir. É isso: JSON com data e meta, custo em créditos conhecido antes da chamada, erros custam 0 e cada um traz retryable; o 429 traz Retry-After. Funciona em qualquer ferramenta que faça uma requisição HTTP: n8n, Make, Zapier, Pipedream ou um cron.

O fluxo em três passos

1. Guarde a chave como credencial

   No n8n, uma credencial Header Auth com Authorization: Bearer SUA_CHAVE. Nunca no corpo do fluxo, nunca em nó de código versionado.

   Authorization: Bearer cnpj_live_…

2. Um nó HTTP Request por operação

   GET /v1/cnpjs/{cnpj} para enriquecer um registro; GET /v1/cnpjs com filtros para descobrir empresas. O JSON volta com data e meta.

   GET https://api.cnpj.ia.br/v1/cnpjs/{{ $json.cnpj }}?profile=full

3. Trate os erros pelo código, não pelo texto

   Com a resposta completa ligada no nó, um IF sobre body.error.retryable decide entre repetir (esperando o header Retry-After, quando vier), corrigir o dado ou parar. Erros não consomem crédito.

   IF {{ $json.body.error.retryable }} → Wait {{ $json.headers['retry-after'] || 2 }}s → repetir

Configuração dos nós

Não há nó comunitário ainda; o nó HTTP Request resolve. Os blocos abaixo são os parâmetros a preencher no nó, não um export importável. Make e Zapier funcionam pelo módulo HTTP de cada um, com a chave guardada como conexão.

{
  "node": "HTTP Request",
  "method": "GET",
  "url": "https://api.cnpj.ia.br/v1/cnpjs/{{ $json.cnpj }}",
  "queryParameters": { "profile": "full" },
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "headerAuth": { "name": "Authorization", "value": "Bearer <credencial>" }
}

{
  "node": "HTTP Request",
  "method": "GET",
  "url": "https://api.cnpj.ia.br/v1/cnpjs",
  "queryParameters": {
    "uf": "PR", "municipio": "4106902", "cnae": "1091102",
    "situacao": "ATIVA", "simples": "true",
    "cursor": "{{ $json.meta.next_cursor }}"
  },
  "pagination": { "stopWhen": "{{ $response.body.meta.next_cursor === null }}" }
}

Módulo HTTP → Make a request
URL:    https://api.cnpj.ia.br/v1/cnpjs/{cnpj}?profile=basic
Método: GET
Header: Authorization: Bearer <chave guardada como conexão>
Parse:  JSON → data.razao_social, data.situacao_cadastral.descricao, meta.data_as_of

Campos mais usados

Regras que evitam surpresa no fluxo

• Paginação da busca: repita com cursor = meta.next_cursor até vir null; mudar um filtro invalida o cursor. Cada empresa retornada custa 1 crédito, e meta.total_count_capped na primeira página dá a contagem até o teto de exibição, ou um mínimo quando vem com +, antes de você percorrer tudo.
• Rate limit por conta: todas as chaves e fluxos somam no mesmo contador. Em 429 rate_limited, espere Retry-After; em lote grande, coloque um nó Wait entre páginas em vez de disparar em paralelo.
• Franquia: 402 quota_exceeded é hard cap. Consulte GET /v1/usage no início do fluxo e compare com o custo estimado; nada é cobrado sem uma ação sua.
• 404 not_found é resultado: CNPJ válido que não existe na base não é falha do fluxo, e custa 0.
• Data da base: meta.data_as_of diz qual foto mensal respondeu; grave junto com o registro enriquecido.