Consulta em Lote
Sua base inteira,
conferida de uma vez.
Envie até 10.000 CPFs em um único lote e acompanhe o processamento. Só os CPFs encontrados consomem crédito.
50 créditos grátis por mês, sem cartão de crédito.
O que você recebe
Dez mil consultas. Uma requisição.
O trabalho de orquestrar fila, paralelismo e retentativa fica do nosso lado.
Até 10.000 CPFs por lote
Você envia a lista inteira em uma requisição e recebe o jobId na hora, sem disparar dez mil chamadas nem sobrecarregar o seu servidor.
Resultado parcial durante o processamento
O lote não é uma caixa preta. A cada consulta ao status, você vê quantos CPFs foram processados, quantos foram encontrados e os registros já prontos.
Os mesmos campos da Consulta Simples
Cada CPF encontrado volta com nome, gênero e data de nascimento, no mesmo formato da consulta individual. CPF não encontrado volta com os campos em null.
namenameUppergenderbirthDatedaymonthyearSem código, se você preferir
O painel aceita arquivos CSV e TXT, identifica sozinho o separador e a coluna de CPF e exporta o resultado. Você também pode colar a lista em um campo de texto.
Como funciona
Envie a lista. Acompanhe o lote.
O processamento é assíncrono: a sua requisição não fica esperando dez mil consultas terminarem.
- 01
Envie a lista
Um POST com o array de CPFs. A resposta chega na hora com o jobId, e o processamento continua em segundo plano.
- 02
Acompanhe o lote
Consulte o jobId quando quiser. Cada consulta traz o progresso e os registros já concluídos, até o status mudar para done.
- 03
Use o resultado
Um item por CPF, com os mesmos campos da Consulta Simples. No painel, você exporta o arquivo pronto.
O lote usa a Consulta Simples. A Consulta em Tempo Real não roda em lote. Para volume nela, fale com o nosso time.
Integre em qualquer linguagem
Dois passos: você envia a lista e depois consulta o lote. Nada além de HTTP.
# Passo 1: envie a lista de CPFs
curl -X POST "https://api.cpfhub.io/cpf/bulk" \
-H "x-api-key: SUA_API_KEY" \
-H "content-type: application/json" \
-d '{"cpfs": ["12345678909", "11144477735", "52998224725"]}'
# → 202 Accepted { "jobId": "4a1ef25e-052c-4464-..." }
# Passo 2: aguarde o status "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
-H "x-api-key: SUA_API_KEY"{
"success": true,
"data": {
"id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
"status": "done",
"total_records": 3,
"processed": 3,
"found": 2,
"not_found": 1,
"skipped": 0,
"error": null,
"cpfs": [
{
"cpf": "12345678909",
"found": true,
"name": "Joao de Exemplo",
"nameUpper": "JOAO DE EXEMPLO",
"gender": "M",
"birthDate": "15/06/1985",
"day": 15,
"month": 6,
"year": 1985
},
{
"cpf": "52998224725",
"found": false,
"name": null,
"nameUpper": null,
"gender": null,
"birthDate": null,
"day": null,
"month": null,
"year": null
}
]
}
}50 créditos grátis por mês, sem cartão.
Acompanhamento
Você sabe onde o lote está.
Três status possíveis e cinco contadores. Você sabe se o lote está rodando, se terminou ou se parou.
processing
O lote está rodando. Consultar o status devolve o progresso e os registros já prontos.
done
O lote terminou. A resposta traz o resultado completo, item por item.
failed
O lote parou. Um lote sem progresso por mais de 10 minutos é marcado automaticamente, em vez de ficar pendente para sempre.
Contadores do lote
total_recordsQuantos CPFs válidos entraram no lote.
processedQuantos já foram consultados.
foundQuantos existem na base. É o que você paga.
not_foundQuantos não têm registro. Não cobram.
skippedQuantos ficaram de fora porque o saldo acabou durante o processamento.
Onde usar
Quando o problema é a base toda.
Situações em que consultar um CPF por vez levaria semanas e ninguém faria.
Limpar base legada
Cadastro antigo com nome digitado errado ou sem data de nascimento. Envie a base inteira e padronize tudo de uma vez.
Migração de sistema
Antes de levar o cadastro para o sistema novo, confirme quais CPFs existem de fato e o que fazer com o resto.
Prevenção de fraude na base ativa
Encontre CPFs que não existem na base e cadastros com nome ou data de nascimento diferentes do informado antes que virem prejuízo.
Auditoria periódica de cadastro
Rode o lote todo mês e acompanhe quantos registros da sua base deixaram de bater com o nome e a data de nascimento retornados.
Conciliação de carteira
Antes de cobrar, renovar ou repassar comissão, confirme que os titulares da carteira são quem o cadastro diz.
Due diligence em fusões e aquisições
Recebeu a carteira de clientes de outra empresa? O lote mostra em poucas horas quantos cadastros estão corretos.
Como cobra
Você paga pelos CPFs que existem.
Em uma base antiga, muitos registros não existem mais. Aqui, CPF não encontrado não consome crédito, então base desatualizada não vira fatura maior.
1 crédito
por CPF encontrado, como na Consulta Simples
R$ 0
por CPF não encontrado ou com formato ou dígito verificador incorreto
10.000
CPFs por lote, quantos lotes você precisar
Em planos sem excedente, o lote só é aceito se houver saldo para todos os CPFs válidos. Se o saldo acabar durante o processamento, os CPFs restantes voltam como skipped, sem consulta e sem cobrança.
Perguntas frequentes
Qual o limite por lote?
Até 10.000 CPFs por requisição em POST /cpf/bulk. Acima disso, a API recusa com 400. Para volumes maiores, divida em vários lotes ou fale com o nosso time sobre o plano Corporativo.
O processamento é síncrono ou assíncrono?
Assíncrono. O POST cria o lote e devolve um jobId. Consulte GET /cpf/bulk/{jobId} até o status mudar para done ou failed. O painel também acompanha o progresso.
CPF não encontrado consome crédito?
Não. No lote, só itens com found: true consomem crédito. CPF não encontrado ou com formato ou dígito verificador incorreto não é cobrado. A mesma regra vale na consulta individual.
Posso usar o lote no plano Grátis?
Sim. O plano Grátis acessa os mesmos endpoints, com 50 créditos por mês. Em planos sem excedente, como o Grátis, o lote só é aceito se houver saldo para todos os CPFs válidos. Sem saldo suficiente, a API responde 403 e nada é cobrado. Veja /precos.
Quais formatos o painel aceita?
CSV e TXT. O separador (ponto e vírgula ou vírgula), o cabeçalho e a coluna de CPF são identificados automaticamente. Você também pode colar a lista em um campo de texto. XLSX não é aceito: exporte como CSV antes de enviar.
O que significa cada status do lote?
processing: o lote está rodando, e a consulta já devolve o progresso e os registros prontos. done: terminou, com o resultado completo. failed: o lote parou. Um lote sem progresso por mais de 10 minutos é marcado como failed automaticamente.
O que acontece se o saldo acabar durante o lote?
Os CPFs restantes voltam como skipped. Não são consultados nem cobrados. Você recarrega o saldo e envia um novo lote só com os CPFs que ficaram de fora.
Consigo baixar o resultado em CSV?
Pelo painel, sim. A API devolve JSON: um item por CPF, com os mesmos campos da Consulta Simples e valores null quando o CPF não foi encontrado.
A Consulta em Tempo Real funciona em lote?
Não. O lote atende só a Consulta Simples. A Consulta em Tempo Real é individual, uma chamada por CPF em POST /cpf/realtime. Para volume nela, fale com o nosso time pelo WhatsApp ou em contato@cpfhub.io.
Confira a base
inteira de uma vez.
- 50 créditos grátis por mês
- Sem cartão de crédito
- Atendimento 24h no WhatsApp