API Reference

Referencia manual

La referencia es manual y se actualiza con cada cambio (regla: internal/docs-playbook.md). En un release futuro se va a generar a partir del spec OpenAPI con docusaurus-plugin-openapi-docs.

Convenciones generales

• Base URL: definida en KUATIA_API_BASE_URL (ej. http://localhost:3000 en dev).
• Autenticación: Bearer JWT en header Authorization: Bearer <token>. El JWT lo emite Keycloak (realm por tenant).
• Paginación: _start, _end, _sort, _order como query params; respuesta incluye header x-total-count.
• Content-Type: application/json (excepto uploads de archivos y SOAP).
• Tenant scoping: el tenantId viaja en el JWT y se aplica automáticamente a todos los queries — no se pasa en URL ni body.
• Permisos: cada endpoint protegido declara @RequirePermission('<modulo>.<Accion>'). Sin el permiso: 403.

Endpoints públicos

Método	Ruta	Descripción
GET	/auth/realm?user=<email>	Resuelve el realm Keycloak por email del usuario (paso 1 del login)
GET	/auth/validate-ott?token=<ott>	Valida un One-Time Token (Redis TTL 5min) — usado por UI Endpoints con ssoType=OTT
GET	/	Saludo raíz
GET	/health	Liveness + readiness. 200 si los 3 requeridos (Postgres / Mongo / Redis) están OK; 503 en degraded
GET	/soap/:id?wsdl	WSDL generado dinámicamente para endpoint SOAP inbound
POST	/soap/:id	Recibe envelope SOAP, valida WS-Security
POST	/flow/webhook/:token	Reanuda flujo pausado en nodo esperar_webhook
GET	/flow/webhook/:token	Estado de un FlowWait (WAITING / RESOLVED / EXPIRED)

Autenticados (sin permiso específico)

Método	Ruta	Descripción
GET	/auth/me	Perfil del usuario + roles + permisos efectivos

CRUD estándar

Todos siguen _start/_end/_sort/_order y devuelven x-total-count. Permisos por módulo (List/Read/Create/Update/Delete).

Recurso	Módulo de permiso	Notas
/accounts	account.*	Search ?q= con Typesense, relation accountType
/account-types	account.*	Bootstrap: 3 tipos default
/dossiers	dossier.*	MongoDB, dossierType como select, jerarquía con parentId + path[]
/dossier-types	dossiertype.*	PostgreSQL + flowDefinition JSONB, bootstrap "general"
/documents	document.*	MongoDB, _id=SHA-256 (content-addressed), deduplicación nativa
/document-types	documenttype.*	PostgreSQL + flowDefinition JSONB (Layer 2), bootstrap "generic"
/tasks	task.*	Filtra por assignedTo. Reference TASK-YYYY-NNNN auto-generada. Enriquece con dossierState, assignee {displayName, initials}, accounts[]. Scope ?scope=mine|team|all|due|overdue
/tasks/counts	task.List	Conteos por bin para la bandeja: {all, mine, team, due, overdue}
/tasks/:id/activity	task.Read	Timeline: GET lista entries, POST agrega comentario, DELETE borra propio comentario
/inbox/saved-views	inbox.SavedView.*	CRUD de vistas guardadas per-user. PG inbox_saved_views
/tenants	tenant.*	Sin DELETE
/users	user.*	Sin CREATE (auto-provision al login)
/credentials	credential.*	Secrets nunca en GET; field hasSecret: boolean en su lugar
/external-systems	externalsystem.*	Relation credential
/endpoints	endpoint.*	Relation system
/ui-endpoints	uiendpoint.*	5 modos: IFRAME / POPUP / REDIRECT / NEW_TAB / INTERNAL
/mime-handlers	mimehandler.*	Extractores y visores custom por tenant
/shares	share.*	WebDAV / SFTP / FTPS / SMB / S3. DELETE solo super_admin
/scheduled-reports	scheduledreport.*	Reportes cron-driven
/dashboards	dashboard.*	Embebe Grafana con SSO; GET /:name/iframe entrega URL firmada
/specialized-processors	specializedprocessor.*	Catálogo de procesadores invocables desde extract_with_processor
/parameter-definitions	parameter.*	Definición de parámetros del sistema

Roles y permisos

Método	Ruta	Permiso	Descripción
POST	/roles/:id/permissions	role.Assign	Asignar permiso a rol
DELETE	/roles/:id/permissions/:permId	role.Assign	Quitar permiso
POST	/roles/:id/users	role.Assign	Asignar usuario a rol
DELETE	/roles/:id/users/:userId	role.Assign	Quitar usuario

Parámetros

Método	Ruta	Permiso	Descripción
GET	/parameters	parameter.List	Resueltos del tenant (con caché Redis 3600s)
GET	/parameters/system	parameter.SystemList	Globales (solo super_admin)
PUT	/parameters/:key	parameter.Update	Setear valor tenant
PUT	/parameters/system/:key	parameter.SystemUpdate	Setear valor global
DELETE	/parameters/:key	parameter.Update	Reset al default

Integraciones

Método	Ruta	Permiso	Descripción
POST	/credentials/:id/test	credential.Test	Probar credencial (auth contra el endpoint configurado)
POST	/endpoints/:id/test	endpoint.Test	Ejecutar test manual del endpoint
GET	/endpoints/:id/executions	endpoint.Read	Historial de ejecuciones del endpoint
GET	/executions	endpoint.Read	Historial global de ejecuciones
GET	/executions/:id	endpoint.Read	Detalle de ejecución
POST	/endpoints/import/curl	endpoint.Import	Importar endpoint desde un comando cURL
POST	/endpoints/import/swagger	endpoint.Import	Importar múltiples endpoints desde un OpenAPI spec

Asistente AI y RAG

Método	Ruta	Permiso	Descripción
POST	/ai/chat	ai.Use	Chat conversacional con LLM (SSE streaming). Body: {message, conversationId?, tools?}
GET	/ai/conversations	ai.ViewHistory	Listar conversaciones del usuario en el tenant
GET	/ai/conversations/:id	ai.ViewHistory	Detalle de conversación con mensajes
GET	/ai/models	ai.Use	Modelos habilitados para el tenant
GET	/ai/settings	ai.Settings	Settings del tenant (providers, modelo default, system prompt, tools)
PUT	/ai/settings	ai.Settings	Actualizar settings AI del tenant
POST	/rag/query	rag.Query	Vector search + síntesis con LLM. Body: {query, scopes?}
POST	/rag/reindex	rag.Reindex	Encola reindex de chunks (cola rag-indexing)

Doc-flow (Layer 2)

Sobre /documents/:id:

Método	Ruta	Permiso	Descripción
POST	/flow/start	document.Update	Arrancar walk. Body opcional {flowDefinitionOverride}
GET	/flow	document.Read	Walk activo o último terminado (history truncado a 20)
POST	/flow/tasks/:taskId/complete	document.Review	Body {outcome?: 'approved'|'rejected', editedFields?: object}
POST	/flow/tasks/:taskId/assistant/message	document.AssistantReview	Enviar mensaje al asistente IA, devuelve respuesta
POST	/flow/tasks/:taskId/assistant/attribute	document.AssistantReview	Agregar atributo libre al doc
DELETE	/flow/tasks/:taskId/assistant/attribute/:key	document.AssistantReview	Rollback de atributo agregado en este task

ACL fino

Método	Ruta	Permiso	Descripción
GET	/acl/rules	acl.View	Listar reglas (filtros subjectType, resourceType)
GET	/acl/rules/:id	acl.View	Detalle
POST	/acl/rules	acl.Manage	Crear regla
PATCH	/acl/rules/:id	acl.Manage	Modificar
DELETE	/acl/rules/:id	acl.Manage	Borrar
GET	/acl/audit	acl.View	Audit chain (hash encadenado SHA-256 + HMAC)
GET	/acl/denials	acl.View	Log de denegaciones

Shares y filesystem gateway

Método	Ruta	Permiso	Descripción
POST	/shares/:id/provision	share.Provision	Refrescar provisioning (SFTPGo / rclone / samba)
GET	/shares/:id/connection-info	share.Read	Cómo conectarse: hosts, puertos, paths, UNC por protocolo habilitado
POST	/fs/sftp/event	HMAC interno	Webhook SFTPGo (upload/delete/rename/mkdir)
POST	/fs/samba/event	HMAC interno	Webhook samba post-write hook

S3 Gateway

9 operaciones S3-compat bajo /s3/* con auth SigV4. Ver integraciones.

Dashboards embebidos

Método	Ruta	Permiso	Descripción
GET	/dashboards/my	(cualquier dashboard.View*)	Dashboards habilitados para los que el usuario tiene requiredPermission. No expone url ni el permiso
GET	/dashboards/:name/iframe	(verificado en requiredPermission del dashboard)	Devuelve {src, sandbox} para el <DashboardLoader>
ALL	/observability/grafana/*path	dashboard.*	Reverse proxy autenticado a Grafana con header X-WEBAUTH-USER (auth-proxy SSO)

Operaciones administrativas

Método	Ruta	Permiso	Descripción
GET	/admin/queues	admin.QueueMonitor	Bull Board UI embebido
GET	/admin/queues/metrics	admin.QueueMonitor	Métricas agregadas (depth, throughput, fail rate)
POST	/admin/reset-database	admin.ResetDatabase	Destructivo: borra datos del tenant. Body {includeConfig?} también borra integraciones
POST	/admin/tenants/:id/reseed	admin.TenantReseed	Encola re-seed por tenant en cola bootstrap-seed

Errores estándar

Todos los errores siguen el formato NestJS:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Códigos comunes:

• 400 — body inválido (validación Class Validator).
• 401 — sin JWT o expirado.
• 403 — sin permiso requerido por el endpoint.
• 404 — recurso no existe (o filtrado por tenant).
• 409 — conflicto (ej. unique violation).
• 429 — rate limit.
• 503 — /health degraded.