Como consumir API de CPF em Pipedrive para validação 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

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 retorna um objeto JSON com os dados cadastrais do titular, que são então gravados nos campos customizados do contato no Pipedrive:

{
    "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:

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 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.

Conclusão

Integrar a API da 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, gere sua API key e teste as primeiras 50 consultas gratuitamente, sem precisar informar cartão de crédito.