Guía de integración

Conecta tu sistema de gestión con JesgIA: tu personal le pregunta al asistente en una ventana de chat dentro de tu sistema, y JesgIA responde con los datos reales de tu empresa.

Cómo funciona

1. Tu personal escribe en el chat flotante de tu sistema, por ejemplo «¿cuánto stock hay de arroz?».
2. JesgIA reconoce qué dato necesita y se lo pide a tu sistema con una petición firmada.
3. Tu sistema responde con el SDK, solo con lo que el rol de esa persona puede ver.
4. El asistente redacta la respuesta con esos datos.

Lo que tu sistema controla:

• Qué datos salen. Solo los campos del perfil comercial/1.0; nada de SQL, costos ni datos internos.
• Quién ve qué. Tu sistema decide con el rol de cada usuario.
• Solo lectura. JesgIA nunca escribe en tu sistema.

Antes de empezar

Escríbenos para dar de alta tu sistema. Te pediremos:

• la URL donde estará tu endpoint, por ejemplo https://sistema.tuempresa.pe/jesgia.php;
• las direcciones desde donde se abrirá el chat, por ejemplo https://sistema.tuempresa.pe.

Paso 1 · Descarga el SDK

Descarga la versión actual desde el portal de descargas. El zip ya trae la clave pública de JesgIA (clave_publica_jesgia.txt).

Comprueba que el archivo no se alteró comparando su huella SHA-256 con la que muestra el portal:

sha256sum jesgia-conector-php-X.Y.Z.zip              # Linux
shasum -a 256 jesgia-conector-php-X.Y.Z.zip          # macOS
Get-FileHash jesgia-conector-php-X.Y.Z.zip           # Windows (PowerShell)

Descomprímelo fuera de la raíz web, por ejemplo en /var/www/privado/jesgia-conector-php/.

Paso 2 · Crea un usuario de solo lectura

Crea vistas con los nombres de campo del perfil y un usuario que solo pueda leerlas. Así, aunque haya un error en una consulta, nada interno puede salir:

CREATE VIEW v_jesgia_productos AS
    SELECT codigo AS sku, descripcion AS nombre, und AS unidad, stock_actual AS stock,
           precio_venta AS precio, 'PEN' AS moneda
      FROM productos WHERE activo = 1;

CREATE USER 'jesgia_lector'@'localhost' IDENTIFIED BY 'una-clave-larga';
GRANT SELECT ON tu_base.v_jesgia_productos TO 'jesgia_lector'@'localhost';

Paso 3 · Escribe tus herramientas

Copia ejemplo/arranque.php junto al SDK. Completa tu tenant y los datos de tu empresa, y escribe una función por cada herramienta que tu sistema pueda responder:

Al escribir cada consulta:

• Usa siempre sentencias preparadas.
• Pon LIMIT 11: el SDK muestra 10 y, si hay una más, avisa que hay más resultados.
• Aplica tus permisos con $usuario->rol. Por ejemplo, el rol de almacén no ve precios.

Las herramientas que no declares responden NO_IMPLEMENTADO. Los campos exactos de cada una están en la especificación.

Paso 4 · Publica el endpoint

Copia ejemplo/jesgia.php a tu raíz web y apúntalo a tu arranque.php. Es el único archivo del conector que queda dentro de la web.

Debe responder en estas dos direcciones:

• https://tu-sistema/jesgia.php/manifest
• https://tu-sistema/jesgia.php/ejecutar

Si tu servidor no admite PATH_INFO, usa jesgia.php?accion=manifest.

Paso 5 · Pasa la prueba de conformidad

php jesgia-conector-php/bin/conformidad.php arranque.php casos.php --url=https://tu-sistema/jesgia.php --json

En casos.php (plantilla en ejemplo/casos.php) pon, para cada herramienta, parámetros que encuentren datos y otros que no. Envíanos el informe que genera --json:

• JesgIA verifica tu endpoint con una petición firmada.
• Tu sistema se activa cuando el informe dice "aprobado": true.

Paso 6 · Muestra el chat flotante

1. El endpoint del token. Copia ejemplo/jesgia-token.php a tu raíz web y adapta las tres líneas marcadas:

• dónde está el SDK;
• cómo guarda tu sistema al usuario en la sesión;
• la dirección de JesgIA: https://IA.TU-DOMINIO.

La API key va en el entorno del servidor (por ejemplo SetEnv JESGIA_API_KEY … en Apache). Nunca en el código ni en el navegador.

2. El snippet. Pégalo antes de </body> en las páginas donde quieras el chat:

<script src="https://IA.TU-DOMINIO/widget.js" data-token-url="/jesgia-token.php" defer></script>

Si la ficha cambia sin recargar la página, usa JesgIA.contexto({id_cliente: "2"}). También puedes abrir el chat con JesgIA.abrir() o enviar una pregunta con JesgIA.preguntar("…").

3. Si tu sitio usa Content-Security-Policy, agrega la dirección de JesgIA:

script-src  'self' https://IA.TU-DOMINIO;
connect-src 'self' https://IA.TU-DOMINIO;

Seguridad

• API key. Vive solo en tu servidor. Si se filtra, pídenos rotarla: la anterior sigue valiendo unos días para que cambies la configuración sin cortes.
• Peticiones firmadas. Cada petición de JesgIA está firmada (Ed25519), lleva fecha y no se puede repetir. El SDK rechaza cualquier petición sin firma válida.
• Token del chat. Dura 15 minutos y está atado al usuario y a su rol. El widget lo guarda solo en memoria.
• Lo que escribe el asistente se muestra siempre como texto, nunca como HTML.

Problemas frecuentes

Actualizar el SDK

Descarga la versión nueva y reemplaza la carpeta jesgia-conector-php/. Tus archivos (arranque.php, casos.php, jesgia.php y jesgia-token.php) están fuera de ella y no se tocan.

Lee en el historial de versiones qué cambió y vuelve a pasar la prueba de conformidad.