NovoVerificação de identidade facial

Como usar API de CPF para enriquecer dados de CRM automaticamente

Aprenda a usar a API de CPF para enriquecer automaticamente os dados do seu CRM com nome completo, data de nascimento e gênero dos contatos.

Lucas Vieira
Lucas Vieira
··8 min de leitura
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 ~150 ms — dados que preenchem automaticamente os campos vazios ou incompletos de cada contato na base. No gratuito, zerar os 50 créditos do mês interrompe as consultas com HTTP 403 ("Limite de créditos excedido"). Nos planos pagos o excedente não é um valor único: ele varia e está publicado na página de preços. O limite por minuto responde HTTP 429 com Retry-After.

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

Campo no CRMAntesDepois (via API)
NomeC. OliveiraCarla Mendes Oliveira
Data de nascimento(vazio)08/11/1988
Gênero(vazio)F
Faixa etária(vazio)36-45

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 créditos/mês no Gratuito, 1.000 no Pro. Essa cota grátis não continua depois do fim: a API responde HTTP 403 ("Limite de créditos excedido") e as consultas param. O excedente dos planos pagos, quando existe, está na página de preços. O limite por minuto segue separado, com HTTP 429 e Retry-After.

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 ~150 ms 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 créditos mensais para operações em escala. Quando os créditos do Grátis acabam, a API pausa e devolve HTTP 403, "Limite de créditos excedido". Se o plano for pago e tiver excedente, a cobrança extra sai na fatura seguinte — veja a página de preços. O teto por minuto, se estourado, responde HTTP 429 com Retry-After.

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

CPFHub.io

Pronto para integrar a API?

50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.

WhatsApp