Consulta por Lote
Toda tu base de datos,
verificada de una vez.
Envía hasta 10.000 CPF (el número de identificación fiscal de personas físicas en Brasil) en un solo job y sigue el procesamiento. Pagas solo por los que se encuentren, y nada por los que no existan.
La misma clave y el mismo crédito que la Consulta Simple. Desde el dashboard o por la API.
Lo que recibes
Diez mil consultas. Una solicitud.
El trabajo de orquestar la cola, el paralelismo y los reintentos queda de nuestro lado.
Un job, hasta 10.000 CPF
Envías la lista completa en una sola solicitud y recibes un jobId al instante. Sin disparar diez mil llamadas y esperar que tu servidor aguante.
Resultado parcial mientras procesa
El job no es una caja negra. En cada consulta de estado ves cuántos se procesaron, cuántos se encontraron y los registros listos hasta ese momento.
Cobro solo por lo que se encuentra
Cada CPF encontrado consume 1 crédito. Un CPF no encontrado o con formato o dígito verificador incorrecto no consume nada. Una base desordenada no se convierte en una factura inflada.
Sin código, si lo prefieres
El dashboard acepta CSV o TXT, detecta solo el separador y la columna de CPF, y exporta el resultado. También puedes pegar la lista directamente en un campo de texto.
Seguimiento
Sabes en qué punto está el job.
Tres estados posibles y cinco contadores. Sin adivinar si se trabó o si sigue corriendo.
processing
El job está corriendo. Consultar el estado devuelve el progreso y los registros ya listos.
done
Terminó. La respuesta trae el resultado completo, ítem por ítem.
failed
Algo se trabó. Un job detenido por más de 10 minutos se marca automáticamente, en vez de quedar colgado para siempre.
Contadores del job
total_records
Cuántos CPF válidos entraron al job.
processed
Cuántos ya se consultaron.
found
Cuántos existen en la base de datos. Es lo que pagas.
not_found
Cuántos no tienen registro. No se cobran.
skipped
Cuántos quedaron fuera por falta de crédito.
Cómo se cobra
Pagas por los CPF
que existen.
En una base antigua, buena parte de los registros ya no existirá. En muchos servicios, cada uno de esos intentos se cobra igual. Aquí, el intento sin resultado no entra en la cuenta.
1 crédito
por CPF encontrado, igual que la Consulta Simple
R$ 0
por CPF no encontrado o con formato o dígito verificador incorrecto (montos en reales brasileños, BRL)
10.000
CPF por job, tantos jobs como necesites
Si el crédito se acaba a mitad del lote, los CPF restantes vuelven como skipped. No se consultan ni se cobran, y puedes reprocesarlos cuando quieras.
Ver planesDónde usarlo
Cuando el problema es toda la base.
Situaciones en las que consultar un CPF a la vez tomaría semanas y nadie lo haría.
Limpiar una base heredada
Un registro antiguo con nombres mal escritos y fechas de nacimiento faltantes. Pasa toda la base y normalízala de una vez.
Migración de sistema
Antes de llevar el registro al sistema nuevo, confirma qué CPF existen de verdad y qué hacer con el resto.
Enriquecer antes de una campaña
Con el nombre correcto y la fecha de nacimiento a mano, la segmentación y la personalización funcionan de verdad.
Auditoría periódica de registros
Corre el lote cada mes y revisa cuántos registros de tu base dejaron de coincidir con el dato oficial.
Conciliación de cartera
Antes de cobrar, renovar o pagar comisiones, confirma que los titulares de la cartera son quienes dice el registro.
Due diligence de adquisición
Compraste una base junto con la empresa. El lote te dice en horas qué porcentaje es aprovechable.
Cómo funciona
Envías y sigues el avance. Nada más.
El job es asíncrono, así que tu solicitud no queda colgada esperando a que terminen diez mil consultas.
01
Envía la lista
Un POST con el array de CPF. La respuesta vuelve al instante con el jobId, sin retener tu solicitud mientras se procesa.
02
Sigue el job
Consulta el jobId cuando quieras. Cada consulta trae el progreso y los registros ya concluidos, hasta que el estado pase a done.
03
Usa el resultado
Un ítem por CPF, con los mismos campos de la Consulta Simple. En el dashboard puedes exportar el archivo listo.
El lote atiende a la Consulta Simple. Para volumen en la Consulta en Tiempo Real, que no corre por lote, habla con nosotros.
Intégrala en cualquier lenguaje
Dos pasos: envías la lista y luego consultas el job. Nada más allá de HTTP.
# Paso 1: POST con un arreglo de CPFs en JSON
curl -X POST "https://api.cpfhub.io/cpf/bulk" \
-H "x-api-key: TU_API_KEY" \
-H "content-type: application/json" \
-d '{"cpfs": ["12345678909", "11144477735", "52998224725"]}'
# → 202 Accepted { "jobId": "4a1ef25e-052c-4464-..." }
# Paso 2: polling hasta que el estado sea "done"
curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
-H "x-api-key: TU_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
}
]
}
}FAQ
Preguntas frecuentes
¿Cuál es el límite por job?
Hasta 10.000 CPF por solicitud en POST /cpf/bulk. Por encima de eso la API rechaza con 400. Para volúmenes mayores, divide en varios jobs o habla con nosotros sobre Enterprise.
¿Es síncrono o asíncrono?
Asíncrono. El POST crea el job y devuelve un jobId. Haz polling en GET /cpf/bulk/{jobId} hasta que el estado sea done o failed. El dashboard también muestra el progreso.
¿Un 404 consume crédito?
No. En el lote, solo los ítems con found: true consumen crédito. Un CPF no encontrado o con dígito verificador incorrecto no se cobra. La misma regla vale para el GET individual (solo HTTP 200).
¿Se puede usar el lote en el plan Gratis?
Sí. El plan Gratis accede a los mismos endpoints, con 50 créditos/mes. Con 0 créditos, los ítems del lote quedan como skipped (sin excedente en el plan Gratis). Pro y Enterprise cubren volúmenes mayores. Consulta /es/precios.
¿Qué formatos acepta el dashboard?
CSV y TXT. El separador (punto y coma o coma), el encabezado y la columna de CPF se detectan automáticamente. También puedes pegar la lista directamente en un campo de texto. No se acepta XLSX: expórtalo como CSV antes de enviarlo.
¿Qué significa cada estado del job?
processing: sigue en ejecución, y al consultar el job ya devuelve el progreso y los registros listos. done: terminó, con el resultado completo. failed: algo se trabó. Un job detenido por más de 10 minutos se marca como failed automáticamente, en lugar de quedar colgado.
¿Qué pasa si se acaban los créditos a la mitad del lote?
Los CPF restantes vuelven como skipped. No se consultan ni se cobran. Recargas el plan y reprocesas solo lo que quedó afuera.
¿Puedo descargar el resultado en CSV?
Desde el dashboard, sí. La API devuelve JSON: un ítem por CPF, con los mismos campos de la Consulta Simple y valores nulos cuando el CPF no se encontró.
¿La Consulta en Tiempo Real funciona en lote?
No. El lote atiende solo la Consulta Simple. La Consulta en Tiempo Real es individual, una llamada por CPF en POST /cpf/realtime. Para volumen en ella, escríbenos por WhatsApp o a contato@cpfhub.io.
¿Todavía tienes dudas?
ContáctanosVerifica toda la base
de una vez.
Hasta 10.000 CPF por job, por la API o subiendo un archivo en el dashboard. Pagas solo por los que se encuentren.
Acceso inmediato a tu clave de API y a la documentación.