Como fazer consulta de CPF em lote (batch) via API de forma eficiente

Para fazer consulta de CPF em lote via API, envie requisições individuais de forma sequencial ou concorrente com um intervalo de pelo menos 1,1 segundo entre cada chamada (plano Pro), trate respostas HTTP 429 com exponential backoff e persista os resultados parciais em arquivo ou banco de dados para retomada segura em caso de interrupção.

Introdução

Empresas que lidam com grandes volumes de cadastros frequentemente precisam validar centenas ou milhares de CPFs de uma só vez. Seja para atualização cadastral, limpeza de base de dados ou processos de compliance, a consulta em lote (batch) é uma necessidade real para equipes de tecnologia e operações.

A CPFHub.io oferece uma API REST com latência de aproximadamente 900ms por consulta, planos flexíveis e documentação completa para implementar processamento em lote em qualquer linguagem, com suporte a Python, Node.js, PHP, Bash e outras.

O que significa consulta de CPF em lote

A consulta de CPF em lote (ou batch) consiste em enviar múltiplas requisições de validação de CPF de forma sequencial ou concorrente, processando uma lista de números de CPF e coletando os resultados de cada consulta individual.

Diferente de um endpoint que aceita vários CPFs em uma única chamada, o modelo de consulta individual com processamento em lote oferece algumas vantagens:

• Controle granular -- Cada consulta tem seu próprio status de sucesso ou erro, facilitando o tratamento individual de falhas.

• Rastreabilidade -- É possível saber exatamente qual CPF falhou e por qual motivo, sem comprometer o restante do lote.

• Resiliência -- Se uma consulta falha, as demais continuam normalmente.

• Flexibilidade -- Permite ajustar a velocidade de processamento conforme o plano contratado.

Entendendo os rate limits da API

Antes de implementar qualquer solução de consulta em lote, é fundamental entender os limites de taxa (rate limits) da API da CPFHub.io. Consulte sempre a documentação oficial da Receita Federal para entender as implicações regulatórias do tratamento em lote de dados de CPF.

Ao exceder o rate limit, a API retorna o código HTTP 429 (Too Many Requests). Por isso, qualquer implementação de lote deve incluir lógica de controle de intervalo entre requisições e tratamento de erros.

Estratégia básica: fila sequencial com delay

A abordagem mais simples e segura é processar os CPFs de forma sequencial, com um intervalo fixo entre cada requisição. Veja um exemplo em Python:

import requests
import time
import json

API_KEY = "SUA_CHAVE_DE_API"
BASE_URL = "https://api.cpfhub.io/cpf"
DELAY_SECONDS = 1.1 # Margem de segurança para o rate limit do plano Pro

cpfs = [
    "12345678901",
    "98765432100",
    "11122233344",
    # ... adicione mais CPFs conforme necessário
]

resultados = []

for cpf in cpfs:
    try:
    response = requests.get(
    f"{BASE_URL}/{cpf}",
    headers={
    "x-api-key": API_KEY,
    "Accept": "application/json"
    },
    timeout=10
    )

    if response.status_code == 200:
    data = response.json()
    resultados.append(data)
    print(f"CPF {cpf}: {data['data']['name']}")
    elif response.status_code == 429:
    print(f"Rate limit atingido. Aguardando 5 segundos...")
    time.sleep(5)
    else:
    print(f"Erro no CPF {cpf}: HTTP {response.status_code}")

    except requests.exceptions.Timeout:
    print(f"Timeout na consulta do CPF {cpf}")

    time.sleep(DELAY_SECONDS)

# Salvar resultados em arquivo JSON
with open("resultados_cpf.json", "w") as f:
    json.dump(resultados, f, indent=2, ensure_ascii=False)

print(f"Total processado: {len(resultados)} de {len(cpfs)}")

Essa abordagem funciona bem para volumes pequenos a médios (até algumas centenas de CPFs). O delay de 1.1 segundo garante que não se ultrapasse o rate limit do plano Pro.

Estratégia avançada: processamento concorrente com controle de taxa

Para volumes maiores, é possível usar processamento assíncrono com controle de taxa. Em Node.js, por exemplo:

const fetch = require('node-fetch');

const API_KEY = 'SUA_CHAVE_DE_API';
const BASE_URL = 'https://api.cpfhub.io/cpf';
const DELAY_MS = 1100;

const cpfs = [
    '12345678901',
    '98765432100',
    '11122233344',
    // ... mais CPFs
];

function sleep(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function consultarCPF(cpf) {
    const response = await fetch(`${BASE_URL}/${cpf}`, {
    method: 'GET',
    headers: {
    'x-api-key': API_KEY,
    'Accept': 'application/json'
    },
    timeout: 10000
    });

    if (response.status === 429) {
    console.log('Rate limit atingido. Aguardando...');
    await sleep(5000);
    return consultarCPF(cpf); // Retry
    }

    return response.json();
}

async function processarLote(listaCpfs) {
    const resultados = [];

    for (const cpf of listaCpfs) {
    try {
    const resultado = await consultarCPF(cpf);
    resultados.push({ cpf, ...resultado });
    console.log(`Processado: ${cpf}`);
    } catch (error) {
    console.error(`Erro no CPF ${cpf}: ${error.message}`);
    resultados.push({ cpf, error: error.message });
    }

    await sleep(DELAY_MS);
    }

    return resultados;
}

processarLote(cpfs).then(resultados => {
    console.log(`Total processado: ${resultados.length}`);
});

Implementando retry com exponential backoff

Quando a API retorna o código 429 (Too Many Requests), a melhor prática é implementar retry com exponential backoff. Isso significa aumentar progressivamente o tempo de espera entre tentativas:

import requests
import time

def consultar_cpf_com_retry(cpf, api_key, max_retries=3):
    base_url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": api_key,
    "Accept": "application/json"
    }

    for tentativa in range(max_retries):
    try:
    response = requests.get(base_url, headers=headers, timeout=10)

    if response.status_code == 200:
    return response.json()
    elif response.status_code == 429:
    wait_time = (2 ** tentativa) + 1 # 2s, 5s, 9s
    print(f"Rate limit. Tentativa {tentativa + 1}. Aguardando {wait_time}s...")
    time.sleep(wait_time)
    else:
    return {"error": f"HTTP {response.status_code}"}

    except requests.exceptions.Timeout:
    print(f"Timeout. Tentativa {tentativa + 1}")
    time.sleep(2)

    return {"error": "Máximo de tentativas excedido"}

O exponential backoff é especialmente importante em cenários de lote, pois evita que o sistema fique preso em um loop de erros 429 consecutivos.

Boas práticas para consulta em lote

Divida em lotes menores

Em vez de processar milhares de CPFs em uma única execução, divida a lista em lotes menores (por exemplo, 100 CPFs por lote) com pausas entre os lotes. Isso reduz o risco de problemas de memória e facilita o monitoramento.

Persista resultados intermediários

Salve os resultados parciais em arquivo ou banco de dados à medida que forem processados. Caso a execução seja interrompida, é possível retomar de onde parou sem reprocessar CPFs já consultados.

Monitore o consumo de consultas

O dashboard da CPFHub.io em app.cpfhub.io exibe o consumo mensal em tempo real, permitindo acompanhar quanto do limite já foi utilizado e planejar a execução de lotes grandes com antecedência.

Valide localmente antes de consultar

Antes de enviar um CPF para a API, valide o formato e os dígitos verificadores localmente. Isso evita gastar consultas do seu plano com CPFs que já sabemos serem inválidos:

def validar_cpf_local(cpf):
    cpf = ''.join(filter(str.isdigit, cpf))

    if len(cpf) != 11 or cpf == cpf[0] * 11:
    return False

    for i in range(9, 11):
    valor = sum(int(cpf[num]) * ((i + 1) - num) for num in range(0, i))
    digito = ((valor * 10) % 11) % 10
    if digito != int(cpf[i]):
    return False

    return True

Escolha o plano adequado

Para consultas em lote com volume significativo, o plano Pro (1.000 consultas/mês, 1 requisição por segundo) ou o plano Corporativo (volume personalizado) são as opções mais adequadas. O plano Grátis, com 50 consultas/mês e rate limit de 1 requisição a cada 2 segundos, é ideal para testes e prototipagem.

Exemplo completo com cURL em script Bash

Para quem prefere uma solução simples via linha de comando, é possível usar um script Bash com cURL:

#!/bin/bash

API_KEY="SUA_CHAVE_DE_API"
INPUT_FILE="lista_cpfs.txt"
OUTPUT_FILE="resultados.json"

echo "[" > "$OUTPUT_FILE"
FIRST=true

while IFS= read -r cpf; do
    cpf=$(echo "$cpf" | tr -d '[:space:].-')

    if [ ${#cpf} -ne 11 ]; then
    echo "CPF inválido ignorado: $cpf"
    continue
    fi

    RESPONSE=$(curl -s -X GET "https://api.cpfhub.io/cpf/$cpf" \
    -H "x-api-key: $API_KEY" \
    -H "Accept: application/json" \
    --max-time 10)

    if [ "$FIRST" = true ]; then
    FIRST=false
    else
    echo "," >> "$OUTPUT_FILE"
    fi

    echo "$RESPONSE" >> "$OUTPUT_FILE"
    echo "Consultado: $cpf"

    sleep 1.1
done < "$INPUT_FILE"

echo "]" >> "$OUTPUT_FILE"
echo "Processamento concluído."

Basta criar um arquivo lista_cpfs.txt com um CPF por linha e executar o script.

Perguntas frequentes

Como controlar o rate limit em processamento batch de CPF?

Implemente um delay fixo entre requisições — 1,1 segundo para o plano Pro e 2,1 segundos para o plano Grátis. Quando receber HTTP 429, aplique exponential backoff: aguarde 2s na primeira tentativa, 5s na segunda e 9s na terceira. Evite paralelismo agressivo; processe no máximo um CPF por vez para garantir previsibilidade.

Quantos CPFs posso processar por hora em lote?

No plano Pro (1 requisição/segundo), o limite teórico é 3.600 CPFs por hora. Na prática, com um delay de 1,1s e latência de resposta de ~900ms, o ritmo sustentável fica em torno de 1.800 a 2.000 CPFs/hora. Para volumes maiores, o plano Corporativo oferece rate limits personalizados.

O que acontece se meu lote ultrapassar o limite mensal de consultas?

A API da CPFHub.io não bloqueia quando o limite mensal é atingido — ela continua funcionando e cobra R$ 0,15 por consulta adicional. Para lotes grandes, monitore o consumo em app.cpfhub.io antes de iniciar a execução e estime o custo total com antecedência.

Como retomar um lote interrompido sem repetir consultas já feitas?

Persista os resultados em arquivo JSON ou banco de dados após cada consulta bem-sucedida. No início de cada execução, carregue a lista de CPFs já processados e filtre-os da lista de entrada. Essa estratégia de checkpoint elimina reprocessamento e evita consumo desnecessário de consultas do plano.

Conclusão

A consulta de CPF em lote via API é uma operação comum e necessária para empresas que precisam validar grandes volumes de cadastros. Com as estratégias corretas -- controle de rate limit, retry com exponential backoff, validação local prévia e persistência de resultados intermediários -- é possível processar lotes de forma eficiente e confiável.

A CPFHub.io oferece planos adequados para cada volume, desde testes com o plano Grátis (50 consultas/mês) até operações corporativas com limites personalizados, todos com latência de aproximadamente 900ms e conformidade com a LGPD.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e processe seu primeiro lote de CPFs hoje mesmo.