NexoID · API de RUC y DNI

Resuelve RUC y DNI peruanos desde fuentes oficiales, con la procedencia de cada dato en la respuesta. Sin caché de borde: cada consulta llega al origen y queda auditada.

Crear una cuenta gratis

Empezar

La base es http://nexoid.victorllerena.com/id/v1 y la autenticación es un bearer token. Los tokens empiezan por nxid_live_ o nxid_test_; los de pruebas no consumen cuota.

curl -H "Authorization: Bearer nxid_test_…" \
     http://nexoid.victorllerena.com/id/v1/ruc/20131312955

🔒 La sorpresa que se lleva todo el mundo al migrar. Un RUC que empieza por 10, 15 o 17 es una persona natural: su campo nombre es el nombre de alguien, y por eso GET /ruc/10452159428 entrega lo mismo que GET /dni/45215942.

El régimen lo decide el contenido, no la ruta. Un token con solo ruc.read recibe 403 scope_insuficiente al consultarlo, la respuesta va private, no-store y la auditoría guarda el documento hasheado. Si vienes de otro proveedor, este es el primer 403 que verás.

Los datos de identidad exigen además finalidad declarada, base legal y anexo de tratamiento firmado. No se activan desde la web: se tramitan con nosotros.

Endpoints

Endpoint	Scopes	Cuota
`POST /dni/batch` Hasta 100 DNIs de una vez	`batch` `dni.read`	sí
`GET /dni/{dni}` Identidad de una persona natural por DNI	`dni.read`	sí
`GET /health` Estado del servicio y frescura del padrón	público	no
`GET /me` Qué es este token y qué puede hacer	—	no
`GET /openapi.json` Esta misma especificación	público	no
`POST /ruc/batch` Hasta 100 RUCs de una vez	`batch` `ruc.read`	sí
`GET /ruc/buscar` Búsqueda por razón social	`ruc.search`	sí
`GET /ruc/{ruc}` Ficha de contribuyente por RUC	`ruc.read`	sí
`GET /tipo-cambio` Tipo de cambio de hoy	`tc.read`	sí
`GET /tipo-cambio/rango` Serie histórica de tipo de cambio	`tc.read`	sí
`GET /tipo-cambio/{fecha}` Tipo de cambio de una fecha	`tc.read`	sí
`GET /ubigeo/{codigo}` Departamento, provincia y distrito de un código INEI	—	no
`GET /uso` Consumo del periodo, desglosado	—	no
`GET /watch/eventos` Historial de cambios detectados	`watch.manage`	no
`GET /watch/listas` Listar watchlists	`watch.manage`	no
`POST /watch/listas` Crear una watchlist	`watch.manage`	no
`POST /watch/listas/{lista}/rucs` Agregar RUCs a una watchlist	`watch.manage`	no
`DELETE /watch/listas/{lista}/rucs` Quitar RUCs de una watchlist	`watch.manage`	no
`GET /watch/webhooks` Listar endpoints de webhook	`watch.manage`	no
`POST /watch/webhooks` Registrar un endpoint de webhook	`watch.manage`	no
`POST /watch/webhooks/{endpoint}/probar` Enviar una entrega de prueba	`watch.manage`	no

El contrato completo, con parámetros y descripciones, está en OpenAPI 3.1 — generado de la tabla de rutas en cada petición, así que describe este despliegue.

Probar ahora

Pega tu token de pruebas y lanza una consulta de verdad contra esta misma instalación.

🔒 Solo tokens nxid_test_. Con uno de producción esta página gastaría tu cuota, y la petición saldría con nuestra IP — saltándose la allowlist que tú configuraste. Tu token no se guarda en ningún sitio.

Token de pruebas Endpoint

Los parámetros vienen rellenos con un ejemplo. Puedes cambiarlos tras enviar.

Catálogo de errores

Toda respuesta de error trae un error.codigo estable. Ramifica por él, nunca por el mensaje ni por el status: dos códigos distintos pueden compartir status y significar cosas opuestas.

Código	Qué hacer
`token_invalido`	Revisa la cabecera `Authorization: Bearer`. El token pudo expirar o ser revocado.
`ip_no_permitida`	El token tiene allowlist de IPs y la petición no sale de ninguna. Se cambia desde el panel.
`scope_insuficiente`	El scope efectivo es la intersección del token con el plan: mira `scopes_efectivos` en `/me` para saber cuál de los dos falta.
`finalidad_no_declarada`	Faltan finalidad, base legal o el anexo de tratamiento firmado. Es requisito para servir identidad y se resuelve con nosotros, no en el código.
`tenant_suspendido`	La cuenta está suspendida. Contacta con soporte.
`sin_plan_vigente`	La cuenta no tiene suscripción vigente. Sin plan no hay scopes, así que esto no se arregla esperando.
`documento_invalido`	El RUC o el DNI no pasan la validación de formato o de dígito verificador. Valídalo en tu lado y ahorras la llamada.
`rate_limit_excedido`	Vas demasiado rápido. Reintenta pasado lo que diga `Retry-After`.
`presupuesto_agotado`	El presupuesto mensual de consultas a fuentes externas se agotó. El documento podría existir; no es un 404.
`cuota_agotada`	La cuota del periodo se acabó y el plan no permite excedente. Se arregla subiendo de plan.
`tope_excedente_alcanzado`	El plan sí permite excedente, pero se alcanzó el tope de gasto configurado para tu cuenta. Se arregla subiendo el tope, no el plan.

Lo que NexoID no hace

No hay búsqueda de personas naturales por nombre. La búsqueda por razón social devuelve solo RUC tipo 20.
No hay exportación ni descarga masiva, ni endpoints que devuelvan poblaciones.
No hay scoring, inferencias, datos sensibles ni biometría.
No hay caché de borde: cada consulta llega al origen y queda registrada.

No es una lista de funciones pendientes: es el diseño. Un servicio que resuelve identidad y además deja barrerla no es lo mismo con más funciones — es otra cosa.