API Import ed Export Utenti

L’API Import ed Export Utenti consente operazioni massiva sugli utenti per scenari di migrazione, onboarding e backup. Gli amministratori possono importare utenti da file CSV o JSON ed esportare l’intera directory utenti in entrambi i formati.

Le operazioni di importazione vengono elaborate in modo asincrono. Dopo aver caricato un file, il job di importazione avanza attraverso vari stati mentre le righe vengono validate e gli utenti vengono creati. Anche le operazioni di esportazione sono asincrone — una volta completate, il file generato è disponibile per il download per 24 ore.

Importa Utenti

Carica File di Importazione

Corpo della richiesta — multipart/form-data

Risposta di successo

{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "users-batch-2025-02.csv",
    "format": "csv",
    "status": "PENDING",
    "totalRows": 150,
    "processedRows": 0,
    "successCount": 0,
    "errorCount": 0,
    "errors": [],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:00:00Z"
  }
}

Codici di errore

Elenca Job di Importazione

Parametri di query

Risposta di successo

{
  "ok": true,
  "data": {
    "data": [
      {
        "id": "imp_abc123",
        "fileName": "users-batch-2025-02.csv",
        "format": "csv",
        "status": "COMPLETED",
        "totalRows": 150,
        "processedRows": 150,
        "successCount": 142,
        "errorCount": 8,
        "createdAt": "2025-02-18T10:00:00Z",
        "updatedAt": "2025-02-18T10:05:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 3,
      "totalPages": 1
    }
  }
}

Recupera Dettaglio Job di Importazione

Risposta di successo

{
  "ok": true,
  "data": {
    "id": "imp_abc123",
    "fileName": "users-batch-2025-02.csv",
    "format": "csv",
    "status": "COMPLETED",
    "totalRows": 150,
    "processedRows": 150,
    "successCount": 142,
    "errorCount": 8,
    "errors": [
      {
        "row": 12,
        "email": "[email protected]",
        "error": "Email already exists in this tenant"
      },
      {
        "row": 34,
        "email": "invalid-email",
        "error": "Invalid email format"
      },
      {
        "row": 56,
        "email": "[email protected]",
        "error": "Role 'super_admin' does not exist"
      }
    ],
    "createdAt": "2025-02-18T10:00:00Z",
    "updatedAt": "2025-02-18T10:05:00Z"
  }
}

Codici di errore

Progressione degli Stati

Formati dei File di Importazione

Formato CSV

La prima riga deve essere una riga di intestazione con i nomi delle colonne. L’ordine delle colonne non ha importanza. Le colonne vengono abbinate per nome (senza distinzione tra maiuscole e minuscole).

email,firstName,lastName,roles,password
[email protected],Jane,Doe,editor,SecurePass123!
[email protected],Bob,Smith,"editor,viewer",AnotherPass456!
[email protected],Alice,Johnson,admin,
[email protected],Carol,Williams,,

• Più ruoli sono separati da virgole tra virgolette: "editor,viewer"
• Il campo password vuoto significa che l’utente deve usare il magic link o il reset password per impostarne uno
• Il campo ruoli vuoto significa che l’utente viene creato senza ruoli assegnati

Formato JSON

Il file deve contenere un array JSON di oggetti utente al livello principale.

[
  {
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Doe",
    "roles": ["editor"],
    "password": "SecurePass123!"
  },
  {
    "email": "[email protected]",
    "firstName": "Bob",
    "lastName": "Smith",
    "roles": ["editor", "viewer"]
  }
]

Riferimento Campi

Gestione degli Errori per Riga

Ogni riga viene elaborata indipendentemente. Se una riga fallisce la validazione, viene saltata e l’errore viene registrato. L’elaborazione continua con le righe rimanenti.

Esporta Utenti

Avvia Esportazione

Corpo della richiesta

{
  "format": "csv"
}

Risposta di successo

{
  "ok": true,
  "data": {
    "id": "exp_abc123",
    "format": "csv",
    "status": "PENDING",
    "totalUsers": 0,
    "createdAt": "2025-02-18T11:00:00Z",
    "expiresAt": "2025-02-19T11:00:00Z"
  }
}

Scarica File di Esportazione

Intestazioni di risposta

Content-Type: text/csv (o application/json)
Content-Disposition: attachment; filename="users-export-2025-02-18.csv"

Codici di errore

Campi Esportati

Flusso di Migrazione

Una tipica migrazione tra tenant segue questo schema:

1. Esporta gli utenti dal tenant sorgente tramite POST /api/users/export con formato json.
2. Scarica il file di esportazione tramite GET /api/users/export/[id]/download.
3. Opzionalmente modifica il file per aggiustare i ruoli o rimuovere utenti.
4. Importa il file nel tenant di destinazione tramite POST /api/users/import.
5. Monitora il job di importazione tramite GET /api/users/import/[id] finché lo stato non è COMPLETED o PARTIAL.
6. Esamina eventuali errori a livello di riga nell’array errors.
7. Notifica gli utenti importati di impostare le proprie password tramite magic link o reset password (poiché le password non vengono esportate).

Riferimento Permessi

Correlati

• Guida Import ed Export — Procedura guidata di migrazione passo-passo
• Import ed Export Utenti — Esegui importazioni ed esportazioni dalla Console
• API Utenti — Endpoint di gestione utenti individuali
• API SCIM 2.0 — Alternativa di provisioning automatizzato