Vai al contenuto principale
PATCH
curl

Supporto KYC e KYB

Questo endpoint funziona in modo identico per le sessioni di Verifica degli utenti (KYC) e Verifica aziendale (KYB). Didit associa il session_id a entrambi i tipi di sessione; la validazione delle transizioni di stato è la stessa per entrambi (si applica lo stesso enum di stati a entrambi). La risposta contiene solo il session_id. Leggi session_kind da Retrieve Session quando la tua logica a valle deve distinguere il tipo.

Transizioni consentite

Puoi portare una sessione in Approved, Declined o Resubmitted. Qualsiasi altro new_status, incluso In Review, restituisce 400. Lo stato attuale della sessione deve essere uno tra Approved, Declined, In Review, Kyc Expired, Abandoned o Resubmitted; in caso contrario l’API restituisce 400. Impostare Approved o Declined su una sessione che ha già quello stato non produce effetti: l’API restituisce 200, non modifica nulla, non attiva alcun webhook e non invia alcuna email. Impostare Resubmitted su una sessione che è già Resubmitted restituisce 400 (The new status is the same as the current status.). Una nuova sottomissione i cui nodes_to_resubmit contengono solo funzionalità esclusivamente backend (AML, DATABASE_VALIDATION, IP_ANALYSIS) viene eseguita automaticamente e riporta la sessione a uno stato con decisione senza alcuna interazione con l’utente. Ripetere una nuova sottomissione di questo tipo entro 30 secondi restituisce 429 Too Many Requests con un header Retry-After, poiché una ripetizione immediata non può produrre un risultato diverso. Non inviare automaticamente una nuova sottomissione da un gestore di webhook ogni volta che ricevi lo stato In Review: prima esamina il risultato o modifica i dati sottostanti.

Visualizza in anteprima l’email

Con send_email: true, Approved e Declined inviano alla persona l’email con la decisione, mentre Resubmitted le invia un nuovo link con i motivi. Puoi visualizzare quell’email prima di modificare qualsiasi cosa:
  1. Chiama Preview Decision Email per Approved o Declined, oppure Preview Resubmission Email per Resubmitted.
  2. Controlla il subject e l’html renderizzati, il recipient e will_be_sent / not_sent_reason.
  3. Chiama questo endpoint con lo stesso new_status (e, per una nuova sottomissione, gli stessi nodes_to_resubmit), send_email: true, email_address impostato su recipient, la email_language che hai visualizzato in anteprima e email_preview_token impostato su preview_token.
Nessuna delle due anteprime modifica la sessione o invia qualcosa. L’aggiornamento invia poi esattamente l’email che hai visualizzato in anteprima. La ricevuta scade dopo 15 minuti. Se il destinatario, la lingua, lo stato della sessione, il mittente o l’email sono cambiati dopo l’anteprima, l’aggiornamento restituisce 409 prima che venga modificato qualsiasi elemento; rigenera l’anteprima e conferma con la nuova ricevuta. Inviare email_preview_token senza send_email: true restituisce 400. Il passaggio di anteprima è facoltativo: le integrazioni esistenti possono continuare a chiamare questo endpoint senza di esso.

Esempi

Autorizzazione

Richiede il privilegio write:sessions. Lo stesso privilegio vale per entrambi i tipi.

Correlati

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Parametri del percorso

sessionId
string<uuid>
obbligatorio

UUID della sessione di verifica da aggiornare. Accetta sia ID di sessione utente (KYC) sia ID di sessione aziendale (KYB): il servizio risolve l'ID per entrambi i tipi di sessione.

Esempio:

"11111111-2222-3333-4444-555555555555"

Corpo

application/json
new_status
enum<string>
obbligatorio

Stato di destinazione. Approved e Declined registrano una decisione manuale definitiva (ciascuna può anche revocare l'altra). Resubmitted azzera i passaggi selezionati e rimanda la sessione all'utente. Qualsiasi altro valore restituisce 400.

Opzioni disponibili:
Approved,
Declined,
Resubmitted
Esempio:

"Approved"

comment
string

Motivo della modifica in formato testo libero, memorizzato nella traccia di revisione della sessione e restituito nell'array reviews di Get Decision. Ad esempio Duplicated user.

Esempio:

"All checks passed manual review"

nodes_to_resubmit
object[]

Passaggi del workflow che l'utente deve ripetere. Viene preso in considerazione solo quando new_status è Resubmitted. Per Approved/Declined le voci vengono comunque convalidate a livello di schema (un valore feature non valido restituisce 400), ma le voci conformi allo schema vengono semanticamente ignorate. Se omesso, il server seleziona automaticamente i tentativi esistenti di OCR, Rilevamento della vitalità, Confronto facciale, Prova di residenza, Verifica telefonica, Verifica email, Screening AML, Validazione su database e Questionari il cui stato è Declined, In Review, Not Finished o Expired (i tentativi relativi a NFC, analisi IP, stima dell'età, ricerca facciale e documenti KYB non vengono mai selezionati automaticamente; i tentativi sul volto diversi dal confronto facciale vengono selezionati come LIVENESS) — le funzionalità che l'utente non ha mai tentato (nessun tentativo registrato) NON vengono selezionate, quindi una sessione con zero tentativi restituisce 400 ("No features found that need resubmission") anche se nulla è stato approvato; in tal caso, passa esplicitamente nodes_to_resubmit. I passaggi vengono eseguiti nell'ordine del grafo del workflow indipendentemente dall'ordine con cui li invii. KYB_REGISTRY, KYB_KEY_PEOPLE e l'alias KYB vengono rifiutati con 400 — tali controlli padre vengono ricalcolati a partire dalle relative sessioni KYC figlie.

send_email
boolean
predefinito:false

Indica se inviare un'email all'utente in merito alla modifica. Richiede email_address. Per Approved/Declined l'utente riceve una notifica di stato; per Resubmitted l'email include il link di verifica e i motivi del nuovo invio specifici per ciascun passaggio.

Esempio:

false

email_address
string<email>

Destinatario dell'email di notifica. Obbligatorio quando send_email è true; se omesso restituisce 400.

Esempio:

"user@example.com"

email_language
string
predefinito:en

Lingua per l'email di notifica. Accetta qualsiasi stringa a livello di schema; i codici non supportati ripiegano silenziosamente sull'inglese (en).

Esempio:

"en"

email_preview_token
string
write-only

Ricevuta opzionale da Preview Decision Email (per Approved e Declined) o da Preview Resubmission Email (per Resubmitted): il relativo preview_token. Valida solo con send_email: true; in sua assenza la richiesta restituisce 400. Il destinatario, la lingua, lo stato della sessione, il mittente e l'email (e, per un nuovo invio, i passaggi selezionati) devono comunque corrispondere all'anteprima, e la ricevuta scade dopo 15 minuti. In caso contrario, la richiesta restituisce 409 prima che la sessione venga modificata o che venga inviata un'email. Le integrazioni esistenti possono omettere questo campo.

Required string length: 1 - 512

Risposta

Stato aggiornato. La risposta contiene solo il session_id; recupera la sessione aggiornata tramite Get Decision. Il webhook status.updated viene attivato dopo il commit della modifica. Ripetere Approved o Declined restituisce lo stesso corpo e non modifica nulla.

session_id
string<uuid>

UUID della sessione aggiornata.

Ultima modifica il 7 novembre 2026