Concluído08/2024

CNPJ Hub - Nó N8N para Consulta de CNPJ

Nó customizado para N8N que consulta dados de empresas brasileiras em 6 APIs públicas com fallback automático e normalização de dados

ROI: 70h/mês
#n8n#automação#api#open-source

Contexto

Consultar dados de CNPJ é uma necessidade comum em automações brasileiras.

Seja pra validar clientes, enriquecer leads ou verificar fornecedores, ter acesso rápido a dados empresariais é essencial.

Mas tem um problema: as APIs públicas de CNPJ são instáveis.

Uma hora funciona, outra hora cai. Algumas têm rate limit agressivo, outras retornam dados incompletos.

E quando você está no meio de uma automação crítica, não dá pra ficar na mão.

Foi aí que surgiu a ideia: criar um nó para N8N que consulta 6 APIs diferentes e usa fallback automático.

Se uma falha, tenta a próxima. Se todas falharem, retorna erro estruturado.

E o melhor: normaliza os dados pra você não precisar lidar com 6 formatos diferentes de resposta.

Bastidores

O projeto começou como uma necessidade interna do Lab.

Precisávamos enriquecer dados de empresas em várias automações e ficar dependendo de uma única API era arriscado.

"E se a API cair no meio do processo?"

A solução foi criar um sistema de fallback inteligente que tenta 6 APIs públicas na ordem:

1. CNPJ.ws (mais completa)
2. CNPJA (bem estruturada)
3. MinhaReceita (detalhada)
4. OpenCNPJ (atualizada mensalmente)
5. BrasilAPI (comunidade)
6. ReceitaWS (rápida e simples)

Se a primeira falhar, tenta a segunda. Se a segunda falhar, tenta a terceira. E assim por diante.

O resultado? Uma taxa de sucesso muito maior que usar apenas uma API.

Mas tinha outro desafio: cada API retorna os dados em um formato diferente.

Então criamos um sistema de normalização que padroniza tudo:
- Razão social sempre no mesmo campo
- Endereço sempre na mesma estrutura
- Sócios sempre no mesmo formato

Isso economiza horas de trabalho mapeando campos diferentes em cada automação.

E o melhor: o projeto é open-source e já tem 419 downloads no NPM.

Isso significa que outras pessoas estão usando e se beneficiando do trabalho.

Aprendizados

  • →

    Fallback automático é essencial quando você depende de APIs públicas.

    Não dá pra confiar que uma única fonte vai estar sempre disponível, especialmente em automações críticas.

  • →

    Normalização de dados economiza muito tempo.

    Em vez de mapear 6 formatos diferentes em cada automação, você mapeia uma vez só no nó e todas as automações se beneficiam.

  • →

    Open-source gera valor além do código.

    Os 419 downloads mostram que outras pessoas tinham o mesmo problema e agora têm uma solução pronta.

    Isso é impacto real.

  • →

    Rate limiting precisa ser configurável.

    Cada automação tem necessidades diferentes: algumas precisam de velocidade, outras precisam evitar bloqueios.

    Deixar o delay configurável (inclusive com expressões dinâmicas do N8N) foi uma decisão acertada.

Como Replicar

1Instale o nó no N8N

Para instalar um nó da comunidade no N8N:

    • Acesse Configurações (Settings) no seu fluxo de trabalho
    • Vá para a aba Community Nodes
    • Clique em Install a community node
    • Insira o nome do pacote: n8n-nodes-cnpj-hub
    • Clique em Install

A instalação será concluída e você poderá encontrar o novo nó no painel de nós, pronto para ser adicionado a um fluxo.

Buscando o nó CNPJ HUB no N8N
n8n-nodes-cnpj-hub

Nó customizado para N8N - 419 downloads

📦 Ver no NPM
Código Fonte no GitHub

Contribua com o projeto, reporte bugs e sugira melhorias

⭐ Dê uma estrela no GitHub

2Configure o nó no N8N

Adicione o nó "CNPJ HUB" no seu workflow e configure:

Estratégia de API:
  • Fallback Automático (recomendado): Tenta todas as APIs até conseguir
  • API Específica: Usa apenas uma API escolhida
APIs disponíveis no nó CNPJ HUBFormato de Dados:
  • Normalizado (recomendado): Formato padronizado entre todas as APIs
  • Original: Dados brutos da API
Delay entre requisições:
  • Aceita valores fixos ou expressões dinâmicas do N8N
  • Padrão: 1000ms (1 segundo)
  • Mínimo: 0ms
  • Máximo: 60000ms (60 segundos)
Exemplo de expressão dinâmica: 
={{$json.customDelay || 1000}}
={{$json.isPriority ? 500 : 2000}}
={{Math.min($json.requestCount * 100, 5000)}}

3Use em suas automações

O nó retorna dados normalizados com esta estrutura:

{
  "cnpj": "11.222.333/0001-81",
  "razao_social": "Nome da Empresa",
  "nome_fantasia": "Nome Fantasia",
  "situacao": "Ativa",
  "data_abertura": "2009-09-02",
  "porte": "Pequeno",
  "capital_social": "0.00",
  "endereco": {
    "logradouro": "Rua Exemplo",
    "numero": "123",
    "bairro": "Centro",
    "cep": "12345000",
    "municipio": "São Paulo",
    "uf": "SP"
  },
  "contato": {
    "telefone": "(11) 1234-5678",
    "email": "contato@empresa.com"
  },
  "socios": [...],
  "_meta": {
    "api_utilizada": "brasilapi",
    "data_consulta": "2024-11-03T10:00:00.000Z",
    "estrategia": "fallback"
  }
}

4Monitore e otimize

O campo `_meta` traz informações valiosas:

  • Qual API foi usada com sucesso
  • Quais APIs falharam (no modo fallback)
  • Timestamp da consulta
  • Estratégia utilizada
Use essas informações pra:
  • Identificar APIs mais confiáveis
  • Ajustar delays se necessário
  • Debugar problemas
  • Calcular custos (se usar APIs pagas no futuro)

5Contribua com o projeto

O projeto é open-source e aceita contribuições:

  • Reporte bugs
  • Sugira melhorias
  • Adicione novas APIs
  • Melhore a documentação
  • Dê uma estrela no GitHub ⭐

Aprovado

Gostou deste experimento?

Os próximos chegam primeiro no Doug Drops. E o painel mostra todos os casos do laboratório lado a lado.

Assinar o Doug DropsVer o painel do Lab