Saltar a contenido

Integraciones#

Empowerment Center ofrece varias formas de que otros programas usen sus datos sin que una persona abra la aplicación: una API para consultar, un servidor para asistentes de IA, la incrustación de documentos en otras aplicaciones y el paso del metadata entre entornos. Esta parte explica qué hace cada una, qué hay que configurar y cómo se protege.

Antes de empezar#

Todas las integraciones comparten tres principios:

  • Siempre actúan en nombre de un usuario real. No hay cuentas técnicas ni invitados anónimos. El programa entra con una credencial o un token que nombra a un usuario de ECenter, y ve exactamente lo que ese usuario vería en la aplicación: los mismos universos (filas) y la misma seguridad por columnas.
  • Los privilegios se leen en cada petición. Si a un usuario se le quita un rol o se le inhabilita, la integración lo nota en la petición siguiente.
  • No hay SQL. Ninguna integración permite escribir SQL contra la base de datos del cliente. Se pide una consulta de cubo con los identificadores del catálogo y ECenter la calcula con el mismo motor que la aplicación.

Necesita una licencia válida: sin ella, todas las superficies de integración responden 403 LICENSE_INVALID, sin excepciones.

Qué integración usar#

Necesidad Integración Quién la configura Credencial
Un programa (un informe en Python, una hoja de cálculo, un proceso nocturno) que lee cifras API de consulta Cada usuario, para sí mismo Personal, ámbito API de consulta
Un asistente de IA (Claude, otros clientes MCP) que responde preguntas sobre los datos Servidor MCP Administración activa el servidor; cada usuario crea su credencial o entra con la cuenta de la empresa Personal, ámbito Asistentes de IA (MCP), u OAuth
Mostrar documentos o plantillas del portal dentro de una intranet, un ERP o un portal de clientes Incrustación Administración del sistema De la aplicación anfitriona, ámbito Incrustación
Llevar el metadata de desarrollo a producción desde un script o la integración continua Intercambio del metadata sin sesión Administración del sistema, a nombre de quien administra el metadata Ámbito Intercambio del metadata
Dar de alta y de baja usuarios desde el proveedor de identidad Aprovisionamiento por SCIM (véase el capítulo de seguridad) Administración de usuarios Ámbito Aprovisionamiento de usuarios (SCIM)

Todas, salvo el OAuth del servidor MCP, usan una credencial de servicio: un secreto que el programa envía en la cabecera Authorization: Bearer. Las credenciales se explican en Credenciales de servicio.

Las puertas de entrada Cuatro clientes entran por cuatro puertas de Empowerment Center, cada uno con su credencial: un programa por la API de consulta, un asistente de IA por el servidor MCP, una aplicación anfitriona por la incrustación y la integración continua por el intercambio del metadata; todas actúan en nombre de un usuario real, con su seguridad, contra la BD del cliente. EMPOWERMENT CENTER token OAuth Credencial API de consulta Credencial MCP u OAuth Credencial Incrustación + token de 5 min Credencial Intercambio del metadata en nombre de un usuario real consulta de cubo, sin SQL Proveedor de identidad OAuth del MCP y SCIM Programa o script Asistente de IA Aplicación anfitriona servidor e iframe Integración continua API de consulta /api/query/v1 Servidor MCP /api/mcp Incrustación /api/embed/v1 /embed/{clave} Intercambio del metadata /api/metadata-exchange/v1 Seguridad del usuario universos y columnas BD del cliente Todas las puertas exigen licencia válida y dejan rastro en la auditoría.
Las puertas de entrada Cuatro clientes entran por cuatro puertas de Empowerment Center, cada uno con su credencial: un programa por la API de consulta, un asistente de IA por el servidor MCP, una aplicación anfitriona por la incrustación y la integración continua por el intercambio del metadata; todas actúan en nombre de un usuario real, con su seguridad, contra la BD del cliente. EMPOWERMENT CENTER token OAuth Credencial API de consulta Credencial MCP u OAuth Credencial Incrustación + token de 5 min Credencial Intercambio del metadata en nombre de un usuario real consulta de cubo, sin SQL Proveedor de identidad OAuth del MCP y SCIM Programa o script Asistente de IA Aplicación anfitriona servidor e iframe Integración continua API de consulta /api/query/v1 Servidor MCP /api/mcp Incrustación /api/embed/v1 /embed/{clave} Intercambio del metadata /api/metadata-exchange/v1 Seguridad del usuario universos y columnas BD del cliente Todas las puertas exigen licencia válida y dejan rastro en la auditoría.
Las puertas de entrada Ver a tamaño completo Ver a tamaño completo

Rutas de cada integración#

Cada integración tiene su propia ruta y solo acepta su tipo de credencial. La cookie de sesión de la aplicación no sirve en ninguna de ellas, y sus respuestas nunca crean una sesión.

Ruta Integración Qué acepta
/api/query/v1/** API de consulta Credencial de ámbito API de consulta
/api/mcp Servidor MCP Credencial de ámbito MCP o un token OAuth del proveedor de identidad
/api/embed/v1/tokens y /api/embed/v1/host/** Incrustación: el servidor anfitrión Credencial de ámbito Incrustación
/api/embed/v1/** (el resto) Incrustación: el iframe La sesión incrustada que abre el token
/embed/{clave} y /embed/sdk/v1/ecenter-embed.js La página del iframe y el SDK Nada (no dan datos)
/api/metadata-exchange/v1/** Intercambio del metadata Credencial de ámbito Intercambio del metadata
/.well-known/oauth-protected-resource/api/mcp Metadatos OAuth del servidor MCP Nada (público, sin datos)

El proxy inverso tiene que mandar al backend /api/, /embed/ y /.well-known/oauth-protected-resource/. La imagen del frontal ya lo hace; si usa un proxy propio, revise la instalación.

Errores comunes de todas las superficies#

Las respuestas de error van en formato ProblemDetail (JSON) con un campo code, salvo las de SCIM, que van en el formato de errores de SCIM:

HTTP code Qué significa
401 CREDENTIAL_REQUIRED La petición no lleva la cabecera Authorization: Bearer.
401 INVALID_CREDENTIAL La credencial no vale: no existe, ha caducado, está revocada, es de otro ámbito o su titular está inhabilitado. La respuesta no dice cuál de estos motivos es; la auditoría sí.
403 NOT_ALLOWED El titular no tiene el privilegio que pide la ruta, o la credencial no incluye esa conexión.
403 LICENSE_INVALID La instalación no tiene una licencia válida.
403 INSUFFICIENT_SCOPE Solo en el servidor MCP con OAuth: al token le falta el ámbito ecenter.mcp.
503 IDENTITY_PROVIDER_UNAVAILABLE Solo en el servidor MCP con OAuth: no se ha podido comprobar el token con el proveedor de identidad. Lleva Retry-After.
429 RATE_LIMITED Demasiadas peticiones por minuto. Espere lo que indique la cabecera Retry-After.

Varias instancias del backend#

Las consultas de la API y del MCP, y las sesiones incrustadas, se calculan en la memoria de la instancia que las atiende. Con varias instancias, el balanceador tiene que mandar las peticiones de un mismo cliente a la misma instancia: por la cabecera X-ECenter-Embed-Session (incrustación) y por la cabecera Authorization (API y MCP). La configuración de ejemplo para nginx está en el capítulo de instalación.

Los límites por minuto y de consultas a la vez también son por instancia.

Auditoría#

Todo lo que hacen las integraciones queda en la auditoría con su canal (API, MCP, EMBED) y una referencia de la credencial o de la sesión (cred:<id>, oauth:<cliente>, emb:<sesión>), nunca el secreto. El primer uso de cada credencial en cada hora se anota como un acceso, y los rechazos (credencial que no vale, origen no permitido…) también. Véase el capítulo de auditoría.

En esta parte#