Saltar al contenido principal

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.

Listado de empresas con el botón del asistente en la esquina inferior derecha

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.

Listado de empresas con el panel del asistente abierto a la derecha, con el saludo, el estado del índice, las preguntas frecuentes, el micrófono y la caja para escribir

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

ControlQué hace
Preguntas frecuentesCinco preguntas de ejemplo. Al hacer clic en una se envía tal cual. Desaparecen con la primera pregunta.
La caja de textoEscribe tu pregunta con tus palabras, hasta 500 caracteres. Enter la envía y Mayús + Enter salta de línea.
El micrófonoDicta la pregunta en vez de escribirla. Ver Preguntar por voz.
EnviarEnvía la pregunta. Mientras el asistente redacta, el chat muestra una burbuja con tres puntos animados y la palabra Pensando...
LimpiarBorra la conversación y vuelve el saludo con las preguntas frecuentes.
El icono de la esquina del encabezadoAbre 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.

Pantalla Documentación con el botón Preguntar al asistente y el manual embebido

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.

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.

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​

MensajeQué 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​

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 .envQué se pone
MANUAL_AI_API_KEYOpcional. 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_URLLa 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_URLLa 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_PROVIDEROpcional. anthropic (lo normal) u openai, si prefieres responder con OpenAI.
MANUAL_AI_MODELOpcional. El modelo que responde. Sin él se usa el que trae el sistema para ese proveedor.
MANUAL_AI_EMBEDDINGS_API_KEYOpcional. 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=
No ponga otra dirección en MANUAL_AI_RELAY_URL

Esa 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.

  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 --force. 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 responde ya con tu cuenta.

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​

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 llamaOtro servidor, no un usuario: es pública y no lleva token.
Lo que recibequestion (obligatorio, hasta 500 caracteres), previous y previous_answer (opcionales).
Lo que devuelvesuccess, answer, sources, images y screen con la página del manual, que cada instalación convierte en su propia pantalla.
Tope60 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á indexadoResponde 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.

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í.