Integraciones

Kuatia se integra con sistemas externos via varios mecanismos complementarios:

Mecanismo	Cuándo
REST/SOAP outbound	Kuatia llama a APIs externas desde flujos o servicios
REST/SOAP inbound	Sistemas externos llaman a endpoints expuestos por Kuatia
UI Endpoints	UI externa embebida en tareas humanas (iframe, popup, redirect, internal)
Shares (WebDAV / SFTP / Samba / S3)	Acceso al árbol de archivos desde clientes filesystem-like
Scheduled Reports	Salida programada (cron) de reportes por email
LLM Router	Llamadas unificadas a modelos LLM (Ollama, OVH cloud, Anthropic, OpenAI, Google, Mistral)
MIME Handlers	Extractores y visores custom por tipo de archivo
Asistente AI con tools	El asistente puede invocar herramientas configurables
RAG	Búsqueda semántica sobre documentos del tenant

Modelo REST/SOAP

1. Credential — credenciales cifradas (AES-256-GCM). direction=OUTBOUND (Kuatia llama afuera) o INBOUND (afuera llama a Kuatia, usado por Shares).
2. External System — agrupa endpoints bajo un sistema, con URL base y credencial OUTBOUND asociada.
3. Endpoint — define una operación (método, path, headers, schemas, timeout, retry).
4. UI Endpoint — define una UI embebida que se usa en tareas humanas (no es una llamada HTTP propia).

Protocolos soportados

REST (default): endpoints configurados con method (GET/POST/PUT/PATCH/DELETE), path, headers, input/output JSON Schemas, timeout y retry.

SOAP (protocol=SOAP):

• Outbound: Kuatia llama a un servicio SOAP externo. Se configura wsdlUrl y soapVersion.
• Inbound: un sistema externo llama a Kuatia.
  • GET /soap/:id?wsdl — WSDL generado dinámicamente.
  • POST /soap/:id — recibe envelope SOAP con validación WS-Security.

Tipos de credencial

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)

Importación de endpoints

• Desde cURL: POST /endpoints/import/curl — parsea un comando cURL y crea el endpoint.
• Desde Swagger/OpenAPI: POST /endpoints/import/swagger — parsea un spec y crea múltiples endpoints en una sola operación.

UI Endpoints

Permiten embeber interfaces externas (o componentes internos) en el contexto de tareas humanas, con SSO transparente.

Modo	Comportamiento
IFRAME	Sistema externo dentro de iframe (sandbox) en la página de tarea
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)

SSO: NONE, SAME_KEYCLOAK, TOKEN_EXCHANGE, OTT (One-Time Token), SAML.

Callbacks (5 métodos): MESSAGE_API, WEBHOOK, REDIRECT_URL, POLLING, WEBSOCKET.

Shares — acceso filesystem-like

Cliente externo accede al árbol de archivos de Kuatia via WebDAV / SFTP / Samba / S3 gateway, con autenticación via Credential INBOUND.

Protocolo	Cliente típico	Notas
WebDAV	macOS Finder, Windows Explorer, rclone, davfs2	Servidor nativo en NestJS
SFTP	OpenSSH, FileZilla, Cyberduck	Vía SFTPGo
FTPS	FileZilla con TLS	Vía SFTPGo
Samba (SMB3)	Windows Explorer (mapeo de unidad de red), macOS Finder	Bridge LDAP sincronizado con Keycloak; SMB3 + cifrado obligatorio
S3	AWS CLI, SDKs, BYOD apps	Gateway nativo con autenticación SigV4, multipart upload

Mapeo de la jerarquía: tenant/account/dossier/document. El Share puede tener scope TENANT, ACCOUNT o DOSSIER.

Provisioning automático: al crear un Share, ShareProvisioningService registra los recursos externos (SFTPGo, LDAP user para Samba, claves Redis para WebDAV) async (fire-and-forget). El usuario ve provisioned: true cuando se completa.

Permisos: share.{List, Read, Create, Update, Delete, Provision}. El Delete está solo en super_admin porque al soft-deletear el share el provisioning externo se des-registra.

S3 Gateway

Gateway S3-compatible nativo con 9 operaciones (ListBuckets, ListObjectsV2, HeadObject, GetObject, PutObject, DeleteObject, InitiateMultipartUpload, UploadPart, CompleteMultipartUpload, AbortMultipartUpload). Autenticación SigV4 con credentials.s3AccessKeyId y s3SecretEncrypted. Multipart upload state en Redis (TTL 24h).

Scheduled Reports

Reportes cron-driven que se generan en la cola scheduled-reports y se distribuyen por email a múltiples destinatarios.

• Configuración: cron expression, query (con tenantId implícito), template del report, destinatarios.
• Soporta múltiples formatos: PDF, XLSX, CSV.
• Permisos: scheduled-report.{List, Read, Create, Update, Delete}.

LLM Router

Cliente unificado a modelos LLM (api/src/llm-router/). Abstracción única que soporta:

Proveedor	Notas
Ollama	Local, instancia compartida (AI_BASE_URL) — modelos open-source
OVH AI Endpoints	Cloud — modelos open-source con SLA. Modelo recomendado para el asistente: Mistral-Small-3.2-24B-Instruct-2506
Anthropic Claude	Cloud, requiere ANTHROPIC_API_KEY
OpenAI	Cloud, requiere OPENAI_API_KEY
Google Gemini	Cloud, requiere GOOGLE_API_KEY
Mistral	Cloud, requiere MISTRAL_API_KEY

Nota para self-hosting: los proveedores OpenAI-compatible que sólo implementan el endpoint Chat Completions (/v1/chat/completions) — como Ollama y OVH AI Endpoints — se consumen con ese endpoint, no con el Responses API. El asistente conversacional (/admin/ai-settings) permite elegir cualquiera de estos proveedores por tenant.

Budget tracker por tenant: cada llamada se contabiliza contra el límite configurado (llm-budget). Si se excede, se rechazan llamadas hasta el reset del período.

MIME Handlers

Extractores y visores custom por tipo de archivo. El MimeIndexerService aplica extracción tiered a 100+ MIMEs:

• Builtin (Tier 1): PDF (texto + metadata), imágenes (EXIF), Office (Word/Excel/PPT), CSV, texto plano, audio/video (metadata).
• Sidecars (Tier 2+): HEIC/HEIF, RAW (cámaras), EPUB, MOBI, LaTeX, PST, formatos comprimidos, etc. Cada sidecar corre en un container separado en docker-compose.yml.
• Custom por tenant: el admin puede agregar handlers via WEBHOOK, ENDPOINT, REACT_COMPONENT o IFRAME_URL.

Asistente AI con tools

El asistente conversacional embebido puede invocar tools configurables:

• query_documents — búsqueda semántica sobre documentos del tenant (RAG).
• Canvas / acciones de escritura (con confirmación humana).
• Tools de lectura sobre expedientes/tareas (sin efectos colaterales).
• Tools destructivos requieren confirmación explícita y el endpoint los marca con requireConfirmation: true.

Configurable por tenant en /admin/ai-settings (qué tools están habilitados, qué proveedor LLM se usa, system prompt, budget).

RAG

Búsqueda semántica sobre documentos del tenant:

1. Indexación: cada Document se chunkea, los chunks se embeddan con nomic-embed-text (Ollama), se guardan en document_chunks con pgvector.
2. Query: la pregunta se embedda, se buscan los chunks más cercanos por cosine similarity, se arman como contexto.
3. Respuesta: el LLM Router envía la query + contexto al modelo configurado.

Endpoints: POST /rag/query (REST), y el nodo de flow consultar_documentos permite usar RAG dentro de un workflow.