Como consumir API de CPF em n8n para automacoes self-hosted

Para consumir a API de CPF no n8n, crie um nó HTTP Request com método GET apontando para https://api.cpfhub.io/cpf/{CPF}, configure uma credencial do tipo Header Auth com o header x-api-key e processe o retorno com um nó Function. A resposta chega em ~900ms com nome, gênero e data de nascimento — pronta para ser gravada em banco de dados ou disparar notificações. A documentação oficial do n8n está em docs.n8n.io.

n8n é uma plataforma de automação de workflows open-source que pode ser executada em infraestrutura própria — self-hosted. Diferente de plataformas como Zapier ou Power Automate, o n8n oferece controle total sobre os dados e a infraestrutura, o que é especialmente relevante para empresas que lidam com dados sensíveis como CPF. Com mais de 400 integrações nativas e a capacidade de executar código JavaScript customizado, o n8n é uma ferramenta poderosa para criar automações de validação de CPF.

Por que n8n para validação de CPF

O n8n se destaca em cenários onde a privacidade dos dados é prioritária:

• Self-hosted — Os dados de CPF nunca saem da sua infraestrutura. O n8n roda no seu servidor, e as chamadas à API são feitas diretamente dele.
• Open-source — Código auditável, sem dependência de vendor.
• Sem limites de execução — Diferente de plataformas SaaS, o n8n self-hosted não limita o número de execuções.
• Código customizado — O nó "Function" permite escrever JavaScript para lógica complexa.
• Credenciais criptografadas — As chaves de API são armazenadas de forma criptografada no banco de dados do n8n.

Configuração de credenciais

Antes de criar o workflow, configure as credenciais da API no n8n:

1. Acesse Settings > Credentials.
2. Crie uma nova credencial do tipo "Header Auth".
3. Configure:

• Name: CPFHub.io API
• Header Name: x-api-key
• Header Value: sua_chave_de_api

Essa credencial ficará disponível para todos os workflows que precisarem consultar a API.

Workflow básico de validação

O workflow mais simples consiste em três nós:

Nó 1 — Webhook (trigger)

Configure um nó Webhook para receber requisições HTTP:

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

Nó 2 — HTTP Request

Configure o nó HTTP Request para chamar a API da CPFHub.io:

{
    "method": "GET",
    "url": "=https://api.cpfhub.io/cpf/{{ $json.body.cpf.replace(/\\D/g, '') }}",
    "authentication": "headerAuth",
    "headerAuth": "CPFHub.io API",
    "options": {
    "timeout": 10000,
    "fullResponse": false
    },
    "headers": {
    "Accept": "application/json"
    }
}

Nó 3 — Function (processar resposta)

O nó Function processa a resposta e formata o resultado:

// No Function: Processar resultado da consulta
const items = $input.all();
const resultados = [];

for (const item of items) {
    const dados = item.json;

    if (dados.success && dados.data) {
    resultados.push({
    json: {
    valido: true,
    nome: dados.data.name,
    cpf: dados.data.cpf,
    genero: dados.data.gender,
    dataNascimento: dados.data.birthDate,
    dia: dados.data.day,
    mes: dados.data.month,
    ano: dados.data.year
    }
    });
    } else {
    resultados.push({
    json: {
    valido: false,
    erro: "CPF nao encontrado"
    }
    });
    }
}

return resultados;

Workflow de validação em lote

Para validar múltiplos CPFs de uma vez, crie um workflow mais elaborado:

Nó 1 — Trigger manual ou Cron

Use um trigger Cron para executar diariamente ou um trigger manual:

Schedule Trigger: Todos os dias as 08:00

Nó 2 — Buscar CPFs pendentes (Postgres)

SELECT id, cpf, nome_informado
FROM cadastros
WHERE status_validacao = 'pendente'
LIMIT 50;

Nó 3 — Split In Batches

Configure para processar 5 itens por vez com pausa de 1 segundo entre lotes.

Nó 4 — Function (limpar CPF)

const items = $input.all();

return items.map(item => ({
    json: {
    ...item.json,
    cpf_limpo: item.json.cpf.replace(/\D/g, '')
    }
}));

Nó 5 — HTTP Request (consultar API)

{
    "method": "GET",
    "url": "=https://api.cpfhub.io/cpf/{{ $json.cpf_limpo }}",
    "authentication": "headerAuth",
    "headerAuth": "CPFHub.io API",
    "options": {
    "timeout": 10000
    },
    "headers": {
    "Accept": "application/json"
    }
}

Nó 6 — Function (processar e comparar)

const items = $input.all();
const resultados = [];

for (const item of items) {
    const dados = item.json;
    const original = $('Buscar_CPFs').item(items.indexOf(item));

    if (dados.success && dados.data) {
    const nomeAPI = dados.data.name.toUpperCase();
    const nomeInformado = original.json.nome_informado.toUpperCase();
    const nomeConfere = nomeAPI.includes(nomeInformado.split(' ')[0]);

    resultados.push({
    json: {
    id: original.json.id,
    cpf: dados.data.cpf,
    nome_api: dados.data.name,
    nome_informado: original.json.nome_informado,
    nome_confere: nomeConfere,
    genero: dados.data.gender,
    data_nascimento: dados.data.birthDate,
    status: nomeConfere ? 'validado' : 'divergente'
    }
    });
    } else {
    resultados.push({
    json: {
    id: original.json.id,
    status: 'nao_encontrado'
    }
    });
    }
}

return resultados;

Nó 7 — Postgres (atualizar status)

UPDATE cadastros
SET status_validacao = '{{ $json.status }}',
    nome_validado = '{{ $json.nome_api }}',
    validado_em = NOW()
WHERE id = {{ $json.id }};

Tratamento de erros

O n8n permite configurar tratamento de erros em cada nó:

Error Trigger workflow

Crie um workflow separado para tratamento de erros:

Error Trigger
    -> Function (formatar mensagem de erro)
    -> Slack/Email (notificar equipe)
    -> Postgres (registrar erro)

Configuração de retry

No nó HTTP Request, configure retries:

• Retry On Fail: true
• Max Tries: 3
• Wait Between Tries: 2000ms

Instalação do n8n self-hosted

Para rodar o n8n na sua infraestrutura com Docker:

# docker-compose.yml
version: '3.8'

services:
    n8n:
    image: docker.n8n.io/n8nio/n8n
    restart: always
    ports:
    - "5678:5678"
    environment:
    - N8N_BASIC_AUTH_ACTIVE=true
    - N8N_BASIC_AUTH_USER=admin
    - N8N_BASIC_AUTH_PASSWORD=senha_segura
    - DB_TYPE=postgresdb
    - DB_POSTGRESDB_HOST=postgres
    - DB_POSTGRESDB_DATABASE=n8n
    - DB_POSTGRESDB_USER=n8n
    - DB_POSTGRESDB_PASSWORD=senha_db
    - N8N_ENCRYPTION_KEY=chave_criptografia_32_chars
    volumes:
    - n8n_data:/home/node/.n8n
    depends_on:
    - postgres

    postgres:
    image: postgres:16
    restart: always
    environment:
    - POSTGRES_DB=n8n
    - POSTGRES_USER=n8n
    - POSTGRES_PASSWORD=senha_db
    volumes:
    - postgres_data:/var/lib/postgresql/data

volumes:
    n8n_data:
    postgres_data:

docker compose up -d

Monitoramento de workflows

O n8n oferece monitoramento integrado:

• Execution log — Histórico completo de cada execução com detalhes de cada nó.
• Error workflows — Workflows dedicados que disparam quando outros falham.
• Metrics endpoint — Expõe métricas Prometheus para monitoramento externo.

Perguntas frequentes

Qual a diferença entre usar n8n self-hosted e uma plataforma como Zapier para validar CPF?

No n8n self-hosted, os dados de CPF trafegam apenas entre o seu servidor e a API da CPFHub.io — nenhum dado passa por servidores de terceiros. No Zapier, os dados passam pela infraestrutura da própria plataforma antes de chegar ao destino. Para dados sensíveis como CPF, o self-hosted é mais adequado para conformidade com a LGPD, especialmente em setores regulados.

O n8n self-hosted tem custo de uso por execução de workflow?

Não. O n8n self-hosted (versão community) não cobra por execução. O custo é apenas a infraestrutura onde ele roda — um servidor VPS com 2GB de RAM já suporta centenas de execuções diárias. O único custo variável é o consumo da API da CPFHub.io: 50 consultas/mês no plano Gratuito, 1.000 no Pro (R$149/mês), e R$0,15 por consulta excedente.

Como a ANPD orienta o tratamento de dados de CPF em automações?

A Autoridade Nacional de Proteção de Dados (ANPD) orienta que o tratamento de dados pessoais deve respeitar o princípio da necessidade — coletando apenas o mínimo necessário para a finalidade declarada. Em automações com n8n, isso significa não armazenar o CPF bruto nos logs de execução, desativar a retenção de dados de execução no painel do n8n e usar variáveis de ambiente para proteger chaves de API.

Como lidar com falhas de rede ao consultar a API no n8n?

Configure o nó HTTP Request com Retry On Fail ativado, Max Tries: 3 e Wait Between Tries: 2000ms. Além disso, crie um workflow de Error Trigger separado que registra falhas no banco e notifica a equipe. Para erros persistentes, o nó IF pode redirecionar o fluxo para uma fila de reprocessamento em vez de marcar o registro como "erro" permanentemente.

Conclusão

O n8n é a escolha ideal para organizações que precisam de automações de validação de CPF com controle total sobre os dados. A combinação de self-hosting, código customizado e mais de 400 integrações cria workflows poderosos que conectam a API da CPFHub.io a qualquer banco de dados, CRM ou sistema de notificação.

O plano gratuito da CPFHub.io cobre 50 consultas/mês sem cartão — suficiente para validar o workflow antes de colocar em produção. Para volumes maiores, o plano Pro entrega 1.000 consultas por R$149/mês. Consultas além do limite nunca bloqueiam: são cobradas a R$0,15 cada.

Crie sua conta em cpfhub.io e comece a automatizar suas validações de CPF com n8n.