Este artículo explica cómo una organización multitenant puede obtener por API la información de las instancias que gestiona: vigencia de la licencia, componentes contratados, usuarios contratados y activos, fecha de la última campaña lanzada, tipo de organización y sector.
Para qué sirve
La sección Gestión de instancias permite ver el inventario de organizaciones desde la plataforma. El endpoint Managed instances ofrece la misma información de forma automatizada, pensada para los casos en que un sistema externo necesita consumirla. Por ejemplo:
- Un tablero que muestra el estado de todas las instancias en un solo lugar.
- Un proceso que alerta sobre licencias próximas a vencer.
- Un control periódico que compara los usuarios activos contra los usuarios contratados.
- Un seguimiento de instancias que no lanzaron campañas recientemente.
Si busca la gestión de instancias desde la plataforma, consulte Multitenant.
Antes de empezar
- Verifique que su organización gestione instancias. El endpoint solo está disponible para organizaciones multitenant que gestionan instancias.
- Registre una aplicación en Configuración > Integraciones > Aplicaciones registradas con el alcance read_managed_instances seleccionado. El procedimiento completo está en Integración de APIs en SMARTFENSE.
- Obtenga un access token con el flujo Authorization code o Client Credentials. Ambos están soportados por este endpoint.
Nota: el alcance read_managed_instances solo se ofrece a las organizaciones que gestionan instancias. Si no lo ve al registrar la aplicación, su organización no tiene instancias gestionadas asociadas.
Consultar las instancias
GET /api/v1/organization/managed-instances
La ruta es relativa a la URL de su instancia. Incluya el token en el encabezado Authorization de la solicitud:
curl -X GET "https://nombretenant.takesecurity.com/api/v1/organization/managed-instances" \ -H "Authorization: Bearer <access_token>"
Donde nombretenant corresponde al nombre de su instancia.
La respuesta incluye las instancias gestionadas en cualquier nivel de la jerarquía, tanto activas como desactivadas.
Parámetros de consulta
Todos los parámetros son opcionales y pueden combinarse.
| Parámetro | Tipo | Descripción |
|---|---|---|
| name | string | Devuelve solo las instancias cuyo nombre contiene este texto. No distingue mayúsculas de minúsculas. |
| page | integer | Número de la página a consultar. Valor por defecto: 1. |
| page_size | integer | Cantidad de registros por página. Valor por defecto: 50. Valor máximo: 50. |
| validity_end_date_before | string (fecha) | Devuelve solo las instancias cuya vigencia termina en esta fecha o antes. Formato: YYYY-MM-DD. |
Ejemplo: instancias cuya licencia vence hasta el 31 de diciembre de 2026.
GET /api/v1/organization/managed-instances?validity_end_date_before=2026-12-31
Respuesta
La respuesta es paginada y se entrega en formato application/json:
{
"count": 123,
"next": "https://nombretenant.takesecurity.com/api/.../?page=4",
"previous": "https://nombretenant.takesecurity.com/api/.../?page=2",
"results": [
{
"name": "string",
"url": "http://example.com",
"active": true,
"validity_start_date": "2019-08-24",
"validity_end_date": "2019-08-24",
"contracted_users": 0,
"active_users": 0,
"last_campaign_launched_at": "2019-08-24T14:15:22Z",
"company_type": { ... },
"sector": { ... },
"components": [ ... ]
}
]
}- count: cantidad total de instancias que cumplen los filtros.
- next y previous: URL de la página siguiente y anterior. Utilícelas para recorrer todos los resultados.
- results: listado de instancias de la página consultada.
Campos de cada instancia
| Campo | Tipo | Descripción |
|---|---|---|
| name | string | Nombre de la instancia. |
| url | string (URI) | Dirección con la que se accede a la instancia. |
| active | boolean | Indica si la instancia está activa. |
| validity_start_date | fecha o null | Fecha de inicio de vigencia de la licencia. Es nula si no fue cargada. |
| validity_end_date | fecha | Fecha de fin de vigencia de la licencia. |
| contracted_users | integer | Cantidad de usuarios contratados. |
| active_users | integer | Cantidad de usuarios activos en este momento. Se cuentan igual que en la información de licencia, para compararlos con los contratados. |
| last_campaign_launched_at | fecha y hora o null | Fecha y hora de inicio de la última campaña lanzada, de cualquier componente. Es nula si la instancia nunca lanzó una campaña. |
| company_type | objeto | Tipo de organización. |
| sector | objeto o null | Sector de la organización. Es nulo si no fue cargado. |
| components | array de objetos | Componentes contratados. |
Importante: company_type, sector y cada elemento de components se informan con un código estable y su nombre en el idioma de la organización. Utilice el código para automatizar procesos y el nombre solo para mostrar la información.
Cómo se calcula la última campaña lanzada
El campo last_campaign_launched_at tiene en cuenta estas reglas:
- No cuenta las campañas de prueba.
- No cuenta las campañas programadas para más adelante.
- Un itinerario cuenta como una sola campaña.
- Informa la fecha en que la campaña comenzó, no la del último correo enviado.
Códigos de respuesta
| Código | Significado |
|---|---|
| 200 | Solicitud exitosa. |
| 400 | Alguno de los filtros no tiene un valor válido. |
| 401 | No se proveyó un token de acceso, o el token es inválido o está vencido. |
| 403 | El token no posee el alcance requerido, o la organización no tiene instancias gestionadas disponibles para consultar. |
| 429 | Se excedió el límite de peticiones permitidas. Reintente después del tiempo indicado en el header Retry-After. |
Nota: si recibe un 400 al filtrar por fecha, verifique que validity_end_date_before respete el formato YYYY-MM-DD.
💡 Mejores prácticas
- Registre una aplicación exclusiva para esta integración, con el alcance read_managed_instances como único permiso si no necesita otros.
- Recorra todas las páginas siguiendo el campo next hasta que sea nulo. El máximo por página es de 50 instancias.
- Use validity_end_date_before para detectar con anticipación las licencias próximas a vencer.
- Compare active_users con contracted_users para identificar instancias cerca del límite de su licencia.
- Revise last_campaign_launched_at para detectar instancias sin actividad reciente.
- Use el código de tipo de organización, sector y componentes en sus procesos automáticos. El nombre puede cambiar según el idioma de cada organización.
- Ante un 429, respete el tiempo indicado en Retry-After antes de reintentar.