Consulta de registro

Consulta de CPF

Datos registrales oficiales de una persona física a partir del CPF y la fecha de nacimiento.

GET/openapi/v3/consultas/cpf/{cpf}/{nascimento}

Requiere las cabeceras de firma token, timestamp y sign, vea Autenticación.

Devuelve los datos registrales de un CPF de 11 dígitos más la fecha de nacimiento: nombre, situación registral y fecha de nacimiento. La fuente upstream valida CPF y fecha de nacimiento como un par; un par que no coincide y un CPF inexistente devuelven el mismo código 10016003, deliberadamente indistinguibles (vea Consulta de registro).

Solicitud GET: el cuerpo firmado es la cadena vacía y las dos variables de ruta forman parte de la ruta firmada. La respuesta es un objeto simple, sin sobre de la plataforma.

Parámetros

Parámetros de ruta

cpfstringobligatorio
11 dígitos, solo dígitos; no se aceptan caracteres de formato.
Ejemplo: 40710536828
nascimentostringobligatorio
Fecha de nacimiento, DDMMYYYY, 8 dígitos (p. ej. 09011997 = 9 de enero de 1997).
Ejemplo: 09011997

Respuestas

200

Consulta realizada; titular mayor de edad. Datos registrales de la persona física.

nistring
CPF, 11 dígitos.
nomestring
Nombre completo de la persona física.
situacaoobject
Situación registral.
nascimentostring
Fecha de nacimiento, devuelta en el formato original DDMMYYYY.

Errores

Código	HTTP
10016000	400	Formato de CPF inválido (se requieren 11 dígitos). Compruebe caracteres de formato indebidos o longitud incorrecta.
10016001	400	Dígitos verificadores del CPF inválidos. Valide localmente con el algoritmo mod-11 para evitar llamadas inútiles.
10016002	400	Fecha de nacimiento inválida (se requiere un DDMMYYYY válido). Observe el orden día-mes-año y que la fecha debe existir.
10016003	400	CPF no encontrado: el CPF no existe o el CPF y la fecha de nacimiento no coinciden (deliberadamente indistinguibles). Se factura por llamada.
10016005	422	`LGPD: menor de idade`: el titular tiene entre 16 y 17 años. Datos legalmente retenidos por la fuente upstream, sin campos personales; no reintente. Se factura por llamada.
10016004	451	`LGPD: menor de 16 anos (Lei Felca)`: el titular es menor de 16 años. Datos legalmente retenidos, sin campos personales; no reintente. Se factura por llamada.
10016006	428	`LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao`: no se puede verificar la edad. La plataforma ya volvió a verificar una vez con la fecha de nacimiento indicada; no reintente. No se factura.
10016020	503	Fuente de datos upstream temporalmente no disponible. Reintente con backoff exponencial (empiece en 1 s, duplique hasta 30 s, añada jitter); si persiste, contacte con la plataforma. No se factura.

Valores de situacao.codigo

Código	Descripción	Significado
`0`	REGULAR	Regular
`2`	SUSPENSA	Suspendida
`3`	TITULAR FALECIDO	Titular fallecido
`4`	PENDENTE DE REGULARIZACAO	Pendiente de regularización
`5`	CANCELADA POR MULTIPLICIDADE	Cancelada (registro duplicado)
`8`	NULA	Nula
`9`	CANCELADA DE OFICIO	Cancelada de oficio

Nota de negocio: cuando codigo no es 0, corresponde al llamador decidir si el flujo de negocio puede continuar. Emitir una factura a un titular fallecido (3), por ejemplo, normalmente justifica un bloqueo; este endpoint informa la situación fielmente y no toma esa decisión por usted.

Menores de edad y verificación de edad (LGPD / Lei Felca)

La fuente upstream responde a las consultas de CPF según la franja de edad del titular. La plataforma transmite el código de estado upstream sin cambios:

Resultado de la verificación de edad	HTTP	code	Respuesta
Adulto (18 años o más)	200	(ninguno)	Nombre, situación registral y fecha de nacimiento, como de costumbre
16 a 17 años	422	10016005	`{ "code": 10016005, "message": "LGPD: menor de idade" }`, sin ningún campo personal
Menor de 16 años	451	10016004	`{ "code": 10016004, "message": "LGPD: menor de 16 anos (Lei Felca)" }`, sin ningún campo personal
Edad no verificable	428	10016006	`{ "code": 10016006, "message": "LGPD: idade nao verificavel - informe a data de nascimento para completar a verificacao" }`, sin ningún campo personal

El message de las tres franjas de bloqueo es el texto legal fijado por la fuente upstream (portugués) y no se traduce con la cabecera Language; ramifique por code en el código.
428 significa que la base upstream no tiene fecha de nacimiento del titular y no puede calcular la edad. La plataforma ya volvió a verificar una vez con la fecha de nacimiento que usted indicó (dentro de la misma llamada; no necesita reintentar): si la verificación tiene éxito, recibe el resultado normal según la tabla; un 428 persistente significa que la fuente oficial tampoco pudo verificar, y reintentar es inútil.
Facturación: 422 (16 a 17 años), 451 (menor de 16) y no encontrado / fecha de nacimiento que no coincide (400 + 10016003) se facturan por llamada; la fuente upstream también cobra por estas conclusiones. 428 (edad no verificable) e indisponibilidad upstream (503) no se facturan. La plataforma no almacena nada para las franjas de bloqueo. Ante 422 / 451 no consulte el mismo CPF repetidamente: la edad no cambia con los reintentos y cada reintento se factura.
Los errores de formato y de dígito verificador se rechazan localmente, nunca llegan a la fuente upstream y no se facturan.