Introducción

La API de CPFHub.io permite consultar los datos de registro vinculados a un CPF (el número de identificación fiscal de personas físicas en Brasil): nombre, fecha de nacimiento y género, en una sola solicitud HTTP autenticada. También consulta la situación de registro directo en la Receita Federal (la autoridad tributaria federal de Brasil) y procesa listas de CPF por lote.

Qué puedes hacer

Consultar el nombre completo, la fecha de nacimiento y el género a partir del número de CPF
Verificar si un CPF tiene dígitos verificadores válidos
Calcular la edad del titular a partir de year, month y day
Integrar la verificación de mayoría de edad en tu flujo de registro o de transacción
Consultar la situación de registro y el año de fallecimiento de un CPF en la Receita Federal en tiempo real, con código de control y comprobante (Consulta en Tiempo Real)

Endpoints

Método	Endpoint	Descripción	Costo
`GET`	`/cpf/{cpf}`	Consulta Simple: nombre, género y fecha de nacimiento desde la base de datos de CPFHub.io	1 crédito por CPF encontrado
`POST`	`/cpf/realtime`	Consulta en Tiempo Real en la Receita Federal: situación de registro, año de fallecimiento (`deathYear`, un entero o `null`), código de control y comprobante	1,5 créditos por consulta exitosa
`POST`	`/cpf/bulk`	Consulta por lote asíncrona, hasta 10.000 CPF	1 crédito por CPF encontrado
`GET`	`/cpf/bulk/{jobId}`	Estado y resultados de un lote	Gratis
`GET`	`/quota`	Saldo de créditos, uso y plan	Gratis

Los costos anteriores son los valores por defecto. Consulta el costo específico de tu cuenta en el dashboard.

URL base

Todas las solicitudes deben usar HTTPS:

https://api.cpfhub.io

Las solicitudes por http:// reciben una redirección 301 a HTTPS. Muchos clientes HTTP convierten un POST en GET al seguir esa redirección, así que usa siempre https:// directamente.

Formato de las respuestas

Las respuestas de la API usan Content-Type: application/json. La excepción es el comprobante (validationHtmlUrl), que se sirve como text/html.

Éxito (2xx):

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

Error (4xx / 5xx):

JSON

{
  "success": false,
  "data": null,
  "error": {
    "message": "CPF não encontrado na base de dados"
  }
}

La API devuelve los mensajes de error solo en portugués. Este significa "CPF no encontrado en la base de datos". Usa el estado HTTP para decidir el flujo. La mayoría de los errores traen error.message. Los errores de autenticación y de cuenta (401 y 403 de cuenta bloqueada), 500 "Erro ao validar assinatura" ("error al validar la suscripción") y 503 "usage_unavailable" traen error como string:

JSON

{
  "success": false,
  "error": "API Key não fornecida"
}

Aquí el mensaje significa "API key no proporcionada". Para leer el mensaje en los dos formatos: typeof body.error === 'string' ? body.error : body.error?.message. La lista completa está en Códigos de Error.

Autenticación

Todas las solicitudes necesitan el header x-api-key con tu clave de API:

bash

curl "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: TU_API_KEY"

Obtén tu clave gratis en app.cpfhub.io/api-keys. La clave es un string opaco, así que no dependas de su prefijo ni de su formato.

Próximos pasos

Autenticación: claves de API y seguridad
Consulta Simple: campos, parámetros y ejemplos
Consulta en Tiempo Real: situación de registro, año de fallecimiento y comprobante de la Receita Federal
Consulta por Lote: hasta 10.000 CPF por solicitud
Saldo de Créditos: saldo, uso y plan de tu cuenta
Límites de Uso: créditos por plan y límite por minuto
Códigos de Error: lista completa de errores y cuándo reintentar

Actualizado el 3 de octubre de 2026