# Como consumir API de CPF em Pipedrive para validação de leads

> Aprenda a consumir a API de consulta de CPF da CPFHub.io integrada ao Pipedrive para validar leads automaticamente no funil de vendas.

**Publicado:** 07/02/2026
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-consumir-api-de-cpf-em-pipedrive-para-validacao-de-leads

---

Para consumir a API de CPF no Pipedrive, configure um webhook que dispara ao atualizar um contato, envie o CPF para `https://api.cpfhub.io/cpf/{CPF}` com o header `x-api-key` e grave os dados retornados nos campos customizados do Pipedrive — nome, data de nascimento e status de validação — sem nenhuma intervenção manual da equipe de vendas.

## Introdução

O **Pipedrive** é um dos CRMs mais populares entre equipes de vendas no Brasil. Quando a qualificação de leads exige validação de CPF -- seja para verificar a identidade do contato, enriquecer dados cadastrais ou garantir conformidade regulatória -- integrar uma API de consulta de CPF diretamente ao pipeline pode acelerar o ciclo de vendas.

---

## 1. Cenários de uso no Pipedrive

* **Qualificação de leads** -- Validar se o CPF do lead é real antes de avançar no pipeline.

* **Enriquecimento de dados** -- Preencher automaticamente nome completo, gênero e data de nascimento.

* **Compliance** -- Garantir que contatos em negociação possuem dados cadastrais válidos.

* **Prevenção de fraudes** -- Bloquear leads com CPFs inválidos ou inconsistentes.

---

## 2. Campos customizados no Pipedrive

Crie os seguintes campos customizados no Pipedrive para armazenar os dados da validação:

* **CPF** -- Campo de texto no contato (Person).

* **CPF Validado** -- Campo de texto para o nome retornado pela API.

* **CPF Status** -- Campo de opção com valores "Pendente", "Validado" e "Erro".

* **Data de Nascimento** -- Campo de texto para a data retornada.

---

## 3. Webhook do Pipedrive

Configure um webhook no Pipedrive em **Settings > Webhooks**:

* **Event action** -- updated

* **Event object** -- person

* **Endpoint URL** -- URL do seu servidor (ex: `https://seu-servidor.com/webhook/pipedrive`)

O webhook será disparado sempre que um contato for atualizado. O servidor filtrará apenas as atualizações relevantes (quando o campo CPF for preenchido).

---

## 4. Servidor de integração com Node.js

```javascript
const express = require('express');
const app = express();
app.use(express.json());

const PIPEDRIVE_API_TOKEN = process.env.PIPEDRIVE_API_TOKEN;
const PIPEDRIVE_DOMAIN = process.env.PIPEDRIVE_DOMAIN; // ex: suaempresa.pipedrive.com
const CPFHUB_API_KEY = process.env.CPFHUB_API_KEY;

// IDs dos campos customizados (obter via API do Pipedrive)
const FIELD_CPF = process.env.PIPEDRIVE_FIELD_CPF;
const FIELD_CPF_VALIDADO = process.env.PIPEDRIVE_FIELD_VALIDADO;
const FIELD_CPF_STATUS = process.env.PIPEDRIVE_FIELD_STATUS;
const FIELD_NASCIMENTO = process.env.PIPEDRIVE_FIELD_NASCIMENTO;

async function consultarCpf(cpf) {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 5000);

 try {
 const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
 method: 'GET',
 headers: {
 'x-api-key': CPFHUB_API_KEY,
 'Accept': 'application/json'
 },
 signal: controller.signal
 });

 clearTimeout(timeoutId);

 if (!response.ok) {
 throw new Error(`HTTP ${response.status}`);
 }

 return await response.json();
 } catch (error) {
 clearTimeout(timeoutId);
 throw error;
 }
}

async function atualizarContato(personId, campos) {
 const url = `https://${PIPEDRIVE_DOMAIN}/api/v1/persons/${personId}?api_token=${PIPEDRIVE_API_TOKEN}`;

 await fetch(url, {
 method: 'PUT',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify(campos)
 });
}

app.post('/webhook/pipedrive', async (req, res) => {
 const { current, previous } = req.body;

 if (!current || !current[FIELD_CPF]) {
 return res.json({ skipped: true });
 }

 // Só processar se o CPF foi alterado
 if (current[FIELD_CPF] === previous?.[FIELD_CPF]) {
 return res.json({ skipped: true });
 }

 const cpf = current[FIELD_CPF].replace(/\D/g, '');
 const personId = current.id;

 if (cpf.length !== 11) {
 await atualizarContato(personId, { [FIELD_CPF_STATUS]: 'Erro' });
 return res.json({ error: 'CPF inválido' });
 }

 try {
 const resultado = await consultarCpf(cpf);

 if (resultado.success) {
 await atualizarContato(personId, {
 [FIELD_CPF_VALIDADO]: resultado.data.name,
 [FIELD_NASCIMENTO]: resultado.data.birthDate,
 [FIELD_CPF_STATUS]: 'Validado'
 });
 console.log(`Validado: ${cpf} - ${resultado.data.name}`);
 } else {
 await atualizarContato(personId, { [FIELD_CPF_STATUS]: 'Erro' });
 }

 res.json({ success: true });
 } catch (error) {
 await atualizarContato(personId, { [FIELD_CPF_STATUS]: 'Erro' });
 console.error(`Erro: ${error.message}`);
 res.status(500).json({ error: error.message });
 }
});

app.listen(3000, () => console.log('Servidor rodando na porta 3000'));
```

---

## 5. Exemplo de resposta da API

Quando a validação é bem-sucedida, a [**CPFHub.io**](https://www.cpfhub.io/) retorna um objeto JSON com os dados cadastrais do titular, que são então gravados nos campos customizados do contato no Pipedrive:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "João da Silva",
 "nameUpper": "JOÃO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

Esses dados são então gravados nos campos customizados do contato no Pipedrive.

---

## 6. Alternativa com Zapier ou Make

Para equipes que preferem uma solução sem código:

1. **Trigger** -- Pipedrive > New or Updated Person.
2. **Filter** -- Verificar se o campo CPF foi preenchido.
3. **HTTP Request** -- GET para `https://api.cpfhub.io/cpf/{CPF}` com header `x-api-key`. Configure timeout de 5 segundos.
4. **Pipedrive** -- Update Person com os dados retornados.

---

## 7. Validação em lote de leads existentes

Para validar leads já cadastrados, crie um script que percorre os contatos via API do Pipedrive:

```javascript
async function validarLeadsExistentes() {
 const url = `https://${PIPEDRIVE_DOMAIN}/api/v1/persons?api_token=${PIPEDRIVE_API_TOKEN}&limit=50`;
 const response = await fetch(url);
 const { data: contatos } = await response.json();

 for (const contato of contatos) {
 const cpf = contato[FIELD_CPF]?.replace(/\D/g, '');
 if (!cpf || cpf.length !== 11) continue;

 try {
 const resultado = await consultarCpf(cpf);
 if (resultado.success) {
 await atualizarContato(contato.id, {
 [FIELD_CPF_VALIDADO]: resultado.data.name,
 [FIELD_CPF_STATUS]: 'Validado'
 });
 }
 } catch (error) {
 console.error(`Erro no CPF ${cpf}: ${error.message}`);
 }

 // Aguardar entre requisições para evitar sobrecarga
 await new Promise(resolve => setTimeout(resolve, 2000));
 }
}
```

---

## 8. Boas práticas

* **Timeout** -- Sempre configure timeout de 5 segundos nas chamadas à CPFHub.io.

* **Cadência de requisições** -- Respeite os intervalos entre chamadas (Gratuito: 1 req/2s, Pro: 1 req/s) para evitar sobrecarga no processamento em lote.

* **Segurança** -- Armazene tokens e chaves em variáveis de ambiente.

* **Idempotência** -- Verifique se o CPF foi alterado antes de reprocessar para evitar consultas duplicadas.

* **Webhook loop** -- Cuidado para não criar loops: ao atualizar o contato via API, o webhook será disparado novamente. Use o campo de status para filtrar.

---

## Perguntas frequentes

### Como funciona a validação de CPF integrada ao Pipedrive?

Quando um contato tem o campo CPF preenchido ou atualizado, o webhook do Pipedrive dispara uma requisição ao seu servidor. Esse servidor consulta a API CPFHub.io com o número do CPF e grava o resultado — nome validado, data de nascimento e status — de volta nos campos customizados do contato, tudo de forma automática e sem intervenção da equipe.

### O que acontece se a API retornar erro durante a validação de um lead?

O servidor marca o campo CPF Status como "Erro" no contato do Pipedrive, permitindo que a equipe identifique leads com dados problemáticos. O lead permanece no pipeline e o time de vendas pode tratar manualmente ou acionar uma nova tentativa de validação ao editar o campo CPF.

### É possível validar CPF em lote para leads já cadastrados no Pipedrive?

Sim. Crie um script que percorre os contatos via API do Pipedrive, filtra aqueles com CPF preenchido e status "Pendente", e consulta a CPFHub.io para cada um. Aguarde ao menos 2 segundos entre cada requisição para processar com estabilidade. A API CPFHub.io não bloqueia ao atingir o limite do plano gratuito — cobra R$0,15 por consulta adicional.

### Como garantir conformidade com a LGPD ao usar uma API de CPF no CRM?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário e implemente controle de acesso aos logs de consulta. A [ANPD](https://www.gov.br/anpd) orienta que dados de identificação devem ser tratados com o princípio da necessidade — documente a base legal para o tratamento e evite guardar dados cadastrais além do que o fluxo de vendas exige.

### Leia também

- [Como integrar validação de CPF em HubSpot com workflows customizados](https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-hubspot-com-workflows-customizados)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos)
- [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei)

---

## Conclusão

Integrar a API da [**CPFHub.io**](https://www.cpfhub.io/) ao Pipedrive transforma a validação de CPF em um processo automático e silencioso dentro do funil de vendas. A equipe passa a trabalhar apenas com leads cujos dados foram verificados, reduzindo retrabalho e aumentando a qualidade das oportunidades em cada etapa do pipeline.

A implementação via webhook leva menos de uma hora e funciona com qualquer stack — Node.js, Python ou ferramentas no-code como Zapier e Make. Comece agora: cadastre-se em [cpfhub.io](https://www.cpfhub.io/), gere sua API key e teste as primeiras 50 consultas gratuitamente, sem precisar informar cartão de crédito.