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 y viene activo sin configurar nada: las
instalaciones que no tienen token propio responden con el asistente incluido de FacturaLatam.
Lo único que es cosa de quien administra el servidor es apagarlo o hacer que responda con su
propia cuenta, y eso se hace en el archivo .env: ver Configurarlo.
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.

El mismo panel se abre con el botón ? de la barra superior, a la derecha de la campanita.
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:
- Una frase que resume qué se hace y dónde.
- En el panel: el paso a paso, con el nombre exacto de cada menú, botón y campo.
- Por el API: la ruta y el método del servicio, qué cabecera lleva
(
Authorization: Bearer {api_token}, oX-Admin-Tokenen las rutas de administración de la plataforma) y el JSON de ejemplo recortado a los campos de los que habla. - 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.
La respuesta se ve con párrafos separados, listas numeradas con sangría, los nombres de los botones en negrita, el código en línea sobre fondo claro y los enlaces del manual pulsables, que se abren en una pestaña nueva.
No hace falta que uses las palabras del manual: anular o cancelar una factura llevan a la
nota de crédito, clave o llave al api_token, validada o rechazada a la consulta de
estado, y nómina a los servicios de payroll.
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.
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:
- 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.
- Habla con normalidad.
- 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 está apagado en esta instalación... | El administrador lo apagó en el .env. La caja de texto queda deshabilitada. |
| Todavía no tengo cargada la documentación... | Responde con la cuenta propia de la instalación 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... | Con cuenta propia, el proveedor de IA no respondió: sin saldo, llave vencida o modelo inexistente. Avisa al administrador. |
| No pude responderle porque el asistente no está respondiendo en este momento... | Con el asistente incluido: el servidor central no respondió. Vuelve a preguntar en unos minutos. |
| No pude responderle porque se hicieron muchas preguntas seguidas desde este servidor... | Con el asistente incluido: entre todos los usuarios de la instalación se pasó el tope del servidor central. Espera un minuto. |
Configurarlo
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 | Opcional. El token de la cuenta propia de Claude (Anthropic) con el que responde el asistente; empieza por sk-ant-. Vacío, responde el asistente incluido. |
MANUAL_AI_RELAY_URL | La dirección del servidor central que responde cuando no hay token propio. De fábrica, https://api.facturapro.co. Vacía apaga el asistente: no aparece el botón. |
MANUAL_URL | La dirección pública del manual que el asistente indexa. De fábrica, https://docs.facturable.co; 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. |
El asistente incluido viene activo
Como el token del proveedor de IA es de FacturaLatam y no puede estar en el .env de cada
cliente, las instalaciones sin token propio le envían la pregunta al servidor central de
FacturaLatam (MANUAL_AI_RELAY_URL), que es el que tiene la llave y el índice del manual, y
devuelven la respuesta ya redactada. Así que:
- No hay nada que configurar ni que indexar en su servidor, y el token nunca viaja a la instalación.
- El único requisito es que el servidor tenga salida a internet por HTTPS hacia
api.facturapro.co. - Las respuestas se ven igual —con sus enlaces del manual y sus capturas— y el enlace que abre la pantalla del panel se resuelve con las rutas de su instalación.
- El chat no muestra la línea del estado del índice al administrador, porque el índice está en el servidor central.
Para apagar el asistente, añada esta línea tal cual, vacía, al .env (dejando también vacía
MANUAL_AI_API_KEY) y ejecute php artisan config:clear:
MANUAL_AI_RELAY_URL=
MANUAL_AI_RELAY_URLEsa variable solo admite dos valores: el que trae de fábrica o vacía para apagar el asistente.
Responder con su propia cuenta
Es opcional. Con el token puesto, la instalación responde con su cuenta del proveedor y su propio
índice, y deja de usar el asistente incluido. 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.
-
Aplica las migraciones de esta versión en el servidor:
php artisan migrate. -
Pon el token en el
.env:MANUAL_AI_API_KEY=sk-ant-... -
Recarga la configuración:
php artisan config:clear. -
Construye el índice del manual:
php artisan manual:index --force. Descarga el manual completo, así que tarda; al terminar informa cuántas secciones, capturas y ejemplos quedaron indexados. -
Entra al panel: el botón del asistente responde ya con tu cuenta.
.env necesita config:clearSi 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
Solo hace falta con cuenta propia: con el asistente incluido, el índice lo mantiene el servidor central.
El índice es una copia del manual, así que envejece cuando la documentación cambia. Al abrir el chat, el administrador de la plataforma —y solo él— ve arriba una línea gris con el estado del índice: Índice del manual: indexado el 02/11/2026 00:29 · 767 trozos · 46 capturas · 152 JSON de los servicios. Si esa fecha se quedó atrás, el asistente está respondiendo con un manual viejo.
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, y con el asistente incluido tampoco: avisa El
asistente usa el servidor central: no hace falta indexar aquí. En los dos casos
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
Ser el servidor central
Es el caso de FacturaLatam y, en general, de quien atiende las preguntas de otras instalaciones.
Hay que pedirlo a propósito, para que una instalación con token propio no acabe pagando las
preguntas de las demás: en el .env, junto a MANUAL_AI_API_KEY, se añade
MANUAL_AI_RELAY_SERVER=true
Con las dos cosas puestas, esa instalación publica POST /api/manual/assistant/relay, la ruta por
la que las demás le preguntan. Donde falte alguna de las dos, la ruta responde 404.
| Detalle de la ruta | |
|---|---|
| Quién la llama | Otro servidor, no un usuario: es pública y no lleva token. |
| Lo que recibe | question (obligatorio, hasta 500 caracteres), previous y previous_answer (opcionales). |
| Lo que devuelve | success, answer, sources, images y screen con la página del manual, que cada instalación convierte en su propia pantalla. |
| Tope | 60 preguntas por minuto y 2.000 por día por dirección IP. Al pasarse, quien pregunta ve el aviso de muchas preguntas seguidas. |
| Si no está indexado | Responde que no tiene cargada la documentación y lo anota en el log: hay que correr php artisan manual:index --force en el servidor central. |
El motivo real de un fallo (saldo, llave, modelo) queda en el log del servidor central y no viaja a la instalación que preguntó, que solo recibe si conviene esperar o reintentar.
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í.