Consulta por Lote

Envía una lista de hasta 10.000 CPF (el número de identificación fiscal de personas físicas en Brasil) y recibe, para cada uno, el nombre, el género y la fecha de nacimiento, procesados en segundo plano. Cuesta 1 crédito por CPF encontrado.

¿No es esta? Compara las consultas. Si prefieres no escribir código, el dashboard acepta archivos CSV/TXT o CPF pegados y exporta el resultado en CSV.

Flujo en dos pasos:

1. POST /cpf/bulk envía la lista y responde de inmediato con un jobId.
2. GET /cpf/bulk/{jobId} devuelve el progreso y los resultados. Repite hasta que status sea "done" o "failed".

Endpoint

Parámetros

Qué pasa al enviar

Más de 10.000 CPF: divídelos en bloques y envía un POST por cada uno.

Ejemplo

Revisa el estado antes de leer data: en caso de error, la respuesta no trae jobId.

curl -X POST "https://api.cpfhub.io/cpf/bulk" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpfs": ["12345678909", "11144477735", "52998224725"]
  }'

Respuesta

HTTP 202 Accepted

{
  "success": true,
  "data": {
    "jobId": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "processing",
    "totalRecords": 3,
    "invalid": 0
  }
}

El envío responde en camelCase. El estado responde en snake_case.

Estado y resultados

Usa la misma clave de API del envío. No consume crédito, no cuenta en el límite por minuto y funciona con saldo en cero.

Polling:

• Empieza cada 5 s y aumenta hasta 30 s en lotes grandes. Cada llamada devuelve el array cpfs completo (hasta ~2 MB con 10.000 CPF).
• Define un plazo máximo en el cliente (por ejemplo, 30 min). El tiempo del lote depende de cuántos CPF envíes, y cada consulta queda en el mismo rango de la Consulta Simple (~150 ms).
• Ante un 5xx o un error de red, reintenta en el siguiente ciclo. Es seguro repetir el GET.

curl "https://api.cpfhub.io/cpf/bulk/4a1ef25e-052c-4464-9657-4148f53bb0fc" \
  -H "x-api-key: $CPFHUB_API_KEY"

HTTP 200 OK

{
  "success": true,
  "data": {
    "id": "4a1ef25e-052c-4464-9657-4148f53bb0fc",
    "status": "done",
    "file_name": null,
    "format": null,
    "total_records": 2,
    "processed": 2,
    "found": 1,
    "not_found": 1,
    "skipped": 0,
    "error": null,
    "created_at": "2026-10-02T14:15:16.000Z",
    "updated_at": "2026-10-02T14:15:18.000Z",
    "cpfs": [
      {
        "cpf": "12345678909",
        "found": true,
        "name": "Fulano de Tal",
        "nameUpper": "FULANO DE TAL",
        "gender": "M",
        "birthDate": "15/06/1990",
        "day": 15,
        "month": 6,
        "year": 1990
      },
      {
        "cpf": "52998224725",
        "found": false,
        "name": null,
        "nameUpper": null,
        "gender": null,
        "birthDate": null,
        "day": null,
        "month": null,
        "year": null
      }
    ]
  }
}

Mientras el estado es "processing", los contadores se actualizan cada 50 CPF y pueden ir por detrás de cpfs.

Errores

La API responde solo en portugués. Los mensajes de error se muestran tal como llegan, con la traducción entre paréntesis la primera vez.

Formato del error, reintentos y cómo probar sin gastar créditos: Códigos de Error. Límite por minuto y créditos: Límites de Uso.

Detalles

Estados del lote

Valores de error cuando el lote falla:

Con excedente, ningún CPF se omite: todos se consultan y el excedente se cobra.

Cruzar los resultados con tu lista

cpfs llega en orden de procesamiento y no incluye los skipped ni los no procesados. Normaliza tu lista a 11 dígitos y cruza por el campo cpf. Los que falten son los que debes reenviar (incluye los inválidos, que no cuestan nada).

const normalize = (cpf: string) => cpf.replace(/\D/g, '')

const results = new Map(job.cpfs.map((item) => [item.cpf, item]))

for (const original of myCpfs) {
  const result = results.get(normalize(original))
  console.log(original, result ? (result.found ? result.name : 'no encontrado') : 'sin resultado')
}

// CPF para reenviar en un nuevo lote (si el lote falló o tuvo skipped)
const missing = [...new Set(myCpfs.map(normalize))].filter((cpf) => !results.has(cpf))

Más

• Envío no idempotente: cada POST aceptado crea un lote nuevo y cobra los encontrados. Si la conexión se cae sin jobId, revisa el dashboard o GET /quota antes de reenviar. Si recibiste una respuesta de error, no se creó ningún lote.
• Crédito: solo se cobra found: true. Los inválidos, repetidos, no encontrados y skipped no se cobran.
• Exportación CSV: solo en el dashboard, con las columnas CPF, Nome (nombre), Nascimento (fecha de nacimiento) y Encontrado (encontrado), sin género.

Actualizado el 4 de octubre de 2026