Perfil isp/1.0

Versión 1.0 · 13 de octubre de 2026. La definición para máquinas es perfil-isp-1.0.json; el SDK PHP (JesgIA\Conector\Perfil, desde la versión 1.2.0) la trae incorporada.

Este perfil es el contrato entre JesgIA y el sistema de gestión de un proveedor de internet. El personal pregunta en el chat («¿qué plan e IP tiene Juan Pérez?», «¿cuánto debe el abonado 1520?», «¿qué averías tiene la señora Quispe?»). JesgIA le pide los datos al sistema con herramientas de solo lectura y redacta la respuesta.

JesgIA nunca escribe SQL ni ve la base del ISP. Recibe solo los campos de este perfil, y el ISP decide qué puede ver cada rol.

1. Lo que es igual al perfil comercial

La conexión, la firma Ed25519, el anti-replay, el manifest, el formato de la petición y de la respuesta, los códigos de error, el token del widget y la prueba de conformidad son idénticos a los de comercial-1.0.md (secciones 1 a 4, 6 y 7). Solo cambian:

el valor de perfil, que es "isp/1.0" en el manifest, en cada petición y en cada respuesta;
las herramientas (sección 3).

En el SDK basta con una línea en la configuración del conector:

'perfil' => 'isp/1.0',

Reglas comunes: solo lectura, como máximo 10 filas, 3 segundos por respuesta, HTTPS.

2. Datos que nunca salen del sistema

Ninguna herramienta devuelve contraseñas ni credenciales:

las contraseñas PPPoE o hotspot de los abonados;
las credenciales de API de los equipos;
el usuario y la contraseña de los routers, OLT y MikroTik;
las claves del personal.

Se recomienda que el usuario de base de datos del conector tenga permiso solo sobre vistas que no incluyan esas columnas. Así no pueden salir ni por un error en el código.

Un sistema que aloja varios ISP en la misma base filtra cada consulta por el ISP del tenant. Ese ISP se configura en el servidor del sistema, nunca se toma de la petición.

3. Herramientas

Los tipos de los campos son los de comercial-1.0.md (sección 5): texto, numero, entero, fecha, moneda, lista:X. Un tipo terminado en ? admite null.

id_abonado es siempre el id que devuelve buscar_abonado (1–60 caracteres).

buscar_abonado


Parámetro	`texto` (2–100): parte del nombre o apellidos, o DNI/RUC, teléfono, código, IP o usuario PPPoE exactos
Devuelve (lista)	`id` (texto), `nombre`, `documento` (texto?), `telefono` (texto?), `direccion` (texto?), `estado` (texto?: activo, suspendido, retirado… en las palabras del sistema)

ficha_servicio


Parámetro	`id_abonado`
Devuelve (lista: un abonado puede tener varios servicios)	`servicio` (texto: código del servicio), `tipo` (texto?: fibra, inalámbrico…), `plan` (texto?), `tarifa` (numero?), `moneda`, `ip` (texto?), `usuario_pppoe` (texto?), `router` (texto?), `nodo` (texto?), `caja` (texto?), `puerto` (entero?), `onu` (texto?: serie o MAC)

Si el abonado existe pero no tiene servicios registrados, la respuesta es NO_ENCONTRADO.

recibos_pendientes


Parámetro	`id_abonado`
Devuelve (un registro)	`deuda_total` (numero), `moneda`, `recibos`: lista, del más antiguo al más reciente, de {`periodo` (texto: «Septiembre 2026»), `plan` (texto?), `importe` (numero), `descuento` (numero), `saldo` (numero), `emitido` (fecha?)}

Si el abonado existe y está al día, la respuesta es deuda_total 0 y recibos vacío. No es NO_ENCONTRADO.

pagos_abonado


Parámetros	`id_abonado`; `dias` (opcional, entero 1–730, 90 por defecto)
Devuelve (lista, del más reciente al más antiguo)	`fecha` (fecha), `concepto` (texto?), `importe` (numero), `moneda`, `medio` (texto?: efectivo, Yape, banco…), `operacion` (texto?: número de operación)

averias_abonado


Parámetros	`id_abonado`; `estado` (opcional, texto libre del sistema: «pendiente», «atendida»…)
Devuelve (lista, de la más reciente a la más antigua)	`numero` (texto), `fecha` (fecha), `motivo` (texto?), `estado` (texto?), `descripcion` (texto), `solucion` (texto?), `fecha_solucion` (fecha?), `tecnico` (texto?)

equipos_abonado


Parámetro	`id_abonado`
Devuelve (lista)	`modelo` (texto), `serie` (texto), `estado` (texto?), `registrado` (fecha?)

4. Lo que no está en esta versión

Quedan para versiones posteriores del perfil:

El estado en línea del abonado, es decir, si está conectado ahora, su IP actual y el tiempo conectado. Se consulta en vivo al router, no en la base.
Las acciones que modifican datos: suspender o reactivar un servicio, registrar una avería y registrar una solicitud de alta. Irán con confirmación explícita del operador, permisos por rol y registro de quién confirmó.

Agregar una herramienta opcional será isp/1.1. Cambiar o quitar campos será isp/2.0. Un sistema conforme con isp/1.0 lo sigue siendo.