# Como consumir API de CPF em n8n para automacoes self-hosted > Aprenda a criar workflows no n8n que consultam CPF via API CPFHub.io com nos HTTP Request, Function e integrações com bancos de dados e notificações. **Publicado:** 01/10/2026 **Autor:** Lucas Vieira **URL:** https://www.cpfhub.io/blog/como-consumir-api-cpf-n8n-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](https://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: ```json { "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: ```javascript // 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) ```sql 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) ```javascript 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) ```json { "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) ```javascript 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) ```sql 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: ```yaml # 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: ``` ```bash 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)](https://www.gov.br/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. ### Leia também - [Como integrar API de CPF com Zapier e Make (Integromat) sem código](https://cpfhub.io/blog/como-integrar-api-de-cpf-com-zapier-e-make-sem-codigo) - [Como consumir API de CPF em Google Apps Script para automações no Google Sheets](https://cpfhub.io/blog/como-consumir-api-cpf-google-apps-script-automacoes-google-sheets) - [Como consumir API de CPF em Excel VBA para automação de planilhas](https://cpfhub.io/blog/como-consumir-api-cpf-excel-vba-automacao-planilhas) - [Como usar API de CPF para enriquecer dados de CRM automaticamente](https://cpfhub.io/blog/como-usar-api-de-cpf-para-enriquecer-dados-de-crm-automaticamente) --- ## 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**](https://www.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](https://www.cpfhub.io/) e comece a automatizar suas validações de CPF com n8n.