Come aggiungere e rimuovere utenti da un gruppo tramite API

Questo articolo spiega come aggiungere e rimuovere utenti da un gruppo tramite API, identificandoli tramite il loro indirizzo email, e come interpretare la risposta della piattaforma.

A cosa serve

La composizione di un gruppo può essere modificata dall'interfaccia amministrativa oppure tramite l'importazione e la sincronizzazione degli utenti. L'API aggiunge una terza via, pensata per i casi in cui l'appartenenza a un gruppo viene decisa da un sistema esterno: un onboarding che aggiunge ogni nuova persona al gruppo corrispondente, un sistema HR che riflette un cambio di reparto, oppure un processo che crea un gruppo puntuale per una campagna.

Se cerca la gestione dei gruppi dalla piattaforma, consulti Come gestire utenti e gruppi in SMARTFENSE.

Prima di iniziare

È necessaria un'applicazione registrata in Settings > Integrations > API, con l'ambito Scrivere gruppi selezionato. La procedura completa di registrazione è disponibile in Integrazione delle API in SMARTFENSE.

L'ambito Scrivere gruppi presenta attualmente un problema noto: nell'interfaccia viene visualizzato in inglese (Write groups) indipendentemente dalla lingua configurata nell'account. È già stato segnalato al team di Prodotto.

È inoltre necessario l'identificativo del gruppo su cui si opera. Può ottenerlo con l'ambito Visualizzare gruppi, che restituisce i gruppi dell'organizzazione con il relativo identificativo e nome.

Aggiungere o rimuovere utenti

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

Il corpo della richiesta indica l'azione e l'elenco degli indirizzi email:

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

• action: add per aggiungere gli utenti al gruppo, remove per rimuoverli. Una richiesta esegue solo una delle due operazioni.
• emails: fino a 200 indirizzi per richiesta. Gli indirizzi ripetuti all'interno della stessa richiesta vengono elaborati una sola volta.

Aggiungere un utente che appartiene già al gruppo, o rimuoverne uno che non ne fa parte, non genera errore: la piattaforma lascia il gruppo nello stato richiesto.

Risposta

{
  "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: gli indirizzi email su cui è stata applicata l'azione.
• skipped: gli indirizzi che non corrispondono a nessun utente dell'organizzazione. Un indirizzo scartato non interrompe la richiesta: il resto viene comunque elaborato.

Controlli sempre skipped. Un indirizzo che compare lì significa quasi sempre che l'utente non esiste ancora in SMARTFENSE, oppure che è scritto in modo diverso da come è registrato: la piattaforma lo cerca senza distinguere maiuscole e minuscole, ma non corregge differenze di scrittura.

Se l'identificativo del gruppo non corrisponde a nessun gruppo dell'organizzazione, la richiesta non viene elaborata e la piattaforma risponde di non averlo trovato.

Registrazione nell'audit

Ogni utente aggiunto o rimosso viene registrato nell'audit di amministrazione come una modifica di quell'utente, con i gruppi tra i campi modificati. La consultazione si trova in Audit > Amministrazione.

💡 Buone pratiche

• Creare gli utenti prima di assegnarli a un gruppo: l'API non crea utenti, modifica solo la composizione del gruppo.
• Inviare gli indirizzi email in lotti di massimo 200 e controllare il blocco skipped di ogni risposta prima di considerare conclusa l'operazione.
• Se uno stesso processo aggiunge e rimuove utenti, inviare due richieste distinte: una con add e una con remove.
• Registrare un'applicazione per ogni integrazione, con gli ambiti minimi necessari a quella integrazione.