NexoID desde un asistente de código
Para integrar NexoID con la ayuda de Claude Code, Cursor, Copilot u otro asistente: lo que tiene que saber, y un servidor MCP para que pueda consultar los datos públicos mientras trabaja.
Lo que tiene que saber tu asistente
Copia esto en su contexto —el archivo de instrucciones del proyecto, o el principio de la conversación—:
Integra la API de NexoID: RUC, DNI, tipo de cambio y ubigeo de Perú, desde fuentes oficiales.
- La URL base es https://nexoid.victorllerena.com/id/v1. El contrato OpenAPI está en https://nexoid.victorllerena.com/id/v1/openapi.json, y la documentación
para modelos en https://nexoid.victorllerena.com/llms.txt.
- Llama SIEMPRE desde el servidor. El token (nxid_live_…) va en una variable de entorno, nunca en el
código, en el repositorio ni en el navegador.
- Un RUC que empieza por 10, 15 o 17 es una persona natural: exige el scope dni.read y la finalidad
declarada. Sin ellos responde 403; no es un error del código.
- Valida el RUC y el DNI antes de llamar (formato y dígito verificador): uno mal formado es 422 y no
consume cuota.
- Ante un error, lee error.codigo. Reintenta solo si error.reintentable es true, esperando lo que diga
Retry-After. Un 404 de RUC o DNI con meta.degradado true no significa que no exista.
- Usa el SDK oficial (@nexo-lat/id en Node, nexo/id-php en PHP) en vez de un cliente propio.
- Toda respuesta lleva meta.origen y meta.fecha_dato: guárdalos junto al dato.
El servidor MCP
nexoid-mcp le da al asistente nueve herramientas, todas de datos públicos:
consultar_ruc: La ficha de un RUC de empresa (tipo 20). Rechaza sin llamar un RUC 10, 15 o 17 y un DNI.consultar_proveedor: El alta de proveedor de una empresa: ficha, padrones de SUNAT, sanciones del OSCE y avisos. Rechaza sin llamar un RUC de persona.buscar_empresas: Hasta 20 empresas por su razón social.tipo_cambio: El de hoy, una fecha, un rango o un mes; en dólares o en euros. No consume cuota.consultar_ubigeo: El departamento, la provincia y el distrito de un código de 6 dígitos.feriados: Los feriados de un año con su norma y, para el sector público, los no laborables. No consume cuota.plazo_habil: En qué fecha vence un plazo de N días hábiles, y qué días se saltó. No consume cuota.vencimientos_sunat: Lo próximo que vence en SUNAT para el último dígito de un RUC; nunca recibe el RUC. No consume cuota.mi_uso: Qué puede hacer el token y cuánto se ha consumido este mes.
🔒 No hay ninguna de DNI, y no la habrá. Lo que devuelve una herramienta entra en la conversación, y a esa
conversación la procesa el proveedor del asistente: el nombre de una persona no puede viajar ahí sin una base
legal. Para consultar personas, tu backend, con un token con dni.read y la finalidad declarada.
Instalarlo
Todavía no está en npm: te lo damos empaquetado, junto con el SDK de JS que usa.
npm install -g ./nexo-lat-id-<versión>.tgz ./nexoid-mcp-<versión>.tgz
Configurarlo
Con un token solo de empresas —ruc.read, ruc.search y tc.read—, nunca uno con dni.read:
{
"mcpServers": {
"nexoid": {
"command": "nexoid-mcp",
"env": { "NEXOID_TOKEN": "nxid_live_…" }
}
}
}
Cada consulta del asistente es una consulta de tu cuenta: consume tu cuota y se audita como cualquier otra.