Questo articolo spiega come ottenere l'elenco dei gruppi della sua organizzazione, come creare un gruppo tramite API e come interpretare le risposte della piattaforma.
A cosa serve
La sezione Grupos (Gruppi) dell'API di SMARTFENSE comprende queste operazioni:
| Operazione | Endpoint | Utilizzo |
|---|---|---|
| List groups | GET /api/v1/groups | Ottenere tutti i gruppi dell'organizzazione con il relativo identificativo. |
| Create or get a group | POST /api/v1/groups | Creare un gruppo o, se ne esiste già uno equivalente, ottenerlo. |
| Add or remove users from a group | POST /api/v1/groups/{group_id}/users | Aggiungere o rimuovere utenti da un gruppo. |
Entrambe le operazioni descritte in questo articolo restituiscono l'identificativo (id) del gruppo, che è il dato necessario per operare su di esso.
Per aggiungere o rimuovere utenti, consulti Cómo agregar y quitar usuarios de un grupo por API.
Prima di iniziare
È necessaria un'applicazione registrata in Configuración > Integraciones > Aplicaciones registradas, con gli ambiti (scope) richiesti da ciascuna operazione:
- Leer grupos (
read_groups): per elencare i gruppi. - Escribir grupos (
write_groups): per creare o ottenere un gruppo.
La procedura completa di registrazione è descritta in Integración de APIs en SMARTFENSE.
L'API supporta i flussi OAuth 2.0 authorization_code e client_credentials. Ogni richiesta deve includere il token nell'intestazione Authorization.
Elencare i gruppi
GET /api/v1/groups
Restituisce tutti i gruppi dell'organizzazione, inclusi quelli senza utenti e quelli inattivi.
L'elenco non include áreas funcionales (aree funzionali), niveles jerárquicos (livelli gerarchici) né grupos inteligentes (gruppi intelligenti).
Parametri di query
- page (integer): numero della pagina da consultare. Valore predefinito: 1.
- page_size (integer): numero di record per pagina. Valore predefinito: 100. Valore massimo: 1.000.
Risposta
{
"count": 123,
"next": "https://nometenant.takesecurity.com/api/v1/groups?page=2",
"previous": null,
"results": [
{
"id": 0,
"name": "string",
"is_active": true
}
]
}- count: numero totale di gruppi.
- next / previous: link alla pagina successiva e precedente.
- results: i gruppi della pagina, con id, name e l'indicatore is_active.
Come scorrere tutte le pagine
I risultati sono ordinati per id. Per ottenere l'elenco completo:
- Consulti la prima pagina.
- Aggiunga i gruppi di results al suo elenco.
- Se next contiene un valore, consulti quell'URL e ripeta il passaggio 2.
- Quando next è nullo, la consultazione è terminata.
Se richiede una pagina che non esiste, la piattaforma risponde 404 (
NOT_FOUND). Significa che la consultazione è già terminata.
Creare o ottenere un gruppo
POST /api/v1/groups
Crea un gruppo o, se ne esiste già uno equivalente, lo restituisce senza crearne un altro.
Corpo della richiesta
La richiesta deve essere inviata con il tipo di contenuto application/json:
{
"name": "campaign-2026-09"
}- name (string, obbligatorio): nome del gruppo, da 1 a 150 caratteri.
Il nome accetta caratteri Unicode, con queste restrizioni:
- Non può iniziare con
=,+,-,@, virgola né punto e virgola. - Non può contenere caratteri che la piattaforma modifica al salvataggio, come
<,>,&o lo spazio unificatore. - Non può contenere caratteri di controllo.
Quando due nomi sono equivalenti
Due nomi sono equivalenti se coincidono dopo aver eliminato gli spazi all'inizio e alla fine, senza distinguere tra maiuscole e minuscole.
Ad esempio, campaign-2026-09 e Campaign-2026-09 corrispondono allo stesso gruppo.
Risposta
{
"id": 4832,
"name": "campaign-2026-09",
"is_active": true,
"outcome": "existing"
}Il campo outcome indica cosa ha fatto la piattaforma:
- created: il gruppo è stato creato. La risposta è 201.
- existing: esisteva già un gruppo equivalente e viene restituito quello. La risposta è 200.
Ripetere la stessa richiesta è sicuro. La prima risponde 201 con outcome: created e le successive 200 con outcome: existing e lo stesso id. Anche due richieste simultanee con nomi equivalenti vengono risolte nello stesso gruppo.
La risposta restituisce il nome così come è salvato. Può differire per maiuscole e minuscole dal nome inviato.
Comportamento dei gruppi
- Il gruppo creato risulta attivo.
- Il gruppo viene mantenuto anche se in seguito vengono importati utenti da un file.
- Un gruppo esistente viene restituito così com'è: se è inattivo, non viene riattivato, e mantiene il suo tipo.
Errori specifici
| Codice | Significato |
|---|---|
| 400 | La richiesta non è valida. Codici possibili: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE e INVALID_GROUP_NAME. |
| 409 | Esiste più di un gruppo equivalente (AMBIGUOUS_GROUP_NAME). La risposta include i relativi identificativi in group_ids e non viene creato nulla. |
| 415 | Il tipo di contenuto non è application/json (UNSUPPORTED_MEDIA_TYPE). |
| 503 | Un'altra richiesta per un nome equivalente è ancora in corso (TRY_AGAIN). Riprovi dopo i secondi indicati nell'intestazione Retry-After. |
Se riceve 409, verifichi i gruppi elencati in
group_idsper decidere su quale operare. Finché esistono più gruppi equivalenti, la richiesta continuerà a rispondere 409.
Errori comuni a entrambe le operazioni
| Codice | Significato |
|---|---|
| 401 | Il token è assente o non è valido (AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED). |
| 403 | Il token non dispone dell'ambito richiesto (PERMISSION_DENIED), oppure l'organizzazione è disattivata o scaduta (TENANT_INACTIVE). |
| 429 | È stato superato il limite di richieste consentite. |
Limite di frequenza
La piattaforma può limitare il numero di richieste al minuto di ciascuna organizzazione. Il limite conteggia tutte le richieste all'API, non solo quelle relative ai gruppi.
Se il limite è attivo e viene superato, la risposta è 429 con l'intestazione Retry-After. Attenda i secondi indicati in tale intestazione prima di riprovare.
💡 Buone pratiche
- Usare Create or get a group invece di elencare e poi creare: l'operazione evita già i duplicati e può essere ripetuta senza rischi.
- Salvare l'id restituito nella risposta e usarlo nelle operazioni successive, invece del nome.
- Controllare il campo is_active quando outcome è existing: un gruppo inattivo non viene riattivato tramite API.
- Scorrere sempre l'elenco completo seguendo il link next, invece di calcolare il numero di pagine.
- Usare un page_size elevato (fino a 1.000) per ridurre il numero di richieste nelle organizzazioni con molti gruppi.
- Rispettare l'intestazione Retry-After in caso di risposta 429 o 503, invece di riprovare immediatamente.
- Registrare un'applicazione per ogni integrazione, con gli ambiti minimi necessari a tale integrazione.