Como integrar validação de CPF em n8n com nós HTTP customizados

Integrar validação de CPF em n8n é direto: basta configurar um nó HTTP Request apontando para GET https://api.cpfhub.io/cpf/{CPF} com o header x-api-key da CPFHub.io. Em menos de 30 minutos, qualquer workflow de cadastro, onboarding ou processamento de planilhas passa a verificar identidades automaticamente, sem escrever uma linha de código.

Introdução

O n8n é uma plataforma de automação de workflows open-source que vem ganhando popularidade como alternativa ao Zapier e Make (ex-Integromat). Com uma interface visual de arrastar e soltar, o n8n permite conectar centenas de serviços e APIs sem escrever código — embora ofereça total flexibilidade para customizações quando necessário.

Para empresas que precisam automatizar a validação de CPF em fluxos de trabalho como cadastro de clientes, processamento de pedidos ou verificação de dados em planilhas, o n8n é uma ferramenta poderosa.

1. Pré-requisitos

• n8n instalado -- Pode ser self-hosted (Docker, npm) ou usar o n8n Cloud.

• Conta na CPFHub.io -- Cadastre-se em CPFHub.io para obter sua API key gratuita. O plano free oferece 50 consultas por mês sem cartão de crédito.

Instalando n8n localmente

# Via Docker
docker run -it --rm --name n8n -p 5678:5678 n8nio/n8n

# Via npm
npx n8n

Após a instalação, acesse o n8n em http://localhost:5678.

2. Configurando a credencial

Antes de criar workflows, configure a credencial da API:

1. Acesse Settings > Credentials no n8n.
2. Clique em Add Credential.
3. Selecione Header Auth.
4. Configure:
   • Name: CPFHub API Key
   • Header Name: x-api-key
   • Header Value: SUA_CHAVE_DE_API

Essa credencial será reutilizada em todos os nós HTTP Request que acessam a API da CPFHub.io.

3. Workflow básico — Consulta de CPF via Webhook

Este workflow recebe um CPF via webhook e retorna os dados validados.

Nó 1 — Webhook (Trigger)

• HTTP Method: GET
• Path: /validar-cpf
• Response Mode: Last Node

Nó 2 — HTTP Request (CPFHub)

Configure o nó HTTP Request com os seguintes parâmetros:

• Method: GET
• URL: https://api.cpfhub.io/cpf/{{ $json.query.cpf }}
• Authentication: Header Auth (selecione a credencial criada)
• Headers adicionais:
  • Name: Accept
  • Value: application/json
• Timeout: 30000 (em milissegundos)

Nó 3 — IF (Verificação de sucesso)

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

Nó 4 — Respond to Webhook (Sucesso)

• Response Body: JSON com os dados retornados

O mesmo fluxo pode ser representado como código JSON para importação no n8n:

{
  "nodes": [
    {
      "parameters": {
        "httpMethod": "GET",
        "path": "validar-cpf",
        "responseMode": "lastNode"
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "position": [250, 300]
    },
    {
      "parameters": {
        "method": "GET",
        "url": "=https://api.cpfhub.io/cpf/{{ $json.query.cpf }}",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "options": {
          "timeout": 30000
        },
        "headerParameters": {
          "parameters": [
            {
              "name": "Accept",
              "value": "application/json"
            }
          ]
        }
      },
      "name": "Consultar CPF",
      "type": "n8n-nodes-base.httpRequest",
      "position": [470, 300],
      "credentials": {
        "httpHeaderAuth": {
          "id": "1",
          "name": "CPFHub API Key"
        }
      }
    }
  ]
}

4. Exemplo de resposta da API

A API da CPFHub.io retorna um JSON estruturado com os dados cadastrais do titular consultado:

{
  "success": true,
  "data": {
    "cpf": "12345678900",
    "name": "Joao da Silva",
    "nameUpper": "JOAO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

• success -- Indica se a consulta foi bem-sucedida.
• name / nameUpper -- Nome completo do titular.
• gender -- Gênero (M ou F).
• birthDate -- Data de nascimento completa.
• day, month, year -- Componentes da data separados.

No n8n, esses campos são acessíveis como {{ $json.data.name }}, {{ $json.data.gender }}, etc.

5. Workflow avançado — Validação em lote a partir de planilha

Este workflow lê CPFs de uma planilha do Google Sheets, valida cada um e atualiza a planilha com os resultados.

Estrutura do workflow

1. Schedule Trigger -- Executa diariamente às 8h.
2. Google Sheets (Read) -- Lê a coluna de CPFs da planilha.
3. Split In Batches -- Processa um CPF por vez para controlar o consumo de cota.
4. HTTP Request -- Consulta cada CPF na API da CPFHub.io.
5. IF -- Verifica se a consulta foi bem-sucedida.
6. Google Sheets (Update) -- Atualiza as colunas de nome, gênero e status.
7. Wait -- Aguarda 2 segundos entre consultas para evitar picos de consumo.

Configuração do nó HTTP Request

Method: GET
URL: https://api.cpfhub.io/cpf/{{ $json.cpf }}
Authentication: Header Auth (CPFHub API Key)
Headers: Accept: application/json
Timeout: 30000

Configuração do nó Wait

• Resume: After Time Interval
• Amount: 2
• Unit: Seconds

Esse intervalo mantém o consumo de cota previsível, especialmente útil em lotes grandes onde cada consulta extra além da cota do plano é cobrada a R$0,15.

6. Workflow de integração — Cadastro com CRM

Outro cenário comum é validar o CPF automaticamente quando um novo contato é criado no CRM:

1. CRM Trigger -- Quando novo contato é criado (HubSpot, Pipedrive, etc.).
2. Set -- Extrair e limpar o CPF do contato.
3. HTTP Request -- Consultar CPF na API da CPFHub.io.
4. IF -- Verificar se o CPF é válido.
5. CRM Update -- Atualizar o contato com nome verificado e status de validação.
6. Slack/Email -- Notificar a equipe em caso de CPF inválido.

7. Usando o nó Code para lógica customizada

Para cenários mais complexos, utilize o nó Code do n8n:

// Nó Code - Validação e formatação de CPF
const items = $input.all();
const results = [];

for (const item of items) {
  let cpf = item.json.cpf || '';
  cpf = cpf.replace(/\D/g, '');

  if (cpf.length !== 11) {
    results.push({
      json: {
        ...item.json,
        cpf_valido: false,
        erro: 'CPF com formato invalido',
      },
    });
    continue;
  }

  results.push({
    json: {
      ...item.json,
      cpf_limpo: cpf,
      cpf_formatado: cpf.replace(/(\d{3})(\d{3})(\d{3})(\d{2})/, '$1.$2.$3-$4'),
    },
  });
}

return results;

8. Boas práticas no n8n

• Use credenciais armazenadas -- Nunca insira a chave de API diretamente nos nós. Utilize o sistema de credenciais do n8n.

• Configure timeouts -- Defina timeout de 30000ms nos nós HTTP Request para evitar workflows travados.

• Monitore o consumo de cota -- Insira nós Wait entre consultas em lotes grandes e acompanhe o consumo em app.cpfhub.io/settings/billing para evitar cobranças inesperadas de R$0,15 por consulta extra.

• Implemente tratamento de erros -- Use os nós Error Trigger e IF para lidar com respostas de erro da API.

• Monitore execuções -- O n8n mantém um histórico de execuções que facilita a depuração de problemas.

A OWASP recomenda armazenar credenciais de API em variáveis de ambiente ou cofres de segredos, nunca em texto plano nos workflows — o sistema de credenciais do n8n segue essa prática por padrão.

Perguntas frequentes

O que é necessário para integrar a CPFHub.io no n8n?

Você precisa de uma conta na CPFHub.io (gratuita, sem cartão de crédito), uma API key gerada no painel e um nó HTTP Request configurado com o endpoint GET https://api.cpfhub.io/cpf/{CPF} e o header x-api-key. A configuração leva menos de 10 minutos.

A API CPFHub.io retorna erro quando a cota mensal é atingida no n8n?

Não. A CPFHub.io nunca bloqueia requisições. Ao superar as 50 consultas do plano gratuito, cada consulta adicional é cobrada a R$0,15. Para controlar custos em workflows de lote, use o nó Wait entre requisições e monitore o consumo em app.cpfhub.io/settings/billing.

Como garantir conformidade com a LGPD ao usar a API no n8n?

Use o CPF apenas para a finalidade declarada no workflow, evite armazenar o número cru em planilhas ou logs, e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e configure o nó HTTP Request no n8n conforme os exemplos deste artigo.

Conclusão

O n8n é uma ferramenta poderosa para automatizar a validação de CPF sem escrever código complexo. Com nós HTTP Request customizados, é possível integrar a API da CPFHub.io em qualquer workflow de cadastro, CRM ou processamento de planilhas em minutos.

A CPFHub.io oferece conformidade LGPD, tempo de resposta de aproximadamente 900ms e 99,9% de uptime. A integração com o n8n pode ser feita em poucos minutos, tornando acessível a validação de CPF para equipes que não possuem desenvolvedores dedicados.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.