# Acredita desde un asistente de código

Para integrar Acredita 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—:

```text
Integra la API de Acredita: RUC, DNI, tipo de cambio y ubigeo de Perú, desde fuentes oficiales.
- La URL base es https://acredita.stackealabs.com/id/v1. El contrato OpenAPI está en https://acredita.stackealabs.com/id/v1/openapi.json, y la documentación
  para modelos en https://acredita.stackealabs.com/llms.txt.
- Llama SIEMPRE desde el servidor. El token (acr_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.

```bash
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`:

```json
{
  "mcpServers": {
    "nexoid": {
      "command": "nexoid-mcp",
      "env": { "ACREDITA_TOKEN": "acr_live_…" }
    }
  }
}
```

Cada consulta del asistente es una consulta de tu cuenta: consume tu cuota y se audita como cualquier otra.