Questo articolo spiega come creare e aggiornare fino a 1.000 utenti per richiesta tramite l'API di SMARTFENSE e come consultare il risultato di ogni operazione.
A cosa serve
Gli utenti possono essere caricati dall'interfaccia amministrativa o tramite le diverse fonti di importazione e sincronizzazione. L'API di creazione e aggiornamento in blocco aggiunge un percorso pensato per i casi in cui è un sistema esterno a decidere chi deve esistere nella piattaforma: un sistema di risorse umane, un processo di onboarding o un'integrazione propria dell'organizzazione o del partner.
L'operazione funziona in due passaggi:
-
Inviare gli utenti con
POST /api/v1/users/bulk-upsert. La piattaforma convalida la richiesta e la mette in coda. -
Consultare il risultato con
GET /api/v1/users/bulk-upsert/{request_id}, utilizzando l'identificativo restituito nel passaggio precedente.
Prima di iniziare
È necessaria un'applicazione registrata in Impostazioni > Integrazioni > Applicazioni registrate. La procedura completa di registrazione è descritta in Integrazione delle API in SMARTFENSE.
Selezioni i seguenti ambiti (scope) in base a ciò che serve all'integrazione:
| Ambito | A cosa serve |
|---|---|
write_users |
Obbligatorio. Creare e aggiornare utenti e consultare lo stato dell'operazione. |
read_users |
Consultare l'elenco degli utenti. |
read_groups |
Elencare i gruppi esistenti. |
write_groups |
Creare gruppi con POST /api/v1/groups. |
L'API supporta i flussi OAuth 2.0 Authorization code e Client Credentials. Per le integrazioni server-to-server si consiglia Client Credentials.
Tutte le richieste vengono effettuate sull'URL base
https://tenant.takesecurity.com/. Sostituiscatenantcon il sottodominio della sua istanza di SMARTFENSE.
Passaggio 1 — Inviare gli utenti
POST /api/v1/users/bulk-upsert Content-Type: application/json Authorization: Bearer <token>
Il corpo contiene l'elenco users, con un numero di record compreso tra 1 e 1.000:
{
"users": [
{
"username": "ana.perez",
"first_name": "Ana",
"last_name": "Pérez",
"email": "ana.perez@esempio.com",
"group": "Finanza",
"is_active": true,
"language_code": "it-it"
},
{
"username": "juan.gomez",
"group": "Comitato di Sicurezza"
}
]
}Nell'esempio, il primo record crea un nuovo utente e il secondo aggiunge un gruppo a un utente esistente.
Creazione o aggiornamento
Ogni utente è identificato dal suo username:
- Se lo username non esiste, la piattaforma crea l'utente. Il record deve includere tutti i campi.
- Se lo username esiste, vengono modificati solo i campi inviati. Un campo omesso mantiene il suo valore attuale.
Un record che include solo lo
usernameviene rifiutato conNO_UPDATE_FIELDS, perché non indica nulla da modificare.
Campi del record
| Campo | Tipo | Descrizione |
|---|---|---|
username |
string, fino a 150 caratteri | Sempre obbligatorio. Identità dell'utente. |
first_name |
string, fino a 150 caratteri | Nome. Obbligatorio in creazione. |
last_name |
string, fino a 150 caratteri | Cognome. Obbligatorio in creazione. |
email |
string, fino a 254 caratteri | Email. Obbligatoria in creazione. |
group |
string, fino a 150 caratteri | Nome di un gruppo esistente. Obbligatorio in creazione. |
is_active |
boolean | Stato dell'utente. Obbligatorio in creazione. |
language_code |
string | Lingua dell'utente. Obbligatoria in creazione. |
username
- Vengono rimossi gli spazi iniziali e finali e il valore viene convertito in minuscolo. La ricerca non distingue tra maiuscole e minuscole.
- Non può contenere spazi né caratteri di controllo, iniziare con
=,+,-,@, virgola o punto e virgola, né contenere<,>o&. - Per creare un utente, accetta solo lettere, numeri e i caratteri
@ . + - _.
Questa operazione non modifica mai lo username di un account esistente, salvo per convertirlo in minuscolo.
first_name e last_name
Non accettano caratteri di controllo, i prefissi =, +, -, @, virgola o punto e virgola, né i caratteri <, >, & o lo spazio indivisibile.
- Viene salvata in minuscolo.
- Non può appartenere a un altro utente della piattaforma né ripetersi tra due utenti della stessa richiesta. In entrambi i casi il record fallisce con
USER_CONFLICT. -
Non è l'identità dell'utente. L'identità è lo
username.
group
- L'assegnazione è additiva: viene aggiunto il gruppo indicato e vengono mantenuti i gruppi che l'utente aveva già.
- Il gruppo non viene creato da questo endpoint. Se non esiste, il record fallisce con
GROUP_NOT_FOUND. Lo crei prima conPOST /api/v1/groups.
Per rimuovere utenti da un gruppo, consulti Come aggiungere e rimuovere utenti da un gruppo tramite API.
is_active
Deve essere un booleano JSON (true o false), non un testo.
language_code
Deve essere uno di questi codici, senza distinzione tra maiuscole e minuscole:
ar-sa, id-id, ms-my, bg-bg, ca-ca, cs-cz, da-dk, de-de, et-ee, el-gr, en-au, en-nz, en-gb, en-us, es-ar, es-es, es-eu, es-me, fr-ca, fr-fr, gl-gl, ko-kr, hi-in, hr-hr, it-it, he-il, sw-ke, lv-lv, lt-lt, hu-hu, nl-nl, ja-jp, nb-no, pt-br, pl-pl, pt-pt, ro-ro, ru-ru, sq-al, sk-sk, sl-si, sr-latn, fi-fi, sv-se, th-th, vi-vn, tr-tr, uk-ua, zh-cn, zh-hk, zh-tw.
Se l'utente ha cambiato la propria lingua dalla piattaforma, la lingua inviata non viene applicata e il record non la segnala come modifica.
Valori non ammessi
- I valori
null, vuoti o composti solo da spazi vengono rifiutati conEMPTY_FIELD. - Un campo non presente nella tabella precedente viene rifiutato con
UNKNOWN_FIELD. - Se lo stesso
usernamecompare più di una volta nella richiesta, falliscono tutte le sue occorrenze conDUPLICATE_USERNAME.
Risposta
Se la richiesta può essere letta, la piattaforma risponde 202 e mette in coda l'operazione:
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "queued",
"status_url": "https://tenant.takesecurity.com/api/v1/users/bulk-upsert/3f2b9a1e-..."
}Conservi il request_id. È necessario per consultare il risultato.
Un
202indica che la richiesta è stata accettata, non che gli utenti siano già stati applicati. Il risultato di ogni record è disponibile nel passaggio 2.
Errori dell'intera richiesta
Questi errori rifiutano l'intera richiesta. Nessun utente viene applicato.
| Codice HTTP | Causa |
|---|---|
400 |
La richiesta non può essere letta: INVALID_JSON, INVALID_REQUEST, UNKNOWN_FIELD, MISSING_REQUIRED_FIELD, INVALID_FIELD_TYPE o EMPTY_FIELD. |
401 |
Il token è assente o non valido: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
Il token non ha l'ambito write_users (PERMISSION_DENIED), oppure l'organizzazione è disattivata o scaduta (TENANT_INACTIVE). |
413 |
Più di 1.000 utenti (TOO_MANY_RECORDS) o più di 4 MB (PAYLOAD_TOO_LARGE). |
415 |
Il tipo di contenuto non è application/json. |
429 |
È stato superato il limite di richieste. Attenda i secondi indicati nell'intestazione Retry-After prima di riprovare. |
Passaggio 2 — Consultare il risultato
GET /api/v1/users/bulk-upsert/{request_id}
Authorization: Bearer <token>Sostituisca {request_id} con l'identificativo restituito nel passaggio 1. Anche questo endpoint richiede l'ambito write_users.
Un lotto di 1.000 utenti termina in pochi minuti al massimo. Consulti lo stato ogni 5-10 secondi fino al termine dell'operazione.
Risposta
{
"request_id": "3f2b9a1e-6c1d-4f8e-9a77-1b2c3d...",
"status": "completed",
"received_at": "2026-10-01T12:00:00Z",
"started_at": "2026-10-01T12:00:01Z",
"finished_at": "2026-10-01T12:00:31Z",
"progress": {
"processed": 1000,
"total": 1000
},
"totals": {
"received": 1000,
"created": 740,
"updated": 230,
"unchanged": 29,
"failed": 1
},
"errors": [ ... ]
}-
status: stato dell'operazione.
queuedindica che è in coda ecompletedche è terminata. - progress: numero di record elaborati sul totale.
-
totals: riepilogo del risultato.
- created: utenti creati.
- updated: utenti esistenti con almeno un campo modificato.
- unchanged: record che non hanno prodotto modifiche, ad esempio perché erano già stati applicati.
- failed: record rifiutati.
- errors: dettaglio dei record non riusciti, con il relativo codice di errore.
Il risultato di ogni operazione può essere consultato per 30 giorni. Trascorso tale periodo, la consultazione risponde
404.
Errori della consultazione
| Codice HTTP | Causa |
|---|---|
401 |
Il token è assente o non valido: AUTHENTICATION_REQUIRED, AUTHENTICATION_FAILED. |
403 |
Il token non ha l'ambito write_users (PERMISSION_DENIED), oppure l'organizzazione è disattivata o scaduta (TENANT_INACTIVE). |
404 |
JOB_NOT_FOUND: l'identificativo non è valido, non esiste un'operazione con tale identificativo per questa applicazione, oppure il periodo di consultazione è scaduto. |
429 |
È stato superato il limite di richieste. Attenda i secondi indicati in Retry-After. |
L'operazione può essere consultata solo con la stessa applicazione che l'ha inviata.
Come interpretare gli errori per record
Ogni utente viene applicato completamente o non viene applicato. Un record che fallisce non lascia modifiche parziali né impedisce l'applicazione degli altri.
| Codice | Significato | Cosa fare |
|---|---|---|
MISSING_REQUIRED_FIELD |
Manca un campo obbligatorio per creare l'utente. | Invii tutti i campi in creazione. |
NO_UPDATE_FIELDS |
Il record include solo lo username. |
Aggiunga almeno un campo da modificare. |
EMPTY_FIELD |
Un campo è null, vuoto o composto solo da spazi. |
Compili il valore oppure ometta il campo. |
UNKNOWN_FIELD |
È stato inviato un campo non supportato. | Utilizzi solo i campi documentati. |
INVALID_RECORD |
Il record non ha un formato valido. | Verifichi la struttura del record. |
INVALID_FIELD_TYPE |
Un campo ha un tipo di dato errato, ad esempio is_active come testo. |
Invii il tipo indicato nella tabella dei campi. |
INVALID_USERNAME |
Lo username non rispetta le regole di formato. |
Verifichi i caratteri consentiti. |
INVALID_FIELD_VALUE |
Un valore non rispetta le regole del campo. | Verifichi le restrizioni del campo. |
INVALID_EMAIL |
L'email non ha un formato valido. | Corregga l'indirizzo. |
UNSUPPORTED_LANGUAGE |
Il language_code non è nell'elenco supportato. |
Utilizzi uno dei codici elencati. |
INVALID_GROUP_NAME |
Il nome del gruppo non ha un formato valido. | Verifichi il valore di group. |
GROUP_NOT_FOUND |
Il gruppo non esiste. | Lo crei prima con POST /api/v1/groups. |
AMBIGUOUS_GROUP_NAME |
Il nome non identifica un unico gruppo. | Verifichi i gruppi con quel nome. |
DUPLICATE_USERNAME |
Lo username si ripete nella stessa richiesta. |
Invii ogni utente una sola volta. |
USER_CONFLICT |
L'email appartiene a un altro utente o si ripete nella richiesta, oppure l'utente è cambiato durante l'operazione. | Corregga l'email. Se l'utente è cambiato durante l'operazione, invii nuovamente il record. |
INTERNAL_ERROR |
Errore interno durante l'elaborazione del record. | Invii nuovamente il record. |
NOT_PROCESSED |
Il record non è stato elaborato. | Invii nuovamente il record. |
INTERNAL_ERROR,NOT_PROCESSEDeUSER_CONFLICT(quando l'utente è cambiato durante l'operazione) si risolvono inviando nuovamente il record.
Tentativi ripetuti e concorrenza
-
Ripetere una richiesta è sicuro. Non crea mai un utente duplicato, né duplica o rimuove gruppi. I record già applicati vengono segnalati come
unchanged. - Due operazioni simultanee sullo stesso utente vengono applicate una dopo l'altra. Prevale l'ultima, senza mescolare i campi delle due.
Limite di frequenza
La piattaforma può limitare il numero di richieste al minuto di ogni organizzazione, contando tutte le richieste all'API, non solo quelle a questo endpoint. Se il limite è attivo e viene superato, la risposta è 429 con l'intestazione Retry-After. Attenda quei secondi prima di riprovare.
💡 Buone pratiche
- Creare i gruppi prima di inviare gli utenti. Questo endpoint non crea gruppi e il record fallisce con
GROUP_NOT_FOUND. - Inviare lotti fino a 1.000 utenti e verificare che il corpo non superi i 4 MB.
- Conservare il
request_iddi ogni invio e consultare lo stato ogni 5-10 secondi, senza superare questa frequenza. - Verificare sempre
totals.failede il bloccoerrorsprima di considerare concluso il caricamento. - Inviare nuovamente solo i record con
INTERNAL_ERROR,NOT_PROCESSEDoUSER_CONFLICTdovuto a una modifica concorrente. Anche reinviare l'intero lotto è sicuro, ma consuma più richieste. - Utilizzare uno
usernamestabile, che non cambi nel sistema di origine. La piattaforma non lo modifica negli account esistenti. - Inviare
is_activecome booleano JSON e non come testo. - Rispettare l'intestazione
Retry-Afterin caso di429invece di riprovare immediatamente. - Registrare un'applicazione per integrazione, con gli ambiti minimi necessari a tale integrazione.