Guía de Jerarquía, Organizaciones y Agentes
Llamalitica utiliza un modelo de jerarquía de organizaciones para facilitar la gestión de agentes a gran escala. Este sistema permite separar entornos de prueba, gestionar múltiples centros de trabajo y controlar la visibilidad de los agentes de forma centralizada.
Esta guía explica los conceptos fundamentales del modelo organizacional. Para la implementación técnica detallada, consulta la Guía de Integración.
1. Conceptos Fundamentales
Organizaciones y Sub-organizaciones
- Organización Padre: Es la entidad raíz (ej. Mi Grupo Hospitalario). Actúa como el centro de control y repositorio maestro de agentes.
- Sub-organización: Entidades que cuelgan del Padre (ej. Centro Médico Madrid, Sucursal Valencia).
- Auto-provisión: Si realizas una petición a la API con un ID de organización que no existe, Llamalitica la creará automáticamente y vinculará al usuario a dicha organización.
Gestión de Agentes
Actualmente, la creación, edición y borrado de agentes se realiza bajo petición al equipo de Llamalitica.
- Agentes Locales: Residen en una organización específica y solo son visibles en ella.
- Agentes Heredables: Se crean en la organización Padre y, al marcarlos como "heredables", quedan disponibles para todas sus sub-organizaciones.
2. Arquitectura Recomendada
Aunque Llamalitica permite crear jerarquías infinitas (una sub-organización puede tener su propia API Key y crear sus propias "hijas"), recomendamos un Modelo Horizontal.
El Modelo Horizontal (Recomendado)
Mantener todas las sub-organizaciones (centros) en un único nivel por debajo del Padre simplifica la gestión de agentes y la visibilidad de datos.
3. Estrategia de Entornos (Dev vs Prod)
Para gestionar entornos de desarrollo y producción sin necesidad de servidores distintos, utilizamos los headers de la petición:
-
Entorno Beta / Pruebas: Se utiliza la organización Padre. Para acceder, realiza la petición sin enviar el header
X-ORGANIZATION. Aquí es donde Llamalitica configurará los nuevos agentes para que vuestro equipo los valide. -
Entorno de Producción: Se utilizan las Sub-organizaciones. Cuando un agente en el Padre es validado, lo marcamos como "heredable" y aparecerá automáticamente en los centros.
Si actualizamos un agente heredable en el Padre, el cambio se refleja instantáneamente en todos los centros, facilitando correcciones y mejoras globales.
4. Integración Técnica
La autenticación y la ubicación del usuario se resuelven mediante tres cabeceras en las peticiones API:
| Header | Requerido | Descripción |
|---|---|---|
X-API-KEY | Sí | La clave de la organización (Padre o Sub-org). |
X-USER-EMAIL | Sí | Identificador del usuario final para trazabilidad y contexto. |
X-ORGANIZATION | Opcional | El ID interno de vuestra sub-organización/centro. |
Ejemplo de comportamiento
-
Petición sin
X-ORGANIZATION: El sistema te sitúa en la organización dueña de la API Key (ideal para pruebas internas y validación de agentes). -
Petición con
X-ORGANIZATION: centro-001: El sistema te sitúa en ese centro específico. El usuario verá los agentes propios del centro y los que herede del padre.
Consulta la sección de Obtención del Token de Usuario en la Guía de Integración para ver ejemplos de código en varios lenguajes.
5. API Keys y Niveles de Acceso
Cada organización (ya sea padre o hija) puede generar sus propias API Keys.
- Key de Padre: Puede operar en el padre y crear/gestionar hijos de primer nivel.
- Key de Hijo: Si se genera una clave dentro de una sub-organización, esta clave solo puede operar en esa sub-organización y crear "nietos" (un nivel más abajo).
Para la mayoría de los casos de uso, basta con utilizar la API Key del Padre y diferenciar los centros mediante el header X-ORGANIZATION, manteniendo así una estructura plana y fácil de monitorizar.