Asistente IA

El panel tiene un asistente que responde preguntas sobre la plataforma usando únicamente este manual: el de las pantallas y el de los servicios. No inventa: cada respuesta trae el enlace a la página de la documentación de donde salió y, cuando la hay, la captura de esa pantalla o el JSON que se envía al servicio.

Lo usa cualquier cuenta con la sesión iniciada. Configurarlo, en cambio, es cosa de quien administra el servidor: se hace en el archivo .env y hasta que no se ponga el token el asistente no aparece.

El botón y el panel

Cuando el asistente está activo, en la esquina inferior derecha de todas las pantallas del panel hay un botón redondo con una diadema de soporte, acompañado al principio del aviso ¿Necesita ayuda? Pregúntele al asistente.

Al hacer clic, el chat entra deslizándose desde el borde derecho y ocupa todo el alto de la pantalla, sin sacarte de donde estabas. El resto del panel queda atenuado detrás.

Se cierra de tres formas: con la × del encabezado, pulsando fuera del panel o con la tecla Esc.

Control	Qué hace
Preguntas frecuentes	Cinco preguntas de ejemplo. Al hacer clic en una se envía tal cual. Desaparecen con la primera pregunta.
La caja de texto	Escribe tu pregunta con tus palabras, hasta 500 caracteres. Enter la envía y Mayús + Enter salta de línea.
El micrófono	Dicta la pregunta en vez de escribirla. Ver Preguntar por voz.
Enviar	Envía la pregunta. Mientras el asistente redacta, el chat muestra una burbuja con tres puntos animados y la palabra Pensando...
Limpiar	Borra la conversación y vuelve el saludo con las preguntas frecuentes.
El icono de la esquina del encabezado	Abre el manual completo en una pestaña nueva.
×	Cierra el panel. La conversación no se pierde: ver La conversación te sigue.

Desde la pantalla Documentación hay además un botón Preguntar al asistente, que abre ese mismo chat.

Cómo son las respuestas

Todas siguen la misma estructura, y las partes que no aplican simplemente no aparecen:

1. Una frase que resume qué se hace y dónde.
2. En el panel: el paso a paso, con el nombre exacto de cada menú, botón y campo.
3. Por el API: la ruta y el método del servicio, qué cabecera lleva (Authorization: Bearer {api_token}, o X-Admin-Token en las rutas de administración de la plataforma) y el JSON de ejemplo recortado a los campos de los que habla.
4. Tenga en cuenta: las advertencias del manual (lo que no se puede deshacer, lo que conviene probar primero en Habilitación).

Lo del panel va primero, salvo que preguntes por un JSON, una ruta, un token o una integración. Si una de las dos vías no existe, el asistente lo dice en una línea y sigue con la que sí existe.

Debajo de la respuesta puede aparecer:

• El enlace que abre la pantalla del panel donde se hace lo que explica (por ejemplo Cargue el certificado, el software y la resolución en Empresas → ⋮ → Configuración inicial).
• La línea En la documentación: con los enlaces a las páginas de este manual que se usaron para responder. Se abren en una pestaña nueva.
• La captura de pantalla del apartado, si la tiene.
• Los bloques de código con los botones Ajustar (parte las líneas largas), Ampliar (lo abre en grande) y Copiar.

El asistente recuerda tu pregunta anterior y la respuesta que te dio, lo justo para entender un seguimiento del tipo ¿y cómo la anulo? o ¿y por el API?. No es una conversación con memoria larga.

Pregunta de una cosa a la vez

Las preguntas concretas —¿cómo cargo el certificado?, ¿qué JSON envío para una nota crédito?— dan mejores respuestas que las generales. Si el asistente no encuentra el tema, lo dice y te sugiere reformular o escribir a soporte: no se inventa la respuesta.

Preguntar por voz

El botón del micrófono, a la derecha de la caja de texto, dicta la pregunta:

1. Púlsalo: la caja se reemplaza por una barra roja con un punto que parpadea, el tiempo de grabación y lo que se va reconociendo.
2. Habla con normalidad.
3. Pulsa el ✓ (o el micrófono otra vez) para dar por terminada la grabación: lo dictado queda escrito en la caja de texto, para que lo revises y lo corrijas antes de enviarlo. La papelera de la barra descarta la grabación sin escribir nada.

El dictado lo pone el propio navegador, así que solo funciona en Google Chrome y Microsoft Edge y con el panel abierto por https (o en localhost). Si no se cumple, al pulsar el micrófono el asistente te explica en el chat por qué no puede grabar. Lo mismo si falta el permiso del micrófono, si no hay micrófono conectado o si no te escuchó.

La conversación te sigue

Las preguntas y respuestas se guardan en el navegador, así que cambiar de pantalla del panel no borra el chat: al volver a abrir el panel siguen ahí, y si lo dejaste abierto vuelve abierto. Se conservan los últimos 20 mensajes de la pestaña; las capturas incrustadas en una respuesta no se guardan, por lo que al recuperar la conversación esa respuesta se ve sin imagen.

La conversación es de esa pestaña del navegador: se pierde al cerrarla, en otra pestaña empieza en blanco y el botón Limpiar la borra cuando quieras.

Mensajes que puedes ver

Mensaje	Qué pasa
El asistente todavía no está activo...	Falta el token en el .env. La caja de texto queda deshabilitada.
Todavía no tengo cargada la documentación...	Está activo pero sin índice: hay que correr php artisan manual:index en el servidor.
Va muy rápido: espere un minuto y vuelva a preguntar.	Hay un tope de 20 preguntas por minuto y por usuario.
Su sesión se cerró...	Vuelve a entrar al panel.
No pude responderle porque...	El proveedor de IA no respondió: sin saldo, llave vencida o modelo inexistente. Avisa al administrador.

Configurarlo

Se configura en el servidor

El asistente no tiene pantalla de configuración: todo va en el archivo .env de la instalación. El token y el índice son de la plataforma, no de una empresa.

Variable del .env	Qué se pone
MANUAL_AI_API_KEY	El token de la cuenta de Claude (Anthropic) con el que responde el asistente; empieza por sk-ant-. Vacío deja el asistente apagado: no aparece el botón.
MANUAL_URL	La dirección pública del manual que el asistente indexa. De fábrica, https://manual.facturalatam.com; quien tenga su propio manual lo pone aquí.
MANUAL_AI_PROVIDER	Opcional. anthropic (lo normal) u openai, si prefieres responder con OpenAI.
MANUAL_AI_MODEL	Opcional. El modelo que responde. Sin él se usa el que trae el sistema para ese proveedor.
MANUAL_AI_EMBEDDINGS_API_KEY	Opcional. Llave de OpenAI que se usa solo para encontrar el apartado que responde la pregunta. Sin ella la búsqueda es por palabras.

Puesta en marcha

Hace falta que el servidor tenga salida a internet hacia el manual (MANUAL_URL) y hacia el proveedor de IA (api.anthropic.com o api.openai.com): el índice se arma descargando el manual y cada respuesta se pide al proveedor.

1. Aplica las migraciones de esta versión en el servidor: php artisan migrate.

2. Pon el token en el .env:

   MANUAL_AI_API_KEY=sk-ant-...

3. Recarga la configuración: php artisan config:clear.

4. Construye el índice del manual: php artisan manual:index. Descarga el manual completo, así que tarda; al terminar informa cuántas secciones, capturas y ejemplos quedaron indexados.

5. Entra al panel: el botón del asistente ya aparece en todas las pantallas.

Cada cambio del .env necesita config:clear

Si cambias el token o cualquiera de las otras variables, ejecuta php artisan config:clear o el API seguirá usando el valor anterior.

Los embeddings son opcionales

Con solo el token de Claude, el asistente busca el apartado por palabras y responde igual. MANUAL_AI_EMBEDDINGS_API_KEY mejora la búsqueda: mide el parecido entre la pregunta y el texto del manual, así que encuentra el apartado aunque lo preguntes con otras palabras. Se puede agregar después; basta volver a construir el índice para que los calcule.

Si el cálculo se corta a medias (sin saldo, por ejemplo), el mensaje lo dice y el asistente sigue funcionando por palabras. Vuelve a correr php artisan manual:index para completar los que falten: lo ya calculado se conserva y no se vuelve a pagar.

Mantener el índice al día

El índice es una copia del manual, así que envejece cuando la documentación cambia. La plataforma lo rehace todos los días a las 3:30, siempre que el cron de schedule:run esté activo. También puedes lanzarlo a mano en el servidor:

php artisan manual:index

Con el asistente apagado el comando no hace nada; php artisan manual:index --force lo reconstruye de todos modos.

Si no tiene el cron de schedule:run, vuelva a construir el índice cada vez que se actualice el manual. La línea del cron es:

* * * * * cd /ruta/del/api && php artisan schedule:run >> /dev/null 2>&1

En Docker, los comandos son los mismos dentro del contenedor del API:

docker compose exec php_api php artisan manual:index --force

Si algo no responde, mire el log

Los errores del asistente quedan en storage/logs/laravel.log y empiezan por ManualAssistant:. Si el modelo de MANUAL_AI_MODEL no existe en el proveedor, responde con el modelo por defecto y lo deja anotado ahí.