Administración de Integraciones

Esta sección cubre la administración de los distintos mecanismos de integración. Ver Integraciones para el detalle técnico de cada uno.

Sistemas Externos (REST / SOAP)

Los sistemas externos representan las aplicaciones con las que Kuatia se integra (ERP, CRM, servicios web, sistemas core bancarios, registro civil, etc.).

1. Integraciones → Sistemas Externos → + Crear.
2. Completar nombre, descripción, URL base y credencial OUTBOUND asociada (opcional para sistemas sin auth).
3. Guardar y agregar endpoints (operaciones).

Endpoints (operaciones REST o SOAP)

Cada endpoint define una operación concreta:

1. Abrir el sistema externo.
2. + Crear Endpoint.
3. Configurar:
   • Método: GET / POST / PUT / PATCH / DELETE.
   • Path relativo al base URL del sistema.
   • Protocolo: REST (default) o SOAP. Para SOAP outbound: wsdlUrl y soapVersion. Para SOAP inbound: el endpoint se expone públicamente en /soap/:id con WSDL generado dinámicamente.
   • Headers (key-value, sin JSON crudo).
   • Input schema (JSON Schema, con el editor estructurado — no textarea).
   • Output schema.
   • Timeout y retry policy.
4. Probar (botón) ejecuta el endpoint con datos de ejemplo y muestra respuesta + headers + duración.

Importar endpoints

• Desde cURL: pegar un comando cURL y el sistema lo parsea automáticamente.
• Desde Swagger/OpenAPI: subir un spec y crear múltiples endpoints en una sola operación.

Historial de ejecuciones

Cada llamada a un endpoint deja un registro en endpoint_executions con request/response truncados, status code, duración y error. Consultable desde la vista del endpoint (Ver historial) o globalmente desde /executions.

Credenciales

Las credenciales se cifran AES-256-GCM al guardarse. Los GET nunca devuelven el ciphertext ni el plaintext — solo hasSecret: true|false.

Tipo	Uso
NONE	Sin autenticación
BEARER	Token fijo en header Authorization
API_KEY	Key en header o query param
BASIC	Usuario/password (base64)
OAUTH2	Client credentials flow con refresh automático
JWT	JWT firmado con key propia
MTLS	Certificado cliente (en desarrollo)

Direction: OUTBOUND vs INBOUND

• OUTBOUND (default): Kuatia llama a sistemas externos.
• INBOUND: usuarios o sistemas externos acceden a recursos de Kuatia (usado por Shares para autenticar al cliente WebDAV/SFTP/Samba/S3).

Las credenciales INBOUND quedan vinculadas a un Share por shareId y se gestionan desde la pantalla del Share, no desde la pantalla de Credenciales (aunque se pueden ver allí).

UI Endpoints

Los UI Endpoints permiten embeber interfaces externas dentro de Kuatia, especialmente útil en tareas del flujo de trabajo.

Modo	Comportamiento
IFRAME	Sistema externo dentro de iframe sandbox
POPUP	Ventana popup con callback al cerrar
REDIRECT	Redirección completa, callback por URL
NEW_TAB	Nueva pestaña
INTERNAL	Componente React registrado en el frontend (internalPanels) — usado para task UI plugins

SSO entre Kuatia y el sistema externo: NONE, SAME_KEYCLOAK, TOKEN_EXCHANGE, OTT (One-Time Token), SAML.

Callbacks: MESSAGE_API, WEBHOOK, REDIRECT_URL, POLLING, WEBSOCKET.

Callback por postMessage (modo IFRAME)

Si tu sistema externo notifica el resultado de la tarea vía postMessage (ej. { type: "task_complete" }), Kuatia solo acepta el mensaje si se emite desde el mismo origin (dominio + protocolo + puerto) que la URL base configurada del sistema, y desde la propia ventana del iframe. Mensajes desde cualquier otro origin se ignoran por seguridad. Asegurate de que la página embebida corra bajo el mismo origin que el baseUrl del sistema externo.

Shares (acceso filesystem-like)

Permite acceso al árbol de archivos via protocolos WebDAV / SFTP / FTPS / Samba / S3. Ver Configuración → Shares para el procedimiento completo.

Scheduled Reports

Reportes cron-driven distribuidos por email. Ver Configuración → Reportes programados.

MIME Handlers

Extractores de metadata y visores custom por tipo de archivo:

1. Integraciones → MIME Handlers.
2. Ver los handlers builtin (PDF, Office, imágenes, etc.) y sidecars (HEIC, RAW, EPUB, etc.).
3. Para agregar uno custom: + Crear, elegir tipo (WEBHOOK / ENDPOINT / REACT_COMPONENT / IFRAME_URL), MIME que cubre, configuración específica del tipo.

Procesadores especializados

Integraciones → Procesadores especializados — catálogo de procesadores invocables desde el nodo extract_with_processor en doc-flows. Cada procesador declara:

• Nombre único por tenant.
• Endpoint (puede ser un sidecar interno o un servicio externo).
• outputSchema (JSON Schema con Ajv) — los resultados quedan validados en metadata.extracted[procName].fields.
• Opcionalmente: pageRules (cómo procesar páginas específicas), credenciales OUTBOUND si llama afuera.

LLM Router y proveedores

Configuración → IA del tenant (/admin/ai-settings) — ver Configuración → Asistente IA. El LLM Router unifica las llamadas a Ollama (local), OVH cloud, Anthropic, OpenAI, Google y Mistral, con budget tracker por tenant.

Bull Board (cola de jobs)

Administración → Colas (requiere admin.QueueMonitor) — UI embebida (Bull Board) con visibilidad de:

• Jobs en waiting, active, delayed, completed, failed.
• Detalle por job (payload, attempts, errores, stacktrace).
• Acciones manuales: reintentar, borrar, promover delayed.

Las colas incluyen document-pipeline, webhooks, notifications, task-lifecycle, bulk-operations, search-reindex, flow-timeout, scheduled-reports, rag-indexing, bootstrap-seed. Cada una con su métrica de duración y fail rate.