Consultas
Padrón de RUC, tipo de cambio y DNI. Informativas, nunca una validación.
Tres rutas de lectura que resuelven datos que necesitas al construir un comprobante, no al emitirlo.
| Ruta | Resuelve | Scope |
|---|---|---|
GET /api/v2/consultations/ruc/{ruc} | Qué dice el padrón sobre un RUC | consultations:read |
GET /api/v2/consultations/exchange-rate/{date} | El tipo de cambio publicado de esa fecha | consultations:read |
GET /api/v2/consultations/dni/{dni} | El nombre de una persona | consultations:dni |
Ninguna toma Idempotency-Key: no crean nada.
Ninguna de las tres valida nada, y ninguna afecta a la emisión. Ningún create, ningún
trigger y ninguna decisión de envío lee estos catálogos. Un RUC que esta ruta reporte como no
registrado se puede facturar igual, y hacerlo no es un error ni un aviso.
consultations:read es disjunto de todos los scopes documents:*. Preguntar de quién es un RUC
no debería exigir una credencial capaz de emitir un comprobante. Y el DNI tiene su propio scope,
separado del resto: es un dato personal y merece concederse aparte.
El padrón de RUC
Devuelve la razón social, el estado del contribuyente y la condición de domicilio — el valor
literal de SUNAT y además nuestra clasificación. El literal es el autoritativo; la clasificación es
nuestra y puede ser UNKNOWN, de forma que un valor que SUNAT añada mañana se ve en lugar de quedar
mapeado en silencio a otra cosa.
Es una copia periódica, no un registro en vivo, así que siempre va por detrás: una empresa
registrada después del corte no está en ella y sin embargo puede recibir comprobantes
perfectamente. registry.publishedOn te dice de qué instantánea salió la respuesta — es la fecha de
publicación de SUNAT, no la de nuestra ingesta.
Los tres resultados, y solo dos hablan del contribuyente
| Respuesta | Qué significa |
|---|---|
200 con registered: true | El RUC está en la instantánea |
200 con registered: false | Hay instantánea cargada y ese RUC no está en ella |
503 TAXPAYER_REGISTRY_UNAVAILABLE | No hay ninguna instantánea cargada |
Ramifica primero por el código de estado y solo después por registered. Un cliente que
pliegue el 503 dentro de registered: false está reportando una caída nuestra como un hecho
sobre el cliente de alguien.
Un RUC que no tenga exactamente once dígitos responde 422 INVALID_RUC, nunca «no registrado». Una
entrada mal formada es un error tuyo, no una afirmación sobre un contribuyente.
Tipo de cambio
Resuelve el tipo de cambio publicado que aplica en una fecha dada. Útil para un comprobante en moneda extranjera, donde el tipo forma parte del documento.
Es un dato con fecha: pides el de un día concreto, no «el de hoy».
DNI
Resuelve un DNI a un nombre. Mismas advertencias que el padrón: informativa, nunca una validación, y que no resuelva no impide emitir una boleta.
Va con su propio scope, consultations:dni, precisamente para que puedas dar una credencial que
consulta RUC y tipo de cambio sin poder consultar personas.
Y una que no está aquí
La plataforma consulta el servicio de validez de CPE de SUNAT internamente, pero no hay ruta pública para ello. Si la necesitas, dínoslo: es la clase de cosa que se publica cuando alguien tiene un uso concreto, no antes.