NexoID

Referencia

URL base https://nexoid.victorllerena.com/id/v1 · versión 1.29.1 · OpenAPI · versión en Markdown

GET /id/v1/calendario/feriados/{anio}

Feriados del Perú de un año

Los 16 feriados nacionales del año —Jueves y Viernes Santo incluidos— con su nombre y su norma (DL 713 y sus leyes). Con sector=publico, también los días no laborables decretados para el sector público. Solo nacionales: los regionales no están. Un año fuera de meta.cubre es 404 anio_no_disponible, nunca una lista vacía. **Gratis y sin scope**, como el ubigeo: un catálogo, no una consulta de documentos. No descuenta cuota ni se audita, y responde también al token público del sandbox, con datos reales.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
anio path sí string
sector query no string `privado` (por defecto): fines de semana y feriados. `publico`: además, los días no laborables que decreta el Ejecutivo para el sector público, cada uno con su decreto supremo.
EstadoQué significa
200Los días inhábiles del año que no son fin de semana, por fecha.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El año está fuera del rango que cubre el calendario (motivo: anio_no_disponible).
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/calendario/plazo

En qué fecha vence un plazo de N días hábiles

Cuenta desde el día siguiente a desde, como los plazos administrativos, y se salta los fines de semana y los feriados —y los no laborables, con sector=publico—. Devuelve también los días que se saltó, con su motivo. **Gratis y sin scope**, como el ubigeo: un catálogo, no una consulta de documentos. No descuenta cuota ni se audita, y responde también al token público del sandbox, con datos reales.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
desde query sí string El día desde el que se cuenta, `AAAA-MM-DD`. No cuenta: el plazo empieza al siguiente.
dias query sí integer Cuántos días hábiles.
sector query no string `privado` (por defecto): fines de semana y feriados. `publico`: además, los días no laborables que decreta el Ejecutivo para el sector público, cada uno con su decreto supremo.
EstadoQué significa
200La fecha de vencimiento y los días inhábiles que hubo en medio.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El plazo sale del rango que cubre el calendario (motivo: anio_no_disponible).
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/calendario/{fecha}

Si una fecha es día hábil

Si es hábil, y si no, por qué —fin de semana, feriado o no laborable, con su norma—, además del día hábil anterior y el siguiente. **Gratis y sin scope**, como el ubigeo: un catálogo, no una consulta de documentos. No descuenta cuota ni se audita, y responde también al token público del sandbox, con datos reales.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
fecha path sí string
sector query no string `privado` (por defecto): fines de semana y feriados. `publico`: además, los días no laborables que decreta el Ejecutivo para el sector público, cada uno con su decreto supremo.
EstadoQué significa
200La fecha, si es hábil y los hábiles que la rodean.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404La fecha está fuera del rango que cubre el calendario (motivo: anio_no_disponible).
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/demo/ruc/{ruc}

La demo de la landing: un RUC 20, sin token

Público, para probar antes de pedir acceso. 🔒 **Solo RUC 20**: uno de persona natural (10, 15, 17) responde 403, como a un token sin dni.read. Se audita como cualquier consulta, no se cobra y nunca sale a un proveedor externo. Admite 10 consultas por minuto y 50 al día por IP: para integrar, pide un token.

Scopes: ruc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
ruc path sí string
EstadoQué significa
200La ficha del contribuyente, con su procedencia: la misma que /ruc/{ruc}.
403Códigos posibles: scope_insuficiente. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El RUC no está en el padrón publicado, o la demo está cerrada.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/demo/tipo-cambio

La demo de la landing: el tipo de cambio del día, sin token

Público, para el conversor de la landing. La misma respuesta que /tipo-cambio: se audita y no se cobra. Admite 10 consultas por minuto y 50 al día por IP, aparte de la demo de RUC: para integrar, pide un token.

Scopes: tc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
moneda query no string `USD` (por defecto) o `EUR`. El dólar es el de la SBS; el euro, el que publica el BCRP en soles, sin respaldo de SUNAT.
EstadoQué significa
200La cotización vigente, que puede ser de un día anterior.
404No hay ninguna cotización cargada todavía, o la demo está cerrada.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/dni/batch

Hasta 100 DNIs de una vez

🔒 **Nunca dispara fallback**, aunque el token tenga dni.fallback: la respuesta del batch se guarda 24 h para la idempotencia, y un dato de Clase B no puede acabar en almacenamiento persistente (§15.3, R1).

Scopes: batch, dni.read · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
Idempotency-Key header no string Opcional. La misma clave con los mismos documentos devuelve la misma respuesta, con `Idempotency-Replayed: true` y sin volver a consumir. Con otros documentos, 422.
EstadoQué significa
200Un elemento por documento, con menos campos que la consulta individual. Cruza por dni, no por la posición.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: finalidad_no_declarada, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/dni/{dni}

Identidad de una persona natural por DNI

🔒 Exige dni.read y finalidad declarada (R6). Responde siempre private, no-store. Si el padrón no lo tiene y el token lleva dni.fallback, sale al proveedor externo; sin ese scope devuelve 404 aunque el fallback esté contratado. El 404 lleva meta.motivo y meta.degradado: «no está» y «no pude preguntar» son cosas distintas.

Scopes: dni.read · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
dni path sí string
EstadoQué significa
200La identidad de la persona natural, con Cache-Control: private, no-store.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: finalidad_no_declarada, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El DNI no está en el padrón, o no se pudo preguntar fuera. 🔒 meta.degradado distingue las dos cosas: un 404 degradado NO significa que la persona no exista.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/health

Estado del servicio y frescura del padrón

Público: sin token. dependencias.padron dice si las vistas SIRVEN filas, que no es lo mismo que si el ETL corrió: el padrón puede quedarse vacío con sync_run en ok. estado pasa a degraded si el padrón supera 36 h o no sirve filas, si la auditoría tiene pocos meses por delante, si Redis no responde o si un proxy no es de confianza. degraded responde 200, salvo con ?estricto=1; down —sin PostgreSQL o sin esquema— responde 503.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
estricto query no boolean Con `1`, responde **503** también cuando `estado` es `degraded`. Es para un monitor de uptime que solo mira el código HTTP; sin él, `degraded` responde 200 y solo `down` da 503.
EstadoQué significa
200El servicio, sus dependencias y la edad del padrón.
503down, o degraded con ?estricto=1. El cuerpo es el mismo: dice qué falla.

GET /id/v1/me

Qué es este token y qué puede hacer

Devuelve tres listas de scopes: los del token, los del plan y los **efectivos** (su intersección, §13.3). Un 403 de scope tiene dos causas posibles y esto dice cuál es la tuya. bolsas dice lo que te queda de tus bolsas prepago y cuándo vence la primera. No consume cuota.

Scopes: ninguno · Consume cuota: no

EstadoQué significa
200El token, su plan y los scopes efectivos.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/openapi.json

Esta misma especificación

Público y generado desde la tabla de rutas en cada petición, así que describe **este** despliegue y no la última vez que alguien corrió un comando.

Scopes: ninguno · Consume cuota: no

EstadoQué significa
200Esta misma especificación, generada de la tabla de rutas.

GET /id/v1/proveedor/{ruc}

El alta de proveedor: ficha, padrones de SUNAT, sanciones y vigilancia

Lo que un área de compras revisa antes de dar de alta a una empresa, en una respuesta: la ficha de /ruc/{ruc}; si es agente de retención y buen contribuyente, con la fecha de cada lista de SUNAT; sus inhabilitaciones vigentes para contratar con el Estado, del OSCE; si ya la vigilas en alguna lista de Watch (solo lectura); y avisos legibles. Cuesta una consulta, como la ficha. 🔒 **Solo RUC 20**: un 10, 15 o 17 es 422 sin cobrarse. sanciones es null si no hay lista cargada: no lo sé, que no es «sin sanciones».

Scopes: ruc.read · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
ruc path sí string
EstadoQué significa
200El alta de proveedor, con la procedencia de la ficha en meta.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El RUC no está en el padrón publicado.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/ruc/batch

Hasta 100 RUCs de una vez

Con Idempotency-Key: repetir la misma clave devuelve la respuesta guardada sin volver a cobrar. Cada documento se audita por separado. 🔒 Si el lote trae algún RUC de persona natural (10, 15 o 17), la petición entera exige además dni.read y finalidad declarada, y esos documentos se auditan como DNI (§3.4).

Scopes: batch, ruc.read · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
Idempotency-Key header no string Opcional. La misma clave con los mismos documentos devuelve la misma respuesta, con `Idempotency-Replayed: true` y sin volver a consumir. Con otros documentos, 422.
EstadoQué significa
200Un elemento por documento, con menos campos que la consulta individual. Cruza por ruc, no por la posición.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/ruc/buscar

Búsqueda por razón social

🔒 **Solo tipo 20.** No existe búsqueda por nombre de persona: sería una vía de resolución de identidad sin documento (R4).

Scopes: ruc.search · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
q query sí string Texto de la razón social. 🔒 Solo busca entre contribuyentes tipo `20`.
EstadoQué significa
200Los contribuyentes tipo 20 que casan con la búsqueda.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/ruc/{ruc}

Ficha de contribuyente por RUC

🔒 Un RUC que empieza en 10, 15 o 17 es una PERSONA NATURAL: su nombre es un dato de identidad, así que exige dni.read —no basta ruc.read—, finalidad declarada, y responde private, no-store (§3.4). direccion llega en el 13.2% de los casos y es un techo; ubigeo y sus nombres, en el 82.5%. Los campos del padrón extendido traen su propia fecha en meta.fecha_dato_extendido, que puede ser de hace un mes.

Scopes: ruc.read · Consume cuota: sí

ParámetroEnObligatorioTipoQué es
ruc path sí string
EstadoQué significa
200La ficha del contribuyente, con su procedencia.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: finalidad_no_declarada, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El RUC no está en el padrón publicado. meta.motivo distingue «no está» de «no pude preguntar».
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido, cuota_agotada, tope_excedente_alcanzado, presupuesto_agotado, tope_de_pruebas_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/tipo-cambio

Tipo de cambio de hoy

Compra y venta de la SBS, del BCRP o, si no responde, de SUNAT. Si hoy no hay publicación —fin de semana o feriado— devuelve el último día hábil y lo dice en meta: fecha_dato, antiguedad_dias y, pasados cuatro días, aviso. **Gratis:** no descuenta de tu cuota del mes ni de tu bolsa, y se sigue respondiendo con la cuota agotada. Lleva el límite de peticiones por minuto de tu plan.

Scopes: tc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
moneda query no string `USD` (por defecto) o `EUR`. El dólar es el de la SBS; el euro, el que publica el BCRP en soles, sin respaldo de SUNAT.
EstadoQué significa
200La cotización vigente, que puede ser de un día anterior.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404No hay ninguna cotización cargada todavía.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/tipo-cambio/mes/{periodo}

Tipo de cambio de un mes

Los días con publicación del mes AAAA-MM, en orden cronológico. Es el rango del primer al último día del mes, con la misma respuesta. **Gratis:** no descuenta de tu cuota del mes ni de tu bolsa, y se sigue respondiendo con la cuota agotada. Lleva el límite de peticiones por minuto de tu plan.

Scopes: tc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
periodo path sí string
moneda query no string `USD` (por defecto) o `EUR`. El dólar es el de la SBS; el euro, el que publica el BCRP en soles, sin respaldo de SUNAT.
EstadoQué significa
200Las cotizaciones publicadas del mes. Un mes futuro o sin datos devuelve una lista vacía.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/tipo-cambio/rango

Serie histórica de tipo de cambio

Entre dos fechas. El rango está acotado para que no sea una exportación del histórico completo. **Gratis:** no descuenta de tu cuota del mes ni de tu bolsa, y se sigue respondiendo con la cuota agotada. Lleva el límite de peticiones por minuto de tu plan.

Scopes: tc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
desde query sí string Primer día de la serie, `AAAA-MM-DD`.
hasta query sí string Último día. El rango está acotado para que esto no sea una exportación del histórico completo.
moneda query no string `USD` (por defecto) o `EUR`. El dólar es el de la SBS; el euro, el que publica el BCRP en soles, sin respaldo de SUNAT.
EstadoQué significa
200La serie del intervalo pedido, en orden cronológico.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/tipo-cambio/{fecha}

Tipo de cambio de una fecha

Formato YYYY-MM-DD. Una fecha sin publicación devuelve la última anterior, con meta.fecha_dato, meta.antiguedad_dias y, pasados cuatro días, meta.aviso. Solo una fecha anterior a toda la serie devuelve 404. **Gratis:** no descuenta de tu cuota del mes ni de tu bolsa, y se sigue respondiendo con la cuota agotada. Lleva el límite de peticiones por minuto de tu plan.

Scopes: tc.read · Consume cuota: no

ParámetroEnObligatorioTipoQué es
fecha path sí string
moneda query no string `USD` (por defecto) o `EUR`. El dólar es el de la SBS; el euro, el que publica el BCRP en soles, sin respaldo de SUNAT.
EstadoQué significa
200La cotización de esa fecha o la última anterior, con meta.antiguedad_dias.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404La fecha es anterior a toda la serie: no hay nada que devolver.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/ubigeo/{codigo}

Departamento, provincia y distrito de un código INEI

Catálogo de 1,900 divisiones territoriales. Sin scope: no resuelve ningún documento.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
codigo path sí string
EstadoQué significa
200La división territorial del código INEI.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El código no está en el catálogo.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/uso

Consumo del periodo, desglosado

Solo del tenant del token. cuota.consumidas sale del contador en vivo —es el que decide en cada petición— y consultas.* del consolidado, que se vuelca cada 60 s: pueden diferir en un minuto. No incluye el hit rate: es un KPI interno y necesita las consultas que no encontraron nada. Las bolsas prepago se gastan cuando se acaba la cuota del mes: bolsas.saldo es lo que queda, ya descontado lo que aún no se ha volcado.

Scopes: ninguno · Consume cuota: no

EstadoQué significa
200El consumo del periodo en curso.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/vencimientos/proximos

Los próximos vencimientos SUNAT de un dígito

«¿Qué vence ahora?»: los próximos vencimientos de las obligaciones mensuales (IGV, renta, retenciones, percepciones e ITF) para el **último dígito** del RUC, desde hoy o desde desde. 🔒 Recibe el dígito, nunca el RUC: un ?ruc= es 422. **Gratis y sin scope**, como el ubigeo: un catálogo, no una consulta de documentos. No descuenta cuota ni se audita, y responde también al token público del sandbox, con datos reales.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
digito query sí string El último dígito del RUC, del 0 al 9. Nunca el RUC entero.
buen_contribuyente query no boolean Con `1`, la columna de los buenos contribuyentes y las UESP, que vencen después.
desde query no string Desde qué día, incluido. Por defecto, hoy en Lima.
cantidad query no integer Cuántos vencimientos.
EstadoQué significa
200Los próximos vencimientos, con los días que faltan.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404desde cae después del último año del cronograma (motivo: anio_no_disponible): «no lo sé», no «no vence nada».
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/vencimientos/{anio}

El cronograma de vencimientos SUNAT de un año

Los 12 periodos del año con su vencimiento para cada último dígito del RUC y para los buenos contribuyentes, según la RS 281-2022/SUNAT: el N-ésimo día hábil del mes siguiente. estado: publicado es la tabla que SUNAT publicó; calculado, la regla aplicada a un año que SUNAT aún no publica, con aviso. Los no laborables no mueven el cronograma: son hábiles para fines tributarios. **Gratis y sin scope**, como el ubigeo: un catálogo, no una consulta de documentos. No descuenta cuota ni se audita, y responde también al token público del sandbox, con datos reales.

Scopes: ninguno · Consume cuota: no

ParámetroEnObligatorioTipoQué es
anio path sí string
EstadoQué significa
200El cronograma del año, periodo a periodo.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
404El año está fuera del rango del cronograma (motivo: anio_no_disponible).
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/watch/eventos

Historial de cambios detectados

Los eventos que el diff del padrón generó para los RUC vigilados.

Scopes: watch.manage · Consume cuota: no

ParámetroEnObligatorioTipoQué es
limite query no integer Cuántos eventos devolver, del más reciente al más antiguo.
EstadoQué significa
200Los cambios detectados para los RUC vigilados.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/watch/listas

Listar watchlists

Con el número de RUCs vigilados en cada una.

Scopes: watch.manage · Consume cuota: no

EstadoQué significa
200Las watchlists del tenant, con cuántos RUC vigila cada una.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/watch/listas

Crear una watchlist

Sujeta al tope del plan. Un plan sin Watch lo dice explícitamente.

Scopes: watch.manage · Consume cuota: no

EstadoQué significa
201La lista creada.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido, tope_watch_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/watch/listas/{lista}/rucs

Agregar RUCs a una watchlist

🔒 **Solo tipo 20.** El payload del webhook lleva el nombre, y para un RUC 10 eso sería identidad saliendo a una URL ajena. El tope de RUCs es del TENANT sumando todas sus listas, y un lote que lo rebase se rechaza entero.

Scopes: watch.manage · Consume cuota: no

ParámetroEnObligatorioTipoQué es
lista path sí string
EstadoQué significa
200Cuántos RUC se agregaron y cuáles se rechazaron, con el motivo.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido, tope_watch_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

DELETE /id/v1/watch/listas/{lista}/rucs

Quitar RUCs de una watchlist

Deja de vigilarlos desde el diff siguiente.

Scopes: watch.manage · Consume cuota: no

ParámetroEnObligatorioTipoQué es
lista path sí string
EstadoQué significa
200Cuántos RUC se quitaron.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

GET /id/v1/watch/webhooks

Listar endpoints de webhook

El secreto de firma no se devuelve nunca tras crearlo.

Scopes: watch.manage · Consume cuota: no

EstadoQué significa
200Los endpoints del tenant, con su estado. El secreto no se repite nunca.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/watch/webhooks

Registrar un endpoint de webhook

Devuelve el secreto de firma **una sola vez**. Las entregas van firmadas con HMAC-SHA256 sobre timestamp y cuerpo (§12.4).

Scopes: watch.manage · Consume cuota: no

EstadoQué significa
201El endpoint creado, con su secreto de firma por única vez.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido, tope_watch_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.

POST /id/v1/watch/webhooks/{endpoint}/probar

Enviar una entrega de prueba

Firmada y marcada como prueba. No cuenta para el deshabilitado automático.

Scopes: watch.manage · Consume cuota: no

ParámetroEnObligatorioTipoQué es
endpoint path sí string
EstadoQué significa
200El resultado de la entrega de prueba.
401Códigos posibles: token_invalido, ip_no_permitida. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
403Códigos posibles: no_disponible_en_sandbox, scope_insuficiente, sin_plan_vigente, tenant_suspendido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
422Códigos posibles: documento_invalido, tope_watch_alcanzado. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
429Códigos posibles: rate_limit_excedido. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.
503Códigos posibles: servicio_no_disponible. El catálogo con qué hacer ante cada uno está en /docs, y el enlace viene en error.documentacion.