Consulta de registro

Visión general

Consulte datos registrales oficiales brasileños por número de identificación del contribuyente:

Ambos endpoints son GET: el cuerpo firmado es la cadena vacía y todas las variables de ruta (CNPJ / CPF / fecha de nacimiento) forman parte de la ruta firmada, vea Autenticación. Las respuestas son objetos simples (sin sobre de la plataforma); los errores de negocio son un objeto simple {code, message}.

Por qué el CPF requiere fecha de nacimiento

La fuente upstream valida CPF y fecha de nacimiento como un par (semántica de la Receita Federal); el CPF por sí solo no devuelve nada. Un par que no coincide y un CPF inexistente devuelven el mismo código de error: deliberadamente no se distinguen, de lo contrario el endpoint se convertiría en una herramienta para averiguar la fecha de nacimiento de otras personas.

Requisitos previos (una sola vez)

1. Credencial de la aplicación: solicite una aplicación y reciba el app_secret. Se muestra una sola vez; guárdelo de forma segura.
2. Suscripción a la API: la plataforma concede a su aplicación acceso a los endpoints que necesite (la clave de scope es la ruta del endpoint).

Endpoints

Modelo de errores

Dos formas de error

Los errores de negocio, de solicitud y de la fuente upstream (HTTP 400 / 422 / 428 / 451 / 503) se devuelven como objeto simple:

{ "code": 10016003, "message": "CPF not found" }

Los errores de la capa de autenticación (HTTP 401 / 403 / 429) los produce el gateway de la plataforma antes de que la solicitud llegue a la API, y usan el sobre de la plataforma:

{ "success": false, "errorType": 1, "code": 10009005, "message": "API not subscribed, please subscribe before calling" }

Nota: su gestor de errores debe aceptar ambas formas. Una regla robusta: interprete el cuerpo como JSON, lea code de cualquiera de las formas y trate success=false o HTTP >= 400 como fallo.

Códigos de error de negocio

Los errores de formato y de dígito verificador se rechazan localmente en la plataforma y nunca llegan a la fuente upstream: no consumen cuota ni se facturan.

Convención de responsabilidad: 10016000 a 10016003 y 10016010 a 10016012 son problemas del llamador; 10016004 a 10016006 son bloqueos legales de terceros; 10016020 es una indisponibilidad de tercero; HTTP 500 + 10001000 es un fallo de la plataforma.

Facturación: 10016003 (no encontrado / fecha de nacimiento que no coincide), 10016004 (menor de 16) y 10016005 (16 a 17 años) se facturan por llamada; 10016006 (edad no verificable), 10016020 (upstream no disponible) y los errores de formato / dígito verificador rechazados localmente no se facturan. Las franjas de edad se detallan en la página Consulta de CPF.

Errores de autenticación y autorización

Guía de reintentos: 401 y 403 son errores de configuración; reintentar sin corregir es inútil y puede disparar el límite de tasa. 429 y 503 (10016020) son reintentables con backoff. 422 / 428 / 451 son bloqueos legales; reintentar es inútil. Para 500, contacte con la plataforma con el timestamp y la ruta de la solicitud fallida.

Referencia rápida de estados HTTP

Protección de datos

El CPF es un dato personal de una persona física y se rige por la LGPD de Brasil (Ley 13.709/2018):

• La plataforma no persiste los resultados de las consultas de CPF; cada consulta va a la fuente en tiempo real.
• Los valores completos de CPF nunca entran en los registros de la aplicación; se enmascaran.
• Las variables de ruta en el registro de llamadas pasan por HMAC antes de almacenarse; no se conserva texto en claro.
• La fuente upstream retiene legalmente los datos de menores de edad; la plataforma transmite los estados 451 / 422 / 428 sin cambios y no almacena nada. 451 / 422 se facturan por llamada, 428 no; vea Menores de edad y verificación de edad en la página Consulta de CPF.

Se espera que los llamadores observen el mismo principio de necesidad mínima: consulte solo cuando exista una base legal de negocio (como la emisión de facturas) y no conserve datos personales más allá de lo que el negocio requiera.

Localización de las respuestas

El campo message sigue el idioma de la solicitud: la cabecera Language (en / pt / es / zh) tiene prioridad, después Accept-Language (admite pt-BR y valores q). Sin cabecera de idioma, las respuestas usan portugués (pt) por defecto.

Para las decisiones programáticas use siempre el code numérico y valores enumerados como situacao.codigo; nunca compare textos descriptivos. El message de las franjas de bloqueo de la LGPD es el texto legal en portugués y no se traduce.

Lista de comprobación de integración

1. Obtenga el app_secret y confirme que ambos endpoints están suscritos.
2. Llame con un CNPJ real: HTTP 200, ni devuelve la entrada, situacaoCadastral.codigo es 2.
3. Llame con un CPF real + fecha de nacimiento: HTTP 200, nascimento devuelve la entrada.
4. Caso negativo: CPF correcto con fecha de nacimiento incorrecta devuelve 400 + 10016003 (mismo código que no encontrado).
5. Caso negativo: CNPJ / CPF con dígitos verificadores incorrectos devuelve 400 + 10016011 / 10016001 (rechazado localmente, no facturado).
6. Caso negativo: fecha de nacimiento como 1997-01-09 o 31021997 devuelve 400 + 10016002.
7. Rutas de fallo: llame con un sign incorrecto (401 + 10009003); llame a un endpoint no suscrito (403 + 10009005).
8. Compatibilidad del parser: asegúrese de que su cliente trata 422 / 428 / 451 / 503 como fallos y lee el cuerpo simple {code, message} (estos estados no se pueden provocar con datos de prueba; solo aparecen en producción con CPF reales de menores).

Solución de problemas

1. Una solicitud GET no concatenó el cuerpo como la cadena vacía "" (se usó un objeto vacío o un texto de relleno);
2. path sin el prefijo /openapi, o incluyendo la query string;
3. El segmento de la fecha de nacimiento quedó fuera de la firma del CPF; ambas variables de ruta deben firmarse;
4. sign enviado en mayúsculas (debe ser hex en minúsculas);
5. El timestamp usado en la concatenación difiere del de la cabecera (regenerado entre ambos);
6. Un CNPJ con formato cuya / dividió la ruta.

Recalcule primero los valores fijos del ejemplo de firma en Autenticación; cuando su implementación local coincida, pase a inspeccionar los parámetros de la solicitud real.