Consulta en Tiempo Real

Envía el CPF (el número de identificación fiscal de personas físicas en Brasil) y la fecha de nacimiento y recibe el nombre, la fecha de nacimiento, el año de fallecimiento, la situación de registro, el código de control y el comprobante, directo desde la Receita Federal (la autoridad tributaria federal de Brasil). Cuesta 1,5 créditos por consulta.

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Consulta en Tiempo Real y pégalo en tu asistente.

Abrir en Cursor

¿Usas Cursor, Lovable, v0 u otra IA? Copia el prompt de la Consulta en Tiempo Real y pégalo en tu asistente.

Abrir en Cursor

¿No es esta? Compara las consultas.

Endpoint

POSThttps://api.cpfhub.io/cpf/realtime

Parámetros

Dónde	Nombre	Obligatorio	Descripción
Header	`x-api-key`	Sí	Tu clave de API, la misma de la Consulta Simple. Consulta Autenticación.
Header	`Content-Type`	Sí	`application/json`
Body	`cpf`	Sí	CPF con o sin formato: `12345678909` o `123.456.789-09`
Body	`birthDate`	Sí	Fecha de nacimiento, 8 dígitos (día, mes, año): `DD/MM/AAAA` o `DDMMAAAA`. Los separadores se ignoran. Año entre 1900 y el actual.

Ejemplo

Los ejemplos leen la clave desde CPFHUB_API_KEY, usan un timeout de 60 s y manejan los errores según el estado HTTP.

curl --max-time 60 -X POST "https://api.cpfhub.io/cpf/realtime" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpf": "12345678909",
    "birthDate": "15/06/1990"
  }'

Respuesta

HTTP 200 OK

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "FULANO DE TAL",
    "birthDate": "15/06/1990",
    "deathYear": null,
    "situation": "REGULAR",
    "emissionDate": "02/10/2026",
    "emissionTime": "14:15:16",
    "controlCode": "ABCD.1234.EFGH.5678",
    "validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?cp=12345678909&cc=ABCD1234EFGH5678&de=02102026&he=141516&dv=09&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/12345678909/1790950516000"
  }
}

Campo	Tipo	Descripción
`data.cpf`	`string`	CPF consultado, 11 dígitos sin formato
`data.name`	`string`	Nombre tal como consta en la Receita Federal, en mayúsculas
`data.birthDate`	`string`	Fecha de nacimiento, `DD/MM/AAAA`
`data.deathYear`	`integer \| null`	Año de fallecimiento. Siempre presente: `null` cuando no hay fallecimiento registrado o cuando el valor recibido es inválido. Un valor válido tiene 4 dígitos, está entre 1900 y el año actual y no puede ser anterior al año de nacimiento.
`data.situation`	`string`	Situación de registro (tabla de abajo)
`data.emissionDate`	`string`	Fecha de emisión del comprobante, `DD/MM/AAAA`. Opcional.
`data.emissionTime`	`string`	Hora de emisión, `HH:MM:SS`. Opcional.
`data.controlCode`	`string`	Código de control del comprobante (`XXXX.XXXX.XXXX.XXXX`). Opcional.
`data.validationUrl`	`string`	Enlace de verificación en el sitio de la Receita Federal (destino del código QR). Opcional.
`data.validationHtmlUrl`	`string`	Comprobante guardado por CPFHub.io (HTML con código QR). Opcional.

Los campos opcionales pueden no venir: dependen de lo que devuelva la Receita Federal y de la generación del comprobante. deathYear no es opcional: el campo siempre viene, con un entero válido o null.

Situación de registro

Los valores de situation se devuelven en portugués, tal como los registra la Receita Federal.

`situation`	Significado
`REGULAR`	CPF en orden, sin pendientes
`PENDENTE DE REGULARIZAÇÃO`	Falta presentar una declaración o actualizar el registro (pendiente de regularización)
`SUSPENSA`	Registro incorrecto o incompleto (suspendida)
`CANCELADA`	Inscripción cerrada por decisión administrativa o judicial, o por multiplicidad (cancelada)
`NULA`	Inscripción anulada por fraude (nula)
`TITULAR FALECIDO`	Fallecimiento registrado en el padrón (titular fallecido)

Solo REGULAR indica un CPF sin pendientes. Todas las situaciones vienen con 200 y consumen crédito.

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.

Estado	Cuándo ocurre	Qué hacer
`400`	CPF sin 11 dígitos, o `birthDate` ausente o inválida	Corrige el body. No repitas.
`401`	Clave de API ausente, inválida o inactiva (`error` es una cadena)	Revisa el header `x-api-key`.
`403`	Créditos insuficientes sin excedente (`error.message`: `"Limite de créditos excedido"`, límite de créditos excedido) o cuenta inactiva/bloqueada (`error` es una cadena)	Recarga créditos o contacta a soporte. No repitas.
`422`	Dígito verificador incorrecto, o la Receita Federal rechazó la consulta (por ejemplo, fecha de nacimiento que no coincide)	Corrige el CPF o la fecha. No consume crédito. Maneja el caso por el estado, no por el texto (viene de la Receita).
`429`	Límite por minuto excedido (5/min por defecto)	Espera los segundos indicados en el header `Retry-After`. No consume crédito.
`500`	Error interno	Repórtalo si persiste.
`502`, `503`	Falla pasajera en la Receita Federal o en la reserva de créditos	Repite con esperas crecientes (2 s, 4 s, 8 s). No consume crédito.

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

Costo: 1,5 créditos por consulta con 200, en cualquier situación de registro. Algunos planes tienen un costo propio, así que consulta el de tu plan en el dashboard.
Tiempo de respuesta: cerca de 1 segundo (tiempo típico, no un SLA). Usa un timeout de al menos 60 s. Si tu flujo no puede esperar, haz la llamada de forma asíncrona.
Sin lote: la consulta se hace CPF por CPF.
No repitas después de un timeout local: el POST no es idempotente. La consulta pudo completarse y cobrarse. Revisa el saldo en GET /quota antes de intentarlo de nuevo.
Datos de ejemplo: el CPF 12345678909 y los datos anteriores son ficticios.

⚠

El enlace del comprobante es público

Cualquier persona con el enlace de validationHtmlUrl puede abrir el comprobante (nombre, CPF y situación). Trátalo como dato personal: guárdalo solo en el back end, no lo registres en logs y no lo expongas en el front end.

Actualizado el 4 de octubre de 2026