Vai al contenuto principale

Panoramica

Il report di verifica dell’identità raccoglie tutto ciò che Didit ha estratto e validato da un documento d’identità rilasciato da un’autorità governativa: passaporti, carte d’identità, patenti di guida e permessi di soggiorno. Raggruppa i campi anagrafici e del documento estratti tramite OCR, gli URL firmati per i contenuti multimediali acquisiti, i dati dell’indirizzo analizzati e geolocalizzati, i punteggi di qualità dell’immagine per ciascun lato, i contenuti della MRZ, le suddivisioni per sistema di scrittura (latino / non latino) e le corrispondenze del documento tra sessioni diverse. Il report viene generato dopo che l’utente ha completato il passaggio di acquisizione del documento in un workflow (o dopo aver chiamato l’endpoint OCR autonomo). Didit identifica il tipo di documento, esegue l’OCR, valida la MRZ / il codice a barre / il codice QR, analizza l’indirizzo, verifica la presenza di manomissioni (acquisizioni da schermo, copie stampate, manipolazioni del ritratto) e confronta il documento con ogni altro documento acquisito nella tua applicazione. Ciascun report include il proprio status — indipendente dallo stato generale della sessione — che riflette l’esito del solo passaggio relativo al documento d’identità:
  • Approvato — documento riconosciuto, tutti i campi obbligatori estratti, nessun avviso configurato per indirizzare il documento al rifiuto si è attivato.
  • In revisione — uno o più avvisi si sono attivati e il tuo workflow li indirizza verso la revisione.
  • Rifiutato — si è verificata una condizione di rifiuto automatico (documento non supportato, documento scaduto, ritratto mancante, riscontro in blocklist, mancato superamento dell’età adattiva) oppure si è attivato un avviso la cui azione configurata è Rifiuta (l’età minima/massima è impostata per impostazione predefinita su Rifiuta).
  • Scaduto — la expiration_date del documento è trascorsa dopo la verifica. Il monitoraggio continuo della scadenza di Didit passa il report da Approved a Expired, aggiunge un avviso DOCUMENT_EXPIRED e sposta una sessione approvata allo stato di sessione Kyc Expired.
  • Non completato — l’utente non ha mai completato il passaggio di acquisizione.

Dove compare nelle risposte API

Il report di verifica dell’identità viene fornito all’interno dell’array id_verifications[] — sempre un array JSON, mai un singolo oggetto id_verification. Compaiono più voci quando un workflow esegue più di un passaggio del documento (ad esempio un documento d’identità principale più un passaggio di incremento del livello di verifica).
  • API per la decisione della sessione — GET /v3/session/{sessionId}/decision/ restituisce id_verifications[] al livello principale. Consulta Recupera decisione della sessione.
  • Webhook — i payload di session.status.updated includono lo stesso array id_verifications[] una volta che il passaggio ha generato dati. Consulta Webhook.
  • API OCR autonoma — l’invio diretto del documento restituisce un singolo oggetto id_verification con gli stessi campi. Consulta API OCR autonoma.
Leggi response.id_verifications[0] e itera sull’array. La struttura a singolo oggetto id_verification esiste solo nell’API OCR autonoma: non è presente sull’endpoint v3 per la decisione.

Schema

Lo schema canonico campo per campo si trova nella pagina di riferimento Modelli di dati. I campi sottostanti provengono direttamente da IDVerificationV3Serializer, che estende IDVerificationV2Serializer e aggiunge node_id, l’array tra sessioni matches[] e l’array document_selfie_face_matches[] di Silent Capture.

Campi di primo livello

issuing_state è sempre a livello di paese, mai a livello sub-nazionale. Per ogni tipo di documento, comprese le patenti di guida rilasciate da uno stato o da una provincia (Australia, Stati Uniti, Canada), issuing_state e issuing_state_name riportano il paese (ad esempio AUS / Australia), non lo stato. Il valore sub-nazionale, quando il documento ne include uno, è disponibile separatamente in parsed_address.region (con fallback su extra_fields.state per alcuni tipi di documento). La panoramica della sessione nella Business Console mostra questo dato, quando presente, come una riga Regione sotto Stato di emissione.
Patenti di guida che riportano due numeri (Australia). Le patenti australiane riportano sia un numero di patente, che identifica l’abilitazione alla guida del titolare e rimane invariato in caso di sostituzione della tessera, sia un numero di carta, che identifica la carta fisica e cambia a ogni riemissione. Per queste patenti, Didit mappa sempre i numeri nello stesso modo:
  • personal_number — il numero di patente
  • document_number — il numero di carta
Questo vale per ogni stato e territorio australiano (NSW, VIC, QLD, WA, SA, TAS, ACT, NT). Su alcune varianti il numero di carta è stampato solo sul retro, quindi viene letto solo quando viene acquisito il retro della patente. Quando non è possibile leggere alcun numero di carta, il numero di patente viene riportato sia come document_number sia come personal_number, in modo che document_number contenga sempre un identificativo al termine della verifica. In ogni caso, personal_number è il numero di patente. Su altri tipi di documento, document_number rimane il numero principale estratto tramite OCR e può costituire esso stesso un identificativo a livello di titolare.
Il CUIL argentino è extra_fields.tax_number, mai personal_number. I documenti argentini riportano il CUIL (l’identificativo a 11 cifre su cui si basano AFIP, ANSES e le agenzie di informazioni creditizie) in una posizione diversa su ciascun documento, e il DNI riporta un secondo numero a 11 cifre accanto ad esso:
  • sulla patente di guida, il CUIL è il valore contenuto in personal_number;
  • sul DNI, personal_number contiene il número de trámite, che identifica la richiesta della carta e non è un identificativo del titolare. Il CUIL del DNI viene letto dal relativo campo stampato.
Pertanto personal_number non è un CUIL affidabile per l’Argentina: su un DNI è un numero a 11 cifre che non restituirà silenziosamente alcun risultato da nessun registro. Leggi invece extra_fields.tax_number. Didit lo riporta solo quando il valore è convalidato come un vero CUIL (prefisso della persona più la cifra di controllo modulo-11), in cifre canoniche senza separatori (27111111117), qualunque sia il documento argentino presentato dal titolare. Quando non è stato possibile leggere il CUIL della carta, la chiave è assente anziché essere compilata con un numero che non è un CUIL: acquisisci la patente di guida come secondo documento oppure raccogli il CUIL tramite la risposta a un Questionario o tramite i metadata della sessione, per coprire quegli utenti.

Punteggi di qualità dell’immagine

front_image_quality_score e back_image_quality_score restituiscono ciascuno:
Usa overall_score come rapido controllo di idoneità: punteggi superiori a 70 indicano generalmente un’acquisizione sufficientemente buona per una verifica affidabile.

Punteggi del rilevamento della vitalità del documento

document_liveness riporta ciò che il controllo del rilevamento della vitalità del documento ha misurato, indipendentemente dal fatto che abbia generato o meno un avviso. Un avviso esiste solo quando un punteggio è sceso al di sotto di una delle soglie del workflow, quindi prima di questo campo un documento approvato non conteneva alcuna evidenza di vitalità: il campo è il modo in cui puoi sottoporre ad audit una sessione superata con successo. È null quando il controllo non è stato eseguito (ad esempio per un metodo che non prevede documenti o per un’indisponibilità del modello registrata nei log di sessione). Contiene un oggetto per ciascun tipo di frode (portrait_replace, printed_copy e screen_replay), ciascuno con:
Per i documenti più vecchi senza evidenze di valutazione salvate, i punteggi memorizzati rimangono visibili ma sia le soglie che bucket sono null. Le impostazioni correnti del workflow non vengono mai utilizzate per ricostruire un esito storico. Lo stesso vale per un’acquisizione la cui valutazione del documento non è ancora stata completata. La Business Console mostra le stesse tre righe nel blocco rilevamento della vitalità del documento della sezione Verifica dell’identità della sessione.

Corrispondenze tra sessioni

matches[] elenca fino a 5 altri documenti nella tua applicazione che corrispondono a questo: stessa data di nascita, stesso paese di emissione e un nome completo fortemente simile. I documenti inseriti nella blocklist richiedono inoltre una corrispondenza esatta del numero di documento. Le sessioni appartenenti allo stesso utente (con lo stesso vendor_data) sono escluse. Ciascuna voce include session_id, session_number, vendor_data, verification_date, user_details (name, document_type, document_number), status, is_blocklisted (true quando il documento è stato aggiunto alla tua blocklist), api_service e un front_image_url firmato.

Valori di stato

Documenti con più sistemi di scrittura (latino / non latino)

Alcuni documenti — kirghisi, kazaki, russi, giapponesi, coreani, cinesi, arabi, thailandesi e altri — riportano il nome, l’indirizzo o il luogo di nascita del titolare sia in una traslitterazione in caratteri latini sia nel sistema di scrittura locale. Puoi scegliere quale sistema di scrittura popola la risposta di primo livello con l’impostazione del workflow (o dell’API autonoma) preferred_characters: I valori nel sistema di scrittura alternativo si trovano all’interno di extra_fields sotto chiavi con suffisso: first_name_non_latin, last_name_non_latin, middle_name_non_latin, full_name_non_latin, address_non_latin, place_of_birth_non_latin (o le corrispondenti varianti _latin).

Quando compaiono i campi nel sistema di scrittura alternativo

  • Solo quando entrambi i sistemi di scrittura sono effettivamente presenti sul documento. Se un campo OCR indicato come “Surname-Kyrgyz (Cyrillic)” viene estratto come testo in caratteri latini (omoglifi o una traslitterazione latina), non si qualifica come alternativa non latina e tale chiave viene omessa.
  • full_name_non_latin (e full_name_latin) vengono sempre ricostruiti dai singoli componenti di nome, secondo nome e cognome quando entrambi sono disponibili; il campo “Full Name” grezzo dell’OCR viene ignorato per coerenza.
  • Quando preferred_characters=latin ma il documento contiene solo testo non latino (quindi i campi di primo livello finiscono per essere non latini), Didit esegue un passaggio di traslitterazione ed espone first_name_latin, last_name_latin, middle_name_latin, full_name_latin, place_of_birth_latin e address_latin come alternativa latina.
last_name_non_latin è assente perché il campo “Surname (Cyrillic)” del documento è stato restituito in caratteri latini su questo campione; non c’era alcun cognome non latino autentico da estrarre.

Esempi

Approved — carta d’identità spagnola senza anomalie (tutti i campi)

In Review — QR non rilevato su un documento che dovrebbe averne uno

In forma abbreviata: una risposta reale contiene sempre la serie completa di campi mostrata sopra.

Nota sulla sicurezza

Gli URL firmati restituiti per le immagini e i video dei documenti sono temporanei: scadono dopo una finestra temporale limitata. Considerali di breve durata: scarica tempestivamente ciò di cui hai bisogno e non memorizzarli in cache né esporli pubblicamente. In genere, la tua applicazione ha bisogno solo di status, di una manciata di campi anagrafici e degli avvisi; memorizza il minor numero possibile di dati per ridurre al minimo la superficie di attacco in caso di violazione futura.

Correlati

Ultima modifica il 7 novembre 2026