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.

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.