> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API di gestione v3: workflow e fatturazione > Configura workflow, questionari, utenti, fatturazione e blocklist via API con Didit. Pronta per agenti e MCP. Prezzi a consumo, senza contratti. ## Autenticazione Tutti gli endpoint dell'API di gestione usano la tua chiave API dell'applicazione. Negli URL non servono UUID di organizzazione o applicazione: l'applicazione viene identificata dalla tua chiave. ```bash theme={null} curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/... ``` Non hai ancora una chiave API? [Registrati in modo programmatico con 2 chiamate API](https://docs.didit.me/it/integration/programmatic-registration.md). *** ## Workflow Un workflow definisce quali passaggi di verifica devono completare i tuoi utenti (scansione del documento d'identità, rilevamento della vitalità, confronto facciale, screening AML, ecc.). Ogni workflow è una configurazione riutilizzabile che colleghi alle sessioni. **GET /v3/workflows/** `GET` Elenca tutti i workflow della tua applicazione. Restituisce le funzionalità e le soglie di ciascun workflow e indica se è quello predefinito. **POST /v3/workflows/** `POST` Crea un nuovo workflow. Definisci quali funzionalità di verifica attivare, imposta le soglie, configura i tipi di documento accettati e altro. **GET /v3/workflows/\{uuid}/** `GET` Recupera tutti i dettagli di un workflow specifico, incluse le configurazioni di tutte le funzionalità e le soglie. **PATCH /v3/workflows/\{uuid}/** `PATCH` Aggiorna la configurazione di un workflow. Puoi modificare qualsiasi impostazione delle funzionalità, le soglie o i documenti accettati. **DELETE /v3/workflows/\{uuid}/** `DELETE` Elimina un workflow. Le sessioni che usano già questo workflow non sono interessate. > [!WARNING] > > Consigliamo vivamente di usare la **Business Console** per creare e configurare i workflow. Il builder visivo dei workflow offre modelli, configurazione delle funzionalità tramite trascinamento, impostazioni dei documenti, regolazione delle soglie e anteprima, senza scrivere codice. Usa l'API solo per l'automazione o la gestione programmatica dei workflow. ### Esempio rapido: creare un workflow Il `workflow_type` determina l'insieme di funzionalità di base. Le singole funzionalità vengono poi attivate o disattivate con i flag `is_*_enabled`. ```bash theme={null} curl -X POST https://verification.didit.me/v3/workflows/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_face_match_enabled": true, "is_liveness_enabled": true, "is_aml_enabled": false }' ``` I valori disponibili per `workflow_type` sono: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, `address_verification`, `questionnaire_verification`, `email_verification`, `phone_verification`. Per i workflow `kyc`, la verifica dell'identità è inclusa automaticamente: non serve un flag separato. Usa i flag `is_*_enabled` per aggiungere o rimuovere funzionalità facoltative come confronto facciale, rilevamento della vitalità, AML, NFC, telefono, email, prova di residenza, Analisi dispositivo e IP e altre. Quindi usa il workflow quando crei le sessioni: ```bash theme={null} curl -X POST https://verification.didit.me/v3/session/ \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "callback_url": "https://myapp.com/callback", "workflow_id": "WORKFLOW_UUID_FROM_ABOVE" }' ``` *** ## Questionari Moduli personalizzati da aggiungere ai workflow di verifica per raccogliere ulteriori informazioni dagli utenti. **GET /v3/questionnaires/** `GET` Elenca tutti i questionari. **POST /v3/questionnaires/** `POST` Crea un nuovo questionario con domande personalizzate, logica di ramificazione e traduzioni. **GET /v3/questionnaires/\{uuid}/** `GET` Recupera i dettagli di un questionario, incluse tutte le domande e la struttura del modulo. **PATCH /v3/questionnaires/\{uuid}/** `PATCH` Aggiorna un questionario. **DELETE /v3/questionnaires/\{uuid}/** `DELETE` Elimina un questionario. *** ## Utenti Gestisci le persone verificate (utenti) nella tua applicazione. Ogni utente è identificato da una stringa `vendor_data` che fornisci quando crei le sessioni. **GET /v3/users/** `GET` Elenca tutti gli utenti della tua applicazione, inclusi lo stato di verifica e la cronologia delle sessioni. **GET /v3/users/\{vendor\_data}/** `GET` Recupera i dettagli di un utente tramite il tuo identificatore vendor\_data. **PATCH /v3/users/\{vendor\_data}/** `PATCH` Aggiorna i metadati di un utente. **POST /v3/users/delete/** `POST` Elimina in blocco gli utenti. Corpo: `{"vendor_data_list": ["user-1", "user-2"]}` oppure `{"delete_all": true}`. Elimina definitivamente inoltre tutti i modelli biometrici conservati per quegli utenti. *** ## Modelli biometrici Modelli biometrici facciali privi di immagini che un'applicazione che ha scelto di aderire conserva dopo aver eliminato le sessioni. Vedi [Modelli biometrici](https://docs.didit.me/it/management-api/biometric-templates/overview.md). **GET /v3/biometric-templates/** `GET` Elenco paginato con filtri (`vendor_data`, `vendor_user_uuid`, `status`, `source_type`, `retained_from`, `retained_to`, `ordering`). **GET /v3/biometric-templates/count/** `GET` Conteggio con gli stessi filtri. **GET /v3/biometric-templates/\{template\_uuid}/** `GET` Un modello: utente titolare, riferimento di provenienza, scadenza, istruzione e stato. **DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE` Elimina definitivamente un modello. Restituisce `{"uuid": "...", "outcome": "purged" | "already_purged"}`. **POST /v3/biometric-templates/delete/** `POST` Eliminazione definitiva in blocco. Corpo: `{"template_uuids": [...]}` oppure `{"delete_all": true}`, con eventuali filtri facoltativi. *** ## Operazioni sulle sessioni **POST /v3/sessions/delete/** `POST` Elimina in blocco le sessioni. Richiede `delete:sessions`. Corpo: `{"session_numbers": ["1", "2", "3"]}` oppure `{"delete_all": true}` (restringi `delete_all` con i filtri di List Sessions preceduti da `filter_`, come `filter_status`), più eventuali `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction` e `instruction_id`. Fino a 20 sessioni corrispondenti restituiscono `200` con un `face_retention_outcome` per ogni sessione; per un numero maggiore viene restituito `202` con un job di eliminazione. **GET /v3/sessions/delete/\{job\_id}/** `GET` Avanzamento e conteggi degli esiti di un'eliminazione in blocco delle sessioni che ha restituito `202`. **GET /v3/sessions/\{uuid}/reviews/** `GET` Elenca le revisioni e il registro delle attività di una sessione. **POST /v3/sessions/\{uuid}/reviews/** `POST` Aggiungi una nota di revisione o un cambio di stato a una sessione. *** ## Fatturazione **GET /v3/billing/balance/** `GET` Recupera il saldo attuale dei crediti e le impostazioni di ricarica automatica. ```json theme={null} { "balance": "142.5000", "auto_refill_enabled": true, "auto_refill_amount": "100.0000", "auto_refill_threshold": "10.0000" } ``` **POST /v3/billing/top-up/** `POST` Crea una sessione di checkout Stripe per ricaricare i crediti. Ogni ricarica va da \$50 a \$20,000 e viene accreditata al valore nominale. ```json theme={null} { "amount_in_dollars": 100, "success_url": "https://myapp.com/billing/success", "cancel_url": "https://myapp.com/billing/cancel" } ``` *** ## Liste (Blocklist, Allowlist e personalizzate) Gestisci liste tipizzate per il blocklisting, l'allowlisting e le condizioni personalizzate dei workflow. Consulta la [documentazione completa dell'API delle liste](https://docs.didit.me/it/management-api/lists/overview.md). **GET /v3/lists/** `GET` Elenca tutte le liste dell'applicazione (blocklist, allowlist, personalizzate). **POST /v3/lists/\{list\_uuid}/entries/** `POST` Aggiunge una voce a una lista. Supporta `reference_session_id` per estrarre automaticamente i dati da una sessione e `reference_object_uuid` per la tracciabilità verso transazioni, utenti o aziende. **DELETE /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE` Rimuove una voce da una lista. **POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST` Carica un'immagine del volto in una blocklist facciale (base64). *** ## Configurazione webhook **GET /v3/webhook/** `GET` Recupera la configurazione webhook attuale, inclusi l'URL, la versione, la chiave segreta per verificare le firme dei webhook e la politica di conservazione dei dati e dei modelli biometrici dell'applicazione. La risposta contiene anche `allowed_domains`, descritto più avanti in `PATCH /v3/webhook/`. ```json theme={null} { "webhook_url": "https://myapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "whsec_a1b2c3d4e5f6...", "capture_method": "both", "data_retention_months": null, "face_retention_policy": "delete_with_session", "face_retention_days": null, "allowed_return_hosts": ["app.example.com"], "allowed_domains": ["https://app.example.com"] } ``` **PATCH /v3/webhook/** `PATCH` Aggiorna l'URL del webhook, la versione o ruota la chiave segreta. Imposta `rotate_secret_key: true` per generare un nuovo segreto del webhook (quello precedente viene invalidato immediatamente). Imposta anche la politica di conservazione dell'applicazione: `data_retention_months` e `face_retention_policy` (`delete_with_session` come valore predefinito, oppure `retain_until_user_deleted`), insieme a `face_retention_days` obbligatorio, un valore finito da 1 a 3650, quando la conservazione è attiva. Consulta [Conservazione dei modelli biometrici](https://docs.didit.me/it/console/data-retention.md#conservazione-del-modello-biometrico). Registra inoltre `allowed_return_hosts`: fino a 20 nomi host semplici (ad esempio `app.example.com`, senza schema, porta, percorso o wildcard) verso cui una verifica tramite [API del wallet di identità digitale](https://docs.didit.me/it/standalone-apis/digital-id-wallets.md#registra-la-tua-destinazione-di-ritorno) può riportare la persona su HTTPS. Una nuova lista sostituisce quella registrata, e il dominio White label della tua applicazione è sempre consentito. Imposta anche `allowed_domains`: fino a 50 origini web (ad esempio `https://app.example.com`) in cui il flusso di verifica ospitato può essere incorporato e verso cui può riportare l'utente tramite un `callback` della sessione. Ogni voce è composta da uno schema, un host e una porta facoltativa, senza percorso, query o wildcard. Usa `https`; `http` è accettato solo per `localhost`, `127.0.0.1` e `::1`. Didit memorizza ogni origine in minuscolo senza la porta predefinita e restituisce la lista in `allowed_domains`. Una voce non valida genera un errore 400 per `allowed_domains`. Una nuova lista sostituisce quella registrata, e una lista vuota rimuove la restrizione. Finché la lista non è vuota, [`POST /v3/session/`](https://docs.didit.me/it/sessions-api/create-session) rifiuta con 400 un `callback` web che non vi appartiene, e il flusso ospitato non reindirizza l'utente a un callback memorizzato o predefinito del workflow che non vi appartiene. Gli schemi URL personalizzati (deep link delle app) e le chiamate API server-to-server non sono soggetti a questa limitazione. Se invii `endpoints`, ogni destinazione webhook non inclusa nella lista viene eliminata in modo permanente, insieme al suo segreto di firma e all'intero registro delle consegne, esattamente come [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/it/management-api/webhook/delete-destination). Questa operazione non può essere annullata. Per gestire le destinazioni una alla volta, usa invece gli [endpoint delle destinazioni webhook](https://docs.didit.me/it/management-api/webhook/list-destinations.md). ```json theme={null} { "webhook_url": "https://myapp.com/webhooks/didit", "webhook_version": "v3", "allowed_domains": ["https://app.example.com"] } ``` *** ## Riepilogo completo degli endpoint API | Endpoint | Metodo | Descrizione | | - | - | - | | `/v3/session/` | POST | Crea una sessione di verifica | | `/v3/sessions/` | GET | Elenca tutte le sessioni | | `/v3/session/{id}/decision/` | GET | Recupera il risultato di verifica della sessione | | `/v3/session/{id}/update-status/` | PATCH | Approva o rifiuta una sessione | | `/v3/session/{id}/delete/` | DELETE | Elimina una singola sessione | | `/v3/sessions/delete/` | POST | Eliminazione in blocco delle sessioni | | `/v3/sessions/delete/{job_id}/` | GET | Stato del processo di eliminazione in blocco delle sessioni | | `/v3/sessions/{id}/reviews/` | GET, POST | Attività e revisioni della sessione | | `/v3/workflows/` | GET, POST | Elenca/crea workflow | | `/v3/workflows/{id}/` | GET, PATCH, DELETE | Dettaglio/aggiornamento/eliminazione del workflow | | `/v3/questionnaires/` | GET, POST | Elenca/crea questionari | | `/v3/questionnaires/{id}/` | GET, PATCH, DELETE | Dettaglio del questionario | | `/v3/users/` | GET | Elenca gli utenti verificati | | `/v3/users/{vendor_data}/` | GET, PATCH | Dettaglio/aggiornamento dell'utente | | `/v3/users/delete/` | POST | Eliminazione in blocco degli utenti (elimina anche i relativi modelli biometrici conservati) | | `/v3/biometric-templates/` | GET | Elenca i modelli biometrici conservati | | `/v3/biometric-templates/count/` | GET | Conta i modelli biometrici conservati | | `/v3/biometric-templates/{id}/` | GET, DELETE | Dettaglio del modello / eliminazione | | `/v3/biometric-templates/delete/` | POST | Eliminazione in blocco dei modelli | | `/v3/lists/` | GET, POST | Elenca tutte le liste / crea una lista | | `/v3/lists/{id}/` | GET, PATCH, DELETE | Dettaglio / aggiornamento / eliminazione della lista | | `/v3/lists/{id}/entries/` | GET, POST | Elenca le voci / aggiungi una voce | | `/v3/lists/{id}/entries/{eid}/` | DELETE | Rimuovi una voce | | `/v3/lists/{id}/entries/face-upload/` | POST | Carica un volto nella blocklist | | `/v3/webhook/` | GET, PATCH | Configurazione webhook (URL, segreto, versione), politica di conservazione e host di ritorno del wallet | | `/v3/billing/balance/` | GET | Verifica il saldo dei crediti | | `/v3/billing/top-up/` | POST | Ricarica i crediti | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.