Como usar API de CPF para enriquecer dados de CRM automaticamente

Para enriquecer dados de CRM com a API de CPF da CPFHub.io, faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com a API key no header x-api-key. A resposta retorna nome completo, data de nascimento e gênero em ~900ms — dados que preenchem automaticamente os campos vazios ou incompletos de cada contato na base. Consultas excedentes ao plano nunca bloqueiam: são cobradas a R$0,15 cada.

A qualidade dos dados em um CRM impacta diretamente a eficiência da equipe comercial, a personalização de campanhas de marketing e a precisão de relatórios gerenciais. Muitas empresas possuem bases de contatos com informações incompletas ou desatualizadas — nomes abreviados, datas de nascimento ausentes, gênero não preenchido. Enriquecer esses dados manualmente é inviável em bases com milhares de registros.

O que significa enriquecer dados de CRM

Enriquecimento de dados é o processo de complementar registros existentes com informações adicionais obtidas de fontes externas. No contexto de CRM, isso significa usar o CPF do contato para buscar dados cadastrais oficiais.

Dados disponíveis via API

A API da CPFHub.io retorna os seguintes campos para cada CPF consultado:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Carla Mendes Oliveira",
    "nameUpper": "CARLA MENDES OLIVEIRA",
    "gender": "F",
    "birthDate": "08/11/1988",
    "day": 8,
    "month": 11,
    "year": 1988
    }
}

O que pode ser enriquecido

Implementação do enriquecimento em Python

O script a seguir lê uma lista de contatos, consulta a API para cada CPF e atualiza os campos ausentes.

import requests
import csv
import time
from datetime import date

CPFHUB_API_KEY = 'SUA_CHAVE_DE_API'

def consultar_cpf(cpf: str) -> dict:
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {
    'x-api-key': CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
    response = requests.get(url, headers=headers, timeout=10)
    return response.json()

def classificar_faixa_etaria(ano: int) -> str:
    idade = date.today().year - ano
    if idade <= 25:
    return '18-25'
    elif idade <= 35:
    return '26-35'
    elif idade <= 45:
    return '36-45'
    elif idade <= 55:
    return '46-55'
    else:
    return '55+'

def enriquecer_contatos(arquivo_entrada: str, arquivo_saida: str):
    contatos_atualizados = []
    total = 0
    enriquecidos = 0
    erros = 0

    with open(arquivo_entrada, 'r', encoding='utf-8') as f:
    leitor = csv.DictReader(f)

    for contato in leitor:
    total += 1
    cpf = contato.get('cpf', '').replace('.', '').replace('-', '')

    if not cpf or len(cpf) != 11:
    contatos_atualizados.append(contato)
    continue

    try:
    resultado = consultar_cpf(cpf)

    if resultado.get('success'):
    dados = resultado['data']

    # Atualizar nome se estiver vazio ou abreviado
    if not contato.get('nome') or len(contato['nome']) < 10:
    contato['nome'] = dados['name']

    # Preencher data de nascimento se vazia
    if not contato.get('data_nascimento'):
    contato['data_nascimento'] = dados['birthDate']

    # Preencher genero se vazio
    if not contato.get('genero'):
    contato['genero'] = dados['gender']

    # Calcular faixa etaria
    contato['faixa_etaria'] = classificar_faixa_etaria(dados['year'])

    enriquecidos += 1
    else:
    erros += 1

    except Exception as e:
    erros += 1
    print(f'Erro ao consultar CPF {cpf}: {e}')

    contatos_atualizados.append(contato)

    # Intervalo entre requisições para bases grandes
    time.sleep(2)

    # Salvar arquivo enriquecido
    if contatos_atualizados:
    campos = contatos_atualizados[0].keys()
    with open(arquivo_saida, 'w', encoding='utf-8', newline='') as f:
    escritor = csv.DictWriter(f, fieldnames=campos)
    escritor.writeheader()
    escritor.writerows(contatos_atualizados)

    print(f'Total: {total} | Enriquecidos: {enriquecidos} | Erros: {erros}')

enriquecer_contatos('contatos.csv', 'contatos_enriquecidos.csv')

Integração com CRMs populares

Via API do CRM

A maioria dos CRMs modernos oferece APIs para leitura e atualização de registros. O fluxo é:

1. Buscar contatos no CRM que possuem CPF mas têm campos incompletos.
2. Consultar a API da CPFHub.io para cada CPF.
3. Atualizar o registro no CRM via API.

Via webhooks

Outra abordagem é configurar um webhook que é disparado quando um novo contato é criado no CRM. O webhook aciona uma função que consulta a API e atualiza o registro automaticamente.

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

app.post('/webhook/novo-contato', async (req, res) => {
    const { cpf, contatoId } = req.body;

    if (!cpf) {
    return res.json({ status: 'ignorado', motivo: 'CPF ausente' });
    }

    const cpfLimpo = cpf.replace(/\D/g, '');

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

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

    clearTimeout(timeoutId);
    const resultado = await response.json();

    if (resultado.success) {
    // Aqui voce chamaria a API do seu CRM para atualizar o contato
    console.log(`Contato ${contatoId} enriquecido:`, resultado.data);
    return res.json({ status: 'enriquecido', dados: resultado.data });
    }

    return res.json({ status: 'nao_encontrado' });
    } catch (error) {
    clearTimeout(timeoutId);
    return res.status(500).json({ status: 'erro' });
    }
});

app.listen(3000);

Automatizando com agendamento

Para enriquecer a base existente gradualmente, sem exceder os limites do plano, implemente um job agendado.

Estratégia de processamento

• Plano Gratuito (50 consultas/mês) — Processar 1-2 contatos por dia.

• Plano Pro (1.000 consultas/mês) — Processar até 33 contatos por dia.

• Plano Corporativo — Volume personalizado conforme a necessidade.

Priorização

Nem todos os contatos precisam ser enriquecidos com a mesma urgência. Priorize:

1. Contatos criados recentemente (leads ativos).
2. Contatos com campos críticos vazios (nome incompleto).
3. Contatos que serão alvo de campanhas próximas.
4. Restante da base, em ordem cronológica.

Boas práticas

• Obtenha consentimento — A LGPD exige base legal para o tratamento de dados pessoais. Garanta que o enriquecimento de dados está amparado pelo consentimento do titular ou por outra base legal aplicável. A Autoridade Nacional de Proteção de Dados (ANPD) disponibiliza orientações sobre as bases legais previstas na Lei nº 13.709/2018.

• Não sobrescreva dados confirmados — Se o contato já informou seus dados e eles foram confirmados, não sobrescreva automaticamente. Use os dados da API apenas para preencher campos vazios ou corrigir dados incompletos.

• Registre a origem dos dados — Marque no CRM quais campos foram preenchidos via API, para rastreabilidade e auditoria.

• Insira intervalos entre consultas — Em lotes grandes, adicione delays entre as requisições para distribuir o consumo ao longo do tempo.

• Valide antes de salvar — Verifique se os dados retornados pela API são consistentes antes de atualizar o CRM.

Perguntas frequentes

É possível enriquecer uma base de CRM inteira de uma vez com a API de CPF?

Sim, mas o ideal é fazer em lotes agendados. Para bases grandes, processe em batches diários conforme o volume do seu plano — 50 consultas/mês no Gratuito, 1.000 no Pro. Ao superar o limite, a API não bloqueia: consultas excedentes são cobradas a R$0,15 cada. Isso permite escalar o enriquecimento sem interrupção, ajustando o ritmo conforme o orçamento.

Que campos a API retorna para enriquecer o CRM?

Para cada CPF, a API retorna: nome completo, nome em maiúsculas, gênero (M/F), data de nascimento (dia, mês e ano separados). Com esses dados, é possível preencher nome, gênero, data de nascimento e calcular faixa etária automaticamente — eliminando a necessidade de formulários longos no cadastro.

Como evitar sobrescrever dados que o próprio contato informou?

Antes de atualizar o registro no CRM, verifique se o campo já está preenchido. No script Python da seção acima, o padrão é checar if not contato.get('nome') antes de substituir. Para campos como gênero, que o usuário pode ter informado corretamente, adicione uma flag enriquecido_via_api para distinguir dados fornecidos pelo titular de dados vindos da consulta.

O enriquecimento de dados de CRM com CPF é permitido pela LGPD?

Sim, desde que haja base legal. As mais usadas nesse contexto são consentimento (Art. 7, I) — quando o contato aceitou os termos ao se cadastrar — e legítimo interesse (Art. 7, IX) — quando o enriquecimento é necessário para a finalidade comercial do tratamento. Documente a base legal adotada e inclua essa finalidade na política de privacidade.

Conclusão

Enriquecer dados de CRM com informações de CPF é uma forma eficiente de melhorar a qualidade da base de contatos, personalizar o atendimento e aumentar a eficácia das campanhas de marketing. Com a API da CPFHub.io, o processo pode ser totalmente automatizado — seja via webhook no cadastro de novos leads, seja via job agendado para sanitizar a base existente. O resultado é um CRM mais completo sem exigir que os contatos preencham formulários longos.

A latência média de ~900ms permite integrar a consulta ao fluxo de onboarding sem impacto perceptível para o usuário. O plano gratuito cobre os primeiros 50 testes sem cartão; o plano Pro garante 1.000 consultas mensais para operações em escala. Consultas acima do limite nunca bloqueiam — são cobradas automaticamente a R$0,15 cada.

Crie sua conta em cpfhub.io e comece a enriquecer sua base de CRM hoje mesmo.