API de Chat

La API de Chat es el servicio backend Hono.js que impulsa el asistente de fiskaly Workspace. Proporciona streaming de eventos enviados por el servidor (SSE), recuperación de contexto RAG mediante Vertex AI y una sólida capa de seguridad tanto para el chat público como para los paneles de administración.

Capacidades principales

• Respuestas en streaming — Los Server-Sent Events (SSE) entregan caracteres escritos con baja latencia y metadatos estructurados.
• Fundamentación RAG — El contexto se recupera de 5 fuentes integradas (Docs MDX, OpenAPI, Base de conocimientos de Zendesk, Web y PDFs).
• Dos modelos — Las solicitudes se enrutan inteligentemente entre Gemini 2.5 Pro (consultas complejas) y Gemini 2.0 Flash (consultas simples/saludos).
• Sistema de personas — Personalice las respuestas para desarrolladores, gestores de producto u operadores de comercio minorista con diferentes comportamientos de reserva.

Integración de la API

Para usar la API de Chat, normalmente creará una sesión anónima y luego abrirá una conexión EventSource al endpoint de streaming /api/chat.

1. Crear una sesión

POST /api/session

Devuelve un token de sesión JWT necesario para la limitación de tasa y la continuidad.

2. Transmitir una conversación

POST /api/chat
Authorization: Bearer <session_token>
Content-Type: application/json

{
  "message": "How do I create a TSS in SIGN DE?",
  "persona": "developer",
  "history": []
}

La respuesta es un flujo SSE que emite payloads JSON con el prefijo data:. El flujo contendrá tanto fragmentos de texto como metadatos (como citas recuperadas o la puntuación de calidad final).

💡¿Usando React?

Si está creando una aplicación React, ofrecemos una biblioteca de interfaz de usuario completa lista para usar. Consulta la documentación de Componentes de interfaz de Chat en lugar de crear el cliente SSE desde cero.

Seguridad y límites

La API de Chat incluye estrictas salvaguardas para uso en producción:

• Limitación de tasa — 5 mensajes por minuto, 30 por hora por sesión.
• Filtrado de entrada — Detección de jailbreak y validación de longitud (máx. 3000 caracteres por mensaje).
• Filtrado de salida — Análisis de PII y verificación de fundamentación.
• Protección de presupuesto — Un límite de gasto diario configurable para todo el inquilino previene costes inesperados de LLM.

Reindexación de contenido

La base de conocimientos RAG se reindexará automáticamente todos los días a las 3:00 AM UTC mediante un CronJob de Kubernetes. Esto garantiza que la documentación nueva o actualizada, los artículos de Zendesk y las especificaciones de API se reflejen en las respuestas del chat en un plazo de 24 horas.

Panel de administración

El servicio chat-api también aloja una SPA React interna en /admin/*, protegida por Google OAuth. El panel proporciona:

• Revisión de conversaciones y etiquetado de calidad.
• Elementos de acción (tareas pendientes) para la mejora de contenido.
• Anulaciones de prompts de LLM basadas en activadores de palabres clave.
• Análisis de uso, costes y presupuesto.

Próximos pasos

Componentes de interfaz de Chat

Componentes React listos para usar para el Widget de Chat de fiskaly y la experiencia de página completa.

Código fuente del backend

Ver el código fuente de la API subyacente, incluidas las rutas Hono y el pipeline RAG.