NovoVerificação de identidade facial

Como usar paginação e filtros ao consultar CPFs em lote via API

Divida bases grandes em lotes de até 10.000 CPFs, filtre antes de enviar e acompanhe cada job da API de lote da CPFHub.io (POST /cpf/bulk).

Lucas Vieira
Lucas Vieira
··8 min de leitura
Como usar paginação e filtros ao consultar CPFs em lote via API

A API de consulta de CPF em lote da CPFHub.io recebe até 10.000 CPFs por envio (POST /cpf/bulk), processa de forma assíncrona e devolve um jobId para você acompanhar em GET /cpf/bulk/{jobId}. A API não tem parâmetros de paginação nem de filtro: a paginação acontece do seu lado, dividindo bases maiores que 10.000 CPFs em vários jobs, e os filtros (formato, duplicados, cache) entram antes do envio. Só CPFs encontrados consomem crédito, 1 por CPF.

Introdução

Processar grandes volumes de CPFs exige mais do que mandar requisições em sequência. Chamar a consulta individual milhares de vezes esbarra no limite padrão de 30 requisições por minuto e deixa você cuidando de fila, retentativa e progresso na mão. O lote resolve a maior parte disso no servidor. O que sobra para o seu código é dividir a base, limpar a lista antes de enviar e guardar em que ponto o processamento parou.

Por que paginação importa em consultas em lote

Mesmo com a API de lote, dividir a base em partes resolve problemas reais:

  • Teto de 10.000 por envio: uma base de 45.000 CPFs vira 5 jobs. Acima de 10.000 itens, o envio é recusado com HTTP 400.
  • Saldo de créditos: em planos sem excedente, o envio confere o saldo antes. Se não cobre todos os CPFs válidos, a API responde 403 ("Créditos insuficientes para o lote: N necessários.") e o lote não é criado. Jobs menores ajudam a encaixar o consumo no saldo.
  • Recuperação de falhas: se o seu processo cair no meio, um checkpoint por job evita reenviar o que já foi consultado.
  • Visibilidade e custo: um job por parte deixa claro quanto já foi processado e quanto foi gasto.

Modelos de paginação para consultas de CPF

Como a API de lote não pagina por conta própria, estes são modelos para o seu lado da integração:

ModeloMecanismoMelhor paraLimitação
Chunk em jobsDividir a lista em blocos de até 10.000 e enviar cada um com POST /cpf/bulkBases grandes, processamento periódicoExige guardar o jobId de cada bloco
Leitura paginada da sua baseLer o seu banco por cursor ou offset e montar os blocosBases que não cabem em memóriaInconsistência se a base muda durante a leitura
Item a itemGET /cpf/{cpf} para cada CPFVolumes pequenos ou fluxo de cadastroLimite padrão de 30 requisições/min

Implementação de processamento paginado com Python

O exemplo abaixo filtra a lista, divide em blocos de até 10.000, envia um job por vez, acompanha o status até done ou failed e grava um checkpoint por bloco. O resultado de cada job é salvo em JSON, uma linha por job.

import json
import os
import time
import requests

API_KEY = os.environ["CPFHUB_API_KEY"]
BASE_URL = "https://api.cpfhub.io/cpf/bulk"
TAMANHO_BLOCO = 10_000  # máximo aceito por envio
CHECKPOINT = "checkpoint.json"
SAIDA = "resultados.jsonl"


def filtrar(cpfs_brutos):
    """Limpa formato, descarta sequências repetidas e remove duplicados."""
    vistos, validos = set(), []
    for cpf in cpfs_brutos:
        c = "".join(ch for ch in str(cpf) if ch.isdigit())
        if len(c) == 11 and c != c[0] * 11 and c not in vistos:
            vistos.add(c)
            validos.append(c)
    return validos


def paginar(cpfs, tamanho=TAMANHO_BLOCO):
    for i in range(0, len(cpfs), tamanho):
        yield cpfs[i:i + tamanho]


def enviar_bloco(bloco):
    r = requests.post(
        BASE_URL,
        headers={"x-api-key": API_KEY},
        json={"cpfs": bloco},
        timeout=60,
    )
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "60")))
        return enviar_bloco(bloco)
    if r.status_code != 202:
        # 400 (corpo inválido ou > 10.000), 403 (saldo insuficiente), 422 (nenhum CPF válido)
        raise RuntimeError(f"Envio recusado: HTTP {r.status_code} {r.text}")
    return r.json()["data"]["jobId"]


def aguardar(job_id, intervalo=10):
    while True:
        r = requests.get(f"{BASE_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(cpfs_brutos):
    cpfs = filtrar(cpfs_brutos)
    blocos = list(paginar(cpfs))
    print(f"{len(cpfs)} CPFs válidos e únicos em {len(blocos)} bloco(s)")

    feitos = json.load(open(CHECKPOINT)) if os.path.exists(CHECKPOINT) else []

    for n, bloco in enumerate(blocos):
        if n in feitos:
            continue  # bloco já processado em uma execução anterior
        job_id = enviar_bloco(bloco)
        resultado = aguardar(job_id)
        with open(SAIDA, "a") as f:
            f.write(json.dumps({"bloco": n, "jobId": job_id, "resultado": resultado}) + "\n")
        feitos.append(n)
        json.dump(feitos, open(CHECKPOINT, "w"))
        print(f"Bloco {n + 1}/{len(blocos)}: {resultado['data']['status']}")


processar(["123.456.789-09", "111.444.777-35", "111.444.777-35"])

Dois cuidados no código: o POST /cpf/bulk não é idempotente, então depois de um timeout local não reenvie o mesmo bloco sem antes conferir se o job foi criado; e o checkpoint só é gravado depois que o job termina, para nenhum bloco ficar marcado como feito sem resultado salvo.


A API de lote da CPFHub.io em resumo

O CPF em Lote é a consulta simples aplicada a uma lista inteira:

POST https://api.cpfhub.io/cpf/bulk
Content-Type: application/json
x-api-key: SUA_API_KEY

{ "cpfs": ["12345678909", "11144477735"] }
  • Resposta do envio: 202 com {"success":true,"data":{"jobId":"...","status":"processing","totalRecords":2,"invalid":0}}.
  • Status: GET /cpf/bulk/{jobId} até data.status ser done ou failed. Consultar o status não consome crédito.
  • O que cada CPF encontrado traz: os mesmos dados da consulta simples: nome, gênero e data de nascimento.
  • Custo: 1 crédito por CPF com found: true. CPFs inválidos são descartados e contados em invalid; repetidos são consultados uma vez.
  • Formato: a API recebe JSON, não upload de arquivo. No painel em app.cpfhub.io dá para enviar CSV.
  • Limite por minuto: cada envio conta como 1 requisição no limite da consulta simples (30/min no padrão).

Referência completa na documentação do lote. Para CNPJ existe o equivalente, o CNPJ em Lote (POST /cnpj/bulk, também até 10.000 por envio).


Filtros úteis para processamento em lote

Os filtros que economizam crédito são os aplicados antes do envio:

  • Filtro sintático: eliminar CPFs com formato inválido ou sequência de dígitos iguais. A API já descarta inválidos sem cobrar, mas filtrar antes deixa o seu relatório mais limpo.
  • Filtro de deduplicação: remover repetidos antes de montar os blocos, para que um mesmo CPF não caia em dois jobs diferentes e seja cobrado duas vezes.
  • Filtro de cache: excluir CPFs que você já consultou recentemente e guardou o resultado.

Filtros por gênero ou faixa etária não existem na API. Se a sua operação precisa segmentar, aplique o filtro nos resultados depois que o job terminar, usando a data de nascimento e o gênero retornados.


Otimizações avançadas

Para volumes de centenas de milhares de CPFs:

  • Um job por vez, ou poucos em paralelo: cada envio conta no limite por minuto, e o seu saldo precisa cobrir cada bloco enviado.
  • Checkpoint por bloco: salve o índice do último bloco concluído (e o jobId) para retomar sem reenviar.
  • Streaming de resultados: grave cada job em disco assim que ele termina, sem acumular tudo em memória.
  • Leitura paginada da origem: se a base vem de um banco, leia por cursor e monte os blocos sob demanda.

O CERT.br recomenda que sistemas que processam dados pessoais em lote implementem registro de auditoria por lote, garantindo rastreabilidade em caso de incidentes.


Perguntas frequentes

Como calcular quantas consultas em lote cabem no plano gratuito da CPFHub.io?

O plano Grátis oferece 50 créditos mensais, e cada CPF encontrado consome 1. Como o envio confere o saldo antes, um lote com mais CPFs válidos do que o saldo é recusado com HTTP 403 ("Créditos insuficientes para o lote: N necessários."). No Grátis não há excedente. Nos planos pagos com excedente ativo, o valor por crédito extra depende da faixa e está na página de preços.

A API de lote tem parâmetros de paginação ou filtro?

Não. POST /cpf/bulk recebe só a lista de CPFs em JSON ({"cpfs": [...]}, até 10.000) e GET /cpf/bulk/{jobId} devolve o status e os resultados do job. Paginação e filtros ficam do lado do cliente: dividir a base em vários jobs e limpar a lista antes de enviar.

Qual tamanho de bloco é mais indicado?

O máximo por envio é 10.000 CPFs. Em planos sem excedente, use blocos que caibam no saldo disponível, porque o envio inteiro é recusado se o saldo não cobrir todos os CPFs válidos. Blocos menores também diminuem o que você precisa reprocessar se algo falhar no seu lado.

É possível aplicar filtros antes de consumir a API para economizar consultas?

Sim. Filtros sintáticos (CPF com 11 dígitos, não sequência de dígitos iguais) e de deduplicação devem rodar localmente antes do envio. CPF inválido e CPF não encontrado não consomem crédito, mas a deduplicação entre blocos diferentes evita cobrar o mesmo CPF duas vezes.

Como retomar um processamento em lote interrompido sem reprocessar CPFs já consultados?

Salve o índice e o jobId de cada bloco concluído em um arquivo de checkpoint. Ao retomar, pule os blocos já concluídos. Se a interrupção aconteceu logo depois de um envio, consulte GET /cpf/bulk/{jobId} antes de reenviar: o POST não é idempotente e repetir pode criar um segundo lote.


Conclusão

Com a API de lote, a paginação deixa de ser uma requisição por CPF e vira uma questão de dividir a base em jobs de até 10.000, filtrar antes de enviar e guardar um checkpoint por job. O servidor cuida do processamento; o seu código cuida da ordem e da retomada.

Conheça o CPF em Lote da CPFHub.io e crie sua conta em cpfhub.io: 50 créditos mensais gratuitos, sem cartão de crédito, para testar o seu primeiro lote.

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