Cómo agregar y quitar usuarios de un grupo por API

Este artículo explica cómo agregar y quitar usuarios de un grupo por API, identificándolos por su dirección de correo electrónico, y cómo interpretar la respuesta de la plataforma.

Para qué sirve

La composición de un grupo puede modificarse desde la interfaz administrativa o mediante la importación y sincronización de usuarios. La API suma un tercer camino, pensado para los casos en que la pertenencia a un grupo la decide un sistema externo: un onboarding que agrega a cada persona nueva al grupo que le corresponde, un sistema de recursos humanos que refleja un cambio de área, o un proceso que arma un grupo puntual para una campaña.

Si busca la gestión de grupos desde la plataforma, consulte Cómo gestionar usuarios y grupos en SMARTFENSE.

Antes de empezar

Necesita una aplicación registrada en Configuración > Integraciones > API, con el alcance Escribir grupos seleccionado. El procedimiento completo de registro está en Integración de APIs en SMARTFENSE.

También necesita el identificador del grupo sobre el que va a operar. Puede obtenerlo con el alcance Leer grupos, que devuelve los grupos de la organización con su identificador y su nombre.

Agregar o quitar usuarios

POST /api/v1/groups/{id_del_grupo}/users

El cuerpo de la solicitud indica la acción y la lista de correos:

{
  "action": "add",
  "emails": ["ana.perez@ejemplo.com", "juan.gomez@ejemplo.com"]
}

• action: add para agregar los usuarios al grupo, remove para quitarlos. Una solicitud hace una sola de las dos cosas.
• emails: hasta 200 direcciones por solicitud. Los correos repetidos dentro de la misma solicitud se procesan una sola vez.

Agregar a un usuario que ya pertenece al grupo, o quitar a uno que no pertenece, no produce error: la plataforma deja el grupo en el estado que la solicitud pide.

Respuesta

{
  "action": "add",
  "group_id": 2,
  "group_name": "Comité de Seguridad",
  "processed": ["ana.perez@ejemplo.com"],
  "skipped": ["no.existe@ejemplo.com"],
  "details": { "total_processed": 1, "total_skipped": 1 }
}

• processed: los correos sobre los que se aplicó la acción.
• skipped: los correos que no corresponden a ningún usuario de la organización. Un correo salteado no interrumpe la solicitud: el resto se procesa igual.

Revise siempre skipped. Un correo que aparece ahí casi siempre significa que el usuario todavía no existe en SMARTFENSE, o que está escrito distinto al que tiene cargado: la plataforma lo busca sin distinguir mayúsculas de minúsculas, pero no corrige diferencias de escritura.

Si el identificador de grupo no corresponde a ningún grupo de la organización, la solicitud no se procesa y la plataforma responde que no lo encontró.

Registro en la auditoría

Cada usuario agregado o quitado queda registrado en la auditoría de administración como una edición de ese usuario, con los grupos entre los campos modificados. La consulta está en Auditoría > Administración.

💡 Mejores prácticas

• Crear los usuarios antes de asignarlos a un grupo: la API no da de alta usuarios, solo modifica la composición del grupo.
• Enviar los correos en lotes de hasta 200 y revisar el bloque skipped de cada respuesta antes de dar por terminada la operación.
• Si un mismo proceso agrega y quita usuarios, enviar dos solicitudes: una con add y otra con remove.
• Registrar una aplicación por integración, con los alcances mínimos que esa integración necesita.