Este artículo explica cómo obtener el listado de grupos de su organización y cómo crear un grupo por API, y cómo interpretar las respuestas de la plataforma.
Para qué sirve
La sección Grupos de la API de SMARTFENSE reúne estas operaciones:
| Operación | Endpoint | Uso |
|---|---|---|
| List groups | GET /api/v1/groups | Obtener todos los grupos de la organización con su identificador. |
| Create or get a group | POST /api/v1/groups | Crear un grupo o, si ya existe uno equivalente, obtenerlo. |
| Add or remove users from a group | POST /api/v1/groups/{group_id}/users | Agregar o quitar usuarios de un grupo. |
Ambas operaciones de este artículo devuelven el identificador (id) del grupo, que es el dato que necesita para operar sobre él.
Para agregar o quitar usuarios, consulte Cómo agregar y quitar usuarios de un grupo por API.
Antes de empezar
Necesita una aplicación registrada en Configuración > Integraciones > Aplicaciones registradas, con los alcances que requiere cada operación:
- Leer grupos (
read_groups): para listar grupos. - Escribir grupos (
write_groups): para crear u obtener un grupo.
El procedimiento completo de registro está en Integración de APIs en SMARTFENSE.
La API admite los flujos OAuth 2.0 authorization_code y client_credentials. Cada solicitud debe incluir el token en el encabezado Authorization.
Listar grupos
GET /api/v1/groups
Devuelve todos los grupos de la organización, incluidos los que no tienen usuarios y los inactivos.
El listado no incluye áreas funcionales, niveles jerárquicos ni grupos inteligentes.
Parámetros de consulta
- 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: 100. Valor máximo: 1.000.
Respuesta
{
"count": 123,
"next": "https://nombretenant.takesecurity.com/api/v1/groups?page=2",
"previous": null,
"results": [
{
"id": 0,
"name": "string",
"is_active": true
}
]
}- count: cantidad total de grupos.
- next / previous: enlaces a la página siguiente y anterior.
- results: los grupos de la página, con su id, su name y el indicador is_active.
Cómo recorrer todas las páginas
Los resultados se ordenan por id. Para obtener el listado completo:
- Consulte la primera página.
- Agregue los grupos de results a su listado.
- Si next tiene un valor, consulte esa URL y repita el paso 2.
- Cuando next sea nulo, el recorrido terminó.
Si pide una página que no existe, la plataforma responde 404 (
NOT_FOUND). Indica que el recorrido ya terminó.
Crear u obtener un grupo
POST /api/v1/groups
Crea un grupo o, si ya existe uno equivalente, lo devuelve sin crear otro.
Cuerpo de la solicitud
La solicitud debe enviarse con el tipo de contenido application/json:
{
"name": "campaign-2026-09"
}- name (string, obligatorio): nombre del grupo, de 1 a 150 caracteres.
El nombre admite caracteres Unicode, con estas restricciones:
- No puede comenzar con
=,+,-,@, coma ni punto y coma. - No puede contener caracteres que la plataforma modifica al guardarlo, como
<,>,&o el espacio de no separación. - No puede contener caracteres de control.
Cuándo dos nombres son equivalentes
Dos nombres son equivalentes si coinciden después de eliminar los espacios al comienzo y al final, sin distinguir mayúsculas de minúsculas.
Por ejemplo, campaign-2026-09 y Campaign-2026-09 corresponden al mismo grupo.
Respuesta
{
"id": 4832,
"name": "campaign-2026-09",
"is_active": true,
"outcome": "existing"
}El campo outcome indica qué hizo la plataforma:
- created: el grupo se creó. La respuesta es 201.
- existing: ya existía un grupo equivalente y se devuelve ese. La respuesta es 200.
Repetir la misma solicitud es seguro. La primera responde 201 con outcome: created y las siguientes, 200 con outcome: existing y el mismo id. Dos solicitudes simultáneas con nombres equivalentes también se resuelven al mismo grupo.
La respuesta devuelve el nombre tal como está guardado. Puede diferir en mayúsculas del nombre enviado.
Comportamiento de los grupos
- El grupo creado queda activo.
- El grupo se mantiene aunque después se importen usuarios desde un archivo.
- Un grupo existente se devuelve como está: si está inactivo, no se reactiva, y conserva su tipo.
Errores específicos
| Código | Significado |
|---|---|
| 400 | La solicitud no es válida. Códigos posibles: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE e INVALID_GROUP_NAME. |
| 409 | Existe más de un grupo equivalente (AMBIGUOUS_GROUP_NAME). La respuesta incluye sus identificadores en group_ids y no se crea nada. |
| 415 | El tipo de contenido no es application/json (UNSUPPORTED_MEDIA_TYPE). |
| 503 | Otra solicitud para un nombre equivalente sigue en curso (TRY_AGAIN). Vuelva a intentar después de los segundos que indica el encabezado Retry-After. |
Si recibe 409, revise los grupos listados en
group_idspara decidir con cuál operar. Mientras existan varios grupos equivalentes, la solicitud seguirá respondiendo 409.
Errores comunes a ambas operaciones
| Código | Significado |
|---|---|
| 401 | Falta el token o no es válido (AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED). |
| 403 | El token no tiene el alcance requerido (PERMISSION_DENIED), o la organización está desactivada o vencida (TENANT_INACTIVE). |
| 429 | Se excedió el límite de solicitudes permitidas. |
Límite de frecuencia
La plataforma puede limitar la cantidad de solicitudes por minuto de cada organización. El límite cuenta todas las solicitudes a la API, no solo las de grupos.
Si el límite está activo y se supera, la respuesta es 429 con el encabezado Retry-After. Espere los segundos que indica ese encabezado antes de reintentar.
💡 Mejores prácticas
- Usar Create or get a group en lugar de listar y luego crear: la operación ya evita duplicados y puede repetirse sin riesgo.
- Guardar el id que devuelve la respuesta y usarlo en las operaciones siguientes, en lugar del nombre.
- Revisar el campo is_active cuando outcome sea existing: un grupo inactivo no se reactiva por API.
- Recorrer siempre el listado completo siguiendo el enlace next, en lugar de calcular la cantidad de páginas.
- Usar un page_size alto (hasta 1.000) para reducir la cantidad de solicitudes en organizaciones con muchos grupos.
- Respetar el encabezado Retry-After ante una respuesta 429 o 503, en lugar de reintentar de inmediato.
- Registrar una aplicación por integración, con los alcances mínimos que esa integración necesita.