Vai al contenuto principale
PATCH
curl

Cosa fa

Una sessione di verifica è composta da singole funzionalità (passaggi): ID/OCR, Rilevamento della vitalità, Confronto facciale, AML, Prova di residenza, Telefono e così via. Questo endpoint ti consente di impostare lo stato di una di queste funzionalità su Approved, Declined o In Review. Usa update-status quando vuoi approvare, rifiutare o riaprire l’intera sessione. Usa questo endpoint quando vuoi registrare una decisione su un solo passaggio, per esempio per contrassegnare il passaggio Confronto facciale come Declined nel tuo flusso di revisione. Una sessione che ha già una decisione la mantiene: cambia solo il passaggio. Se la sessione non ha ancora una decisione e il suo workflow sta aspettando proprio questo passaggio, applicare la sovrascrittura completa il passaggio, come accadrebbe completandolo normalmente. Il workflow prosegue, vengono eseguiti i passaggi successivi e un nodo di stato può impostare la decisione della sessione e inviare un webhook status.updated.

Come indicare un passaggio con node_id

Nei workflow basati su grafo ogni passaggio ha un node_id (per esempio feature_ocr_1, feature_liveness_1, feature_aml_1). Puoi trovarli nella decisione della sessione: ogni funzionalità in una decisione V3 contiene il proprio node_id. Per i workflow non basati su grafo (a passaggio singolo) la funzionalità sottostante non ha un ID nodo. Passa il valore letterale default come nodeId per indicarla. Poiché in questi workflow nessun passaggio ha un ID nodo, passa anche feature_type (per esempio LIVENESS, AML o FACE_MATCH) per indicare il passaggio desiderato. Un feature_type sconosciuto restituisce 400.

Attendere che la persona completi il flusso

Per impostazione predefinita la sovrascrittura viene applicata subito. Se la persona sta ancora percorrendo il flusso, viene modificato un passaggio di un flusso ancora in corso; in tal caso la sovrascrittura viene registrata con forced: true. Imposta defer_until_flow_finishes: true per attendere. Finché la sessione è Not Started, In Progress o Resubmitted e la persona non ha completato il flusso, la sovrascrittura viene memorizzata come pending_until_flow_finishes. Viene applicata quando la persona completa il flusso, dopo che il flusso ha raggiunto la propria decisione. Su una sessione il cui flusso è già terminato, viene applicata subito in entrambi i casi. Una sovrascrittura in attesa viene annullata anziché applicata quando:
  • la persona rifà il passaggio prima di completarlo (check_changed),
  • una sovrascrittura più recente sullo stesso passaggio la sostituisce (replaced),
  • la sessione esce dal flusso senza completarlo: abbandonata, scaduta o decisa a metà del flusso (session_closed),
  • la annulli con Annulla la sovrascrittura della funzionalità (cancelled_by_reviewer).
Il campo override della risposta indica cosa è successo: state è applied oppure pending_until_flow_finishes, e applied_at è valorizzato una volta applicata. Il campo new_status di primo livello è lo stato memorizzato del passaggio, quindi resta invariato mentre la sovrascrittura è in attesa. Usa Elenca le sovrascritture delle funzionalità per vedere tutte le sovrascritture di una sessione e se la persona è ancora nel flusso.

Supporto KYC e KYB

Funziona allo stesso modo per Verifica degli utenti (KYC) e Verifica aziendale (KYB): Didit risolve il sessionId in entrambi i casi. I tipi di passaggio supportati includono ID/OCR, Rilevamento della vitalità, Confronto facciale, NFC, AML, Prova di residenza, Telefono, Email, Validazione su database, Questionario e i controlli KYB su registro, documenti e persone chiave.
Le sessioni API autonome (quelle create tramite le API di verifica standalone, session_type = API) non possono avere lo stato delle singole funzionalità modificato: l’endpoint restituisce 400.

Esempi

Cosa succede dopo un aggiornamento

  • Webhook: un evento data.updated viene inviato quando la sovrascrittura viene applicata, subito oppure al termine del flusso. Nulla viene inviato mentre è in attesa o quando viene annullata.
  • Attività: ogni sovrascrittura viene registrata nell’attività della sessione come FEATURE_OVERRIDE_PENDING, FEATURE_OVERRIDE_APPLIED o FEATURE_OVERRIDE_CANCELLED, con l’autore (chiave API, utente o il sistema quando una sovrascrittura in attesa viene applicata). La voce della richiesta riporta il tuo comment come motivo. Nell’array reviews della decisione della sessione queste voci compaiono con new_status: null, e la voce della richiesta riporta il tuo motivo in comment.
  • Decisione della sessione: una sessione che ha già una decisione la mantiene. Per cambiare la decisione finale, chiama update-status separatamente.

Autorizzazione

Richiede il privilegio write:sessions, con una chiave API del client (x-api-key) o un header di autorizzazione utente. Una chiave API con ambito limitato richiede l’accesso in scrittura alle decisioni.

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. 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"

nodeId
string
obbligatorio

ID del nodo del grafo del workflow della funzionalità da aggiornare (ad esempio feature_ocr_1). Usa il valore letterale default per i workflow non basati su grafo (a singolo passaggio) in cui la funzionalità non ha un ID nodo.

Esempio:

"feature_ocr_1"

Corpo

application/json
new_status
enum<string>
obbligatorio

Stato di destinazione per questa funzionalità. Deve differire dal valore attuale.

Opzioni disponibili:
Approved,
Declined,
In Review
Esempio:

"Approved"

comment
string

Nota opzionale a testo libero registrata nella traccia di revisione della sessione per questa modifica della funzionalità.

Esempio:

"Document manually verified by compliance."

feature_type
enum<string>

A quale tipo di passaggio puntare. Necessario sui workflow non a grafo (nodeId = default), dove i passaggi non condividono alcun nodo; facoltativo negli altri casi. Un valore sconosciuto restituisce 400.

Opzioni disponibili:
ID_VERIFICATION,
OCR,
OCR_BACK,
NFC,
LIVENESS,
FACE,
AGE_ESTIMATION,
AGE_VERIFICATION,
FACE_SEARCH,
FACE_MATCH,
IP_ANALYSIS,
AML,
PHONE,
PHONE_VERIFICATION,
EMAIL,
EMAIL_VERIFICATION,
POA,
PROOF_OF_ADDRESS,
DATABASE_VALIDATION,
DATA_VALIDATION,
QUESTIONNAIRE,
DOCUMENT_AI,
KYB_REGISTRY,
KYB_DOCUMENTS,
KYB_KEY_PEOPLE,
BANK_VERIFICATION,
GEOLOCATION
Esempio:

"LIVENESS"

defer_until_flow_finishes
boolean
predefinito:false

Mentre la persona è ancora nel flusso, memorizza l'override come pending_until_flow_finishes e applicalo al termine del flusso, anziché immediatamente. Se omesso o impostato su false, l'override viene applicato immediatamente. Su una sessione il cui flusso è già terminato, viene comunque applicato immediatamente.

Esempio:

false

Risposta

L'override è stato registrato. new_status è lo stato del controllo così come memorizzato: quello richiesto una volta applicato l'override, quello invariato mentre attende il completamento del flusso. override indica quale delle due situazioni si è verificata.

session_id
string<uuid>
obbligatorio
node_id
string | null
obbligatorio

Il nodo del workflow del passaggio aggiornato, oppure null per un passaggio senza nodo (il percorso default in un workflow non a grafo).

Esempio:

"feature_ocr_1"

feature_type
string
obbligatorio

Nome del modello della funzionalità aggiornata (ad es. KYC, Face, FaceMatch, AML, POA).

Esempio:

"KYC"

new_status
string
obbligatorio

Lo stato memorizzato del controllo: quello richiesto una volta applicato l'override, quello invariato mentre l'override è in attesa che il flusso termini.

Esempio:

"Approved"

override
object
obbligatorio

Un override dello stato di un controllo (funzionalità) eseguito con PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/: cosa modifica, se è stato applicato o è ancora in attesa che la persona completi il flusso, chi lo ha richiesto e perché.

Ultima modifica il 7 novembre 2026