Integração n8n

Consulte CPFs diretamente em workflows n8n usando o node HTTP Request. Nenhuma instalação adicional é necessária.

Configuração da credencial

No n8n, crie uma credencial do tipo Header Auth:

1. Acesse Settings → Credentials → Add Credential
2. Selecione Header Auth
3. Preencha:
   • Name: CPFHub API Key
   • Header Name: x-api-key
   • Header Value: sua API Key (ex: cpfhub_sk_...)

Node HTTP Request

Adicione um node HTTP Request ao seu workflow e configure:

Para passar o CPF de um node anterior (ex: formulário), use a expressão:

https://api.cpfhub.io/v1/cpf/{{ $json.cpf }}

Resposta da API

Em caso de sucesso, o node retorna:

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/04/1985",
    "day": 15,
    "month": 4,
    "year": 1985
  }
}

Acesse os campos nos nodes seguintes com expressões como:

{{ $json.data.name }}
{{ $json.data.gender }}
{{ $json.data.birthDate }}

Exemplo: workflow de onboarding

Um workflow típico de validação de cadastro:

[Webhook] → [HTTP Request - CPFHub] → [IF: success?]
                                          ↓ sim        ↓ não
                                    [Enviar email] [Notificar erro]

1. Node Webhook

Configure o webhook para receber o CPF do formulário de cadastro. O body esperado:

{ "cpf": "12345678909", "email": "joao@exemplo.com" }

2. Node HTTP Request (CPFHub)

• URL: https://api.cpfhub.io/v1/cpf/{{ $json.body.cpf }}
• Credencial: CPFHub API Key

3. Node IF

• Condition: {{ $json.success }} é true

4. Branch sucesso - node Set

Mapeie os dados para o próximo passo:

name  → {{ $json.data.name }}
email → {{ $('Webhook').item.json.body.email }}

5. Branch erro - node Set

error → {{ $json.error ?? 'CPF_NOT_FOUND' }}

Tratamento de erros HTTP

Ative Continue on Fail no node HTTP Request para tratar erros sem interromper o workflow. Use um node IF após para verificar o status code:

• {{ $json.statusCode }} é 404 → CPF não encontrado
• {{ $json.statusCode }} é 429 → rate limit (adicione um node Wait)
• {{ $json.statusCode }} é 401 → API Key inválida

Usando variáveis de ambiente no n8n

Para evitar expor a API Key hardcoded, use as variáveis de ambiente do n8n:

1. Defina N8N_CPFHUB_API_KEY=cpfhub_sk_... no ambiente do n8n
2. Acesse no workflow com {{ $env.N8N_CPFHUB_API_KEY }}

Ou use o cofre de credenciais nativo do n8n (recomendado para produção).

Referências

• Documentação do HTTP Request node - n8n
• Referência da API CPFHub - GET /cpf
• Códigos de erro & tratamento

Atualizado em 12 de maio de 2026