# Como integrar validação de CPF em n8n com nós HTTP customizados > Aprenda a integrar validação de CPF em n8n usando nós HTTP Request customizados. Exemplos com workflows de automação, webhooks e tratamento de dados. **Publicado:** 02/12/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-n8n-com-nos-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**](https://www.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 ```bash # 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: ```json { "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**](https://www.cpfhub.io/) retorna um JSON estruturado com os dados cadastrais do titular consultado: ```json { "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: ```javascript // 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](https://owasp.org/) 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](https://www.gov.br/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. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [10 erros mais comuns ao integrar uma API de CPF e como evitá-los](https://cpfhub.io/blog/10-erros-mais-comuns-ao-integrar-uma-api-de-cpf) --- ## 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](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e comece hoje mesmo.