Use a validação em tempo real (consulta individual e síncrona) quando o usuário está esperando a resposta, como no cadastro ou no checkout, e o CPF em Lote quando a lista já existe, como numa limpeza de base ou numa importação. Na CPFHub.io, a consulta individual é a Consulta Simples (GET /cpf/{cpf}, cerca de 150 ms, nome, gênero e data de nascimento); o lote é POST /cpf/bulk, com até 10.000 CPFs por envio, processados de forma assíncrona. Se você precisa da situação cadastral na Receita Federal, a opção é a Consulta em Tempo Real na Receita (POST /cpf/realtime, cerca de 1 s), que funciona só CPF a CPF. A maioria das operações de médio porte combina consulta individual na entrada e lote para a base existente.
Validação em tempo real
O que é
Neste artigo, "tempo real" quer dizer consulta individual e síncrona: a API é chamada no momento exato em que o CPF é informado, geralmente durante o preenchimento de um formulário, no checkout de uma compra ou no onboarding de um novo cliente, e o resultado volta na mesma requisição.
Na CPFHub.io existem dois tipos de consulta individual, e vale não confundir os dois:
- Consulta Simples (
GET /cpf/{cpf}): consulta a base da CPFHub.io e retorna nome, gênero e data de nascimento. Tempo típico de cerca de 150 ms. Custa 1 crédito por CPF encontrado. - Consulta em Tempo Real na Receita (
POST /cpf/realtime): consulta a Receita Federal na hora, exige CPF e data de nascimento e retorna a situação cadastral (por exemplo,REGULAR,SUSPENSA,TITULAR FALECIDO) e o ano do óbito. Leva cerca de 1 s e custa 1,5 crédito por consulta bem-sucedida. Detalhes na página da Consulta de CPF na Receita Federal.
Quando usar
- Onboarding de clientes: validar o CPF antes de prosseguir com o cadastro evita dados falsos desde o início.
- Checkout de e-commerce: confirmar a identidade do comprador antes de processar o pagamento.
- Concessão de crédito: verificar dados do solicitante antes de aprovar uma proposta. Aqui a situação cadastral costuma importar, então a Consulta em Tempo Real na Receita faz mais sentido.
- Cadastro de motoristas/prestadores: validar antes de ativar o perfil na plataforma.
Implementação com a Consulta Simples
const axios = require("axios");
const API_KEY = process.env.CPFHUB_API_KEY;
const TIMEOUT_MS = 30000;
async function validarCPFTempoReal(cpf) {
const cpfLimpo = cpf.replace(/\D/g, "");
const inicio = Date.now();
try {
const response = await axios.get(
`https://api.cpfhub.io/cpf/${cpfLimpo}`,
{
headers: { "x-api-key": API_KEY },
timeout: TIMEOUT_MS
}
);
const latencia = Date.now() - inicio;
console.log(`Consulta em ${latencia}ms`);
return {
valido: true,
nome: response.data.data.name,
nascimento: response.data.data.birthDate
};
} catch (error) {
if (error.code === "ECONNABORTED") {
return { valido: false, motivo: "timeout" };
}
const status = error.response?.status;
if (status === 404) {
// CPF não encontrado: não consome crédito
return { valido: false, motivo: "CPF nao encontrado" };
}
// 403 (créditos), 422 (dígito verificador), 429 (limite por minuto) etc.
return { valido: false, motivo: `HTTP ${status ?? error.message}` };
}
}
// Uso no formulário de cadastro
validarCPFTempoReal("123.456.789-09").then(resultado => {
if (resultado.valido) {
console.log(`Bem-vindo, ${resultado.nome}!`);
} else {
console.log(`Validacao falhou: ${resultado.motivo}`);
}
});
Quando precisa da situação cadastral: Consulta em Tempo Real na Receita
POST https://api.cpfhub.io/cpf/realtime
Content-Type: application/json
x-api-key: SUA_API_KEY
{ "cpf": "12345678909", "birthDate": "15/06/1990" }
A resposta traz situation (situação cadastral como a Receita informa), deathYear (inteiro ou null) e, quando a Receita fornece, os dados do comprovante. Use timeout de pelo menos 60 s no cliente e não repita a chamada depois de um timeout local: o POST não é idempotente. Erros 502 e 503 vindos da Receita não consomem crédito. Referência completa na documentação da Consulta em Tempo Real.
Vantagens
- Feedback imediato ao usuário.
- Impede que dados inválidos entrem no sistema.
- Reduz retrabalho posterior.
Desvantagens
- Cada interação consome crédito (1 na Consulta Simples, 1,5 na Consulta em Tempo Real na Receita).
- Adiciona latência ao fluxo do usuário: cerca de 150 ms na Consulta Simples e cerca de 1 s na Consulta em Tempo Real na Receita.
- Requer tratamento de falhas para não bloquear o fluxo principal.
- Tem limite por minuto: 30 requisições/min na Consulta Simples e 5/min na Consulta em Tempo Real, no padrão.
Validação em lote
O que é
A validação em lote acumula CPFs e os processa de uma só vez, geralmente em horários de menor demanda ou em ciclos periódicos (diário, semanal). Na CPFHub.io, isso é o CPF em Lote: você envia até 10.000 CPFs em JSON com POST /cpf/bulk, recebe um jobId e acompanha o processamento em GET /cpf/bulk/{jobId}. O lote usa a Consulta Simples, então retorna nome, gênero e data de nascimento, sem situação cadastral. A Consulta em Tempo Real na Receita não existe em lote.
Quando usar
- Limpeza de base cadastral: validar milhares de CPFs já existentes no banco de dados.
- Importação de dados: verificar CPFs recebidos em planilhas de parceiros ou fornecedores.
- Auditoria periódica: revalidar cadastros antigos para garantir consistência.
- Migração de sistemas: validar dados durante a migração de um sistema legado.
Implementação em lote
import csv
import json
import os
import time
import requests
API_KEY = os.environ["CPFHUB_API_KEY"]
BULK_URL = "https://api.cpfhub.io/cpf/bulk"
MAX_POR_LOTE = 10_000
def enviar_lote(cpfs: list) -> str:
"""Envia até 10.000 CPFs e devolve o jobId."""
r = requests.post(BULK_URL, headers={"x-api-key": API_KEY},
json={"cpfs": cpfs}, timeout=60)
if r.status_code != 202:
# 400 (lista inválida ou > 10.000), 403 (saldo insuficiente),
# 422 (nenhum CPF válido), 429 (limite por minuto)
raise RuntimeError(f"HTTP {r.status_code}: {r.text}")
return r.json()["data"]["jobId"]
def aguardar(job_id: str, intervalo: int = 10) -> dict:
"""Consulta o status até done ou failed. Consultar status não cobra crédito."""
while True:
r = requests.get(f"{BULK_URL}/{job_id}", headers={"x-api-key": API_KEY}, timeout=60)
r.raise_for_status()
corpo = r.json()
if corpo["data"]["status"] in ("done", "failed"):
return corpo
time.sleep(intervalo)
def processar_lote(arquivo_entrada: str, arquivo_saida: str):
"""Lê um CSV de CPFs e processa em jobs de até 10.000."""
with open(arquivo_entrada) as f:
cpfs = [linha[0].strip() for linha in csv.reader(f) if linha]
with open(arquivo_saida, "w") as saida:
for i in range(0, len(cpfs), MAX_POR_LOTE):
job_id = enviar_lote(cpfs[i:i + MAX_POR_LOTE])
resultado = aguardar(job_id)
saida.write(json.dumps(resultado) + "\n")
print(f"Job {job_id}: {resultado['data']['status']}")
processar_lote("cpfs_para_validar.csv", "resultados_validacao.jsonl")
A API recebe a lista em JSON, não upload de arquivo. Se preferir enviar o CSV direto, o painel em app.cpfhub.io aceita. CPFs inválidos são descartados sem custo, repetidos são consultados uma vez e só os encontrados consomem crédito. Em planos sem excedente, o envio confere o saldo antes e recusa o lote inteiro (HTTP 403) se não houver crédito para todos os CPFs válidos. Mais detalhes na referência do lote.
Vantagens
- Processamento eficiente de grandes volumes, sem precisar controlar o limite por minuto CPF a CPF.
- Pode rodar em horários de menor demanda.
- Cada envio conta como uma única requisição no limite por minuto.
- Facilita auditoria e geração de relatórios.
Desvantagens
- Não oferece feedback imediato ao usuário.
- Dados inválidos podem permanecer no sistema até o próximo ciclo de validação.
- Não traz situação cadastral: a Consulta em Tempo Real na Receita é só CPF a CPF.
- Requer infraestrutura para agendamento (cron, scheduler).
Comparativo direto
| Aspecto | Consulta Simples (GET /cpf/{cpf}) | Tempo Real na Receita (POST /cpf/realtime) | Lote (POST /cpf/bulk) |
|---|---|---|---|
| Latência | ~150 ms por consulta | ~1 s por consulta | Assíncrono; total depende do volume |
| Retorna | Nome, gênero, data de nascimento | Situação cadastral, ano do óbito, nome | Nome, gênero, data de nascimento |
| Entrada | CPF | CPF + data de nascimento | Até 10.000 CPFs em JSON |
| Custo | 1 crédito por CPF encontrado | 1,5 crédito por consulta bem-sucedida | 1 crédito por CPF encontrado |
| Limite padrão | 30 req/min | 5 req/min | Cada envio conta 1 no limite da Consulta Simples |
| Ideal para | Onboarding, checkout | Crédito, cadastro que exige CPF regular | Limpeza, auditoria, importação |
Abordagem híbrida
Na prática, a maioria das empresas se beneficia de uma abordagem híbrida:
- Consulta individual no ponto de entrada: validar CPFs novos no momento do cadastro ou transação, com a Consulta Simples ou, quando a situação cadastral importa, com a Consulta em Tempo Real na Receita.
- Lote para a base existente: revalidar periodicamente os CPFs já cadastrados com
POST /cpf/bulk.
class ValidadorCPFHibrido:
"""Validador que combina consulta individual e lote."""
def __init__(self):
self.fila_lote = []
def validar_tempo_real(self, cpf: str) -> requests.Response:
"""Consulta Simples imediata, para novos cadastros."""
return requests.get(f"https://api.cpfhub.io/cpf/{cpf}",
headers={"x-api-key": API_KEY}, timeout=30)
def enfileirar_para_lote(self, cpf: str):
"""Enfileira para revalidação posterior."""
self.fila_lote.append(cpf)
def processar_fila(self):
"""Envia a fila em jobs de até 10.000 CPFs."""
resultados = []
for i in range(0, len(self.fila_lote), MAX_POR_LOTE):
job_id = enviar_lote(self.fila_lote[i:i + MAX_POR_LOTE])
resultados.append(aguardar(job_id))
self.fila_lote.clear()
return resultados
Se a sua operação também valida empresas, a mesma lógica vale para CNPJ: GET /cnpj/{cnpj} no cadastro e o CNPJ em Lote (POST /cnpj/bulk, até 10.000 CNPJs) para a carteira existente.
Considerações de cota e custo
Com o plano Pro de 1.000 créditos da CPFHub.io (R$ 149/mês):
- Cenário tempo real: se você tem 800 cadastros novos por mês na Consulta Simples, restam 200 créditos para revalidação em lote.
- Cenário lote: se o fluxo de novos cadastros é baixo (100/mês), sobram 900 créditos para limpeza de base.
- Cenário com Receita: cada Consulta em Tempo Real na Receita custa 1,5 crédito, então 400 consultas desse tipo usam 600 créditos.
O Pro também tem faixas de R$ 19 (100 créditos), R$ 599 (5.000) e R$ 999 (10.000) por mês. No Grátis, zerar os 50 créditos do mês interrompe as consultas com HTTP 403 ("Limite de créditos excedido"). Nos planos pagos com excedente ativo, o valor por crédito extra varia por faixa e está publicado na página de preços. Vale planejar o volume esperado para evitar surpresas na fatura.
Perguntas frequentes
Qual abordagem consome menos cota da API: tempo real ou lote?
Na Consulta Simples e no lote, o custo é o mesmo: 1 crédito por CPF encontrado. O lote ajuda a controlar o ritmo de consumo e facilita o monitoramento, mas não reduz a quantidade de créditos. No lote, repetidos dentro do mesmo envio são consultados uma vez. A Consulta em Tempo Real na Receita custa mais (1,5 crédito) porque consulta a Receita Federal na hora.
Existe Consulta em Tempo Real na Receita em lote?
Não. A Consulta em Tempo Real (POST /cpf/realtime) é feita CPF a CPF, exige a data de nascimento e tem limite padrão de 5 requisições por minuto. O lote (POST /cpf/bulk) usa a Consulta Simples e retorna nome, gênero e data de nascimento, sem situação cadastral.
A API CPFHub.io tem rate limit diferente para cada plano?
O limite padrão é por API Key: 30 requisições por minuto na Consulta Simples (cada envio de lote conta como 1) e 5 por minuto na Consulta em Tempo Real na Receita. Planos personalizados podem ter limites diferentes. Passar do limite retorna HTTP 429 com Retry-After, o que é diferente de esgotar a franquia mensal: no Grátis, zerar os 50 créditos retorna HTTP 403 ("Limite de créditos excedido") e as consultas param. Nos planos pagos com excedente ativo, o excedente fica na página de preços.
Como lidar com falhas de rede durante o processamento em lote?
Guarde o jobId de cada envio. Se a conexão cair depois do POST /cpf/bulk, consulte GET /cpf/bulk/{jobId} em vez de reenviar: o POST não é idempotente e repetir pode criar um segundo lote. Para bases grandes, divida em jobs de até 10.000 e marque cada um como concluído só depois de salvar o resultado.
Posso misturar validação em tempo real e em lote na mesma aplicação?
Sim, e é a abordagem recomendada para a maioria dos sistemas. Use consulta individual no ponto de entrada (formulários, checkout, onboarding) e reserve o lote para auditorias periódicas da base existente. A LGPD também favorece essa separação, pois facilita documentar a finalidade de cada consulta.
Conclusão
A escolha depende do contexto. Fluxos em que o usuário está esperando (onboarding, checkout) pedem consulta individual: a Consulta Simples quando nome e data de nascimento bastam, a Consulta em Tempo Real na Receita quando a situação cadastral importa. Auditoria, limpeza de base e importação de dados ficam com o lote. Combinar os dois costuma ser o caminho mais barato e mais simples de manter.
Conheça o CPF em Lote da CPFHub.io e crie sua conta em cpfhub.io: 50 créditos mensais gratuitos, sem cartão, e planos Pro a partir de R$ 19 por mês.
CPFHub.io
Pronto para integrar a API?
50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.




