NovoVerificação de identidade facial

API de CPF para validação em tempo real vs. validação em lote: quando usar cada uma

Consulta individual, Consulta em Tempo Real na Receita ou lote de até 10.000 CPFs: quando usar cada modelo da API de CPF da CPFHub.io.

Lucas Vieira
Lucas Vieira
··11 min de leitura
API de CPF para validação em tempo real vs. validação em lote: quando usar cada uma

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

AspectoConsulta Simples (GET /cpf/{cpf})Tempo Real na Receita (POST /cpf/realtime)Lote (POST /cpf/bulk)
Latência~150 ms por consulta~1 s por consultaAssíncrono; total depende do volume
RetornaNome, gênero, data de nascimentoSituação cadastral, ano do óbito, nomeNome, gênero, data de nascimento
EntradaCPFCPF + data de nascimentoAté 10.000 CPFs em JSON
Custo1 crédito por CPF encontrado1,5 crédito por consulta bem-sucedida1 crédito por CPF encontrado
Limite padrão30 req/min5 req/minCada envio conta 1 no limite da Consulta Simples
Ideal paraOnboarding, checkoutCrédito, cadastro que exige CPF regularLimpeza, auditoria, importação

Abordagem híbrida

Na prática, a maioria das empresas se beneficia de uma abordagem híbrida:

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

WhatsApp