> ## 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. # Report di autenticazione biometrica: schema JSON > Analizza i report di autenticazione biometrica Didit con vitalità e confronto facciale opzionale tramite liveness_checks e face_matches. Il report di Autenticazione biometrica è il modo in cui Didit restituisce i risultati di una nuova verifica di un utente già registrato. Il workflow esegue un nuovo rilevamento della vitalità e, quando il Confronto facciale è abilitato nel workflow, un confronto facciale 1:1 rispetto al volto di riferimento determinato durante la creazione della sessione (il `portrait_image` da te fornito, oppure il volto memorizzato dell'utente cercato tramite `vendor_data`). Entrambi i controlli appaiono come elementi standard delle funzionalità nella risposta decisionale della sessione V3. ![Report di autenticazione biometrica Didit che combina il rilevamento della vitalità e il confronto facciale rispetto a un ritratto memorizzato](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/biometric-auth-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=c02e5558780972797d4b2feea685bc73) ## Panoramica L'Autenticazione biometrica è un tipo di workflow (`workflow_type: "biometric_authentication"`), non un oggetto di risposta separato. Quando il workflow viene eseguito genera: * Un **rilevamento della vitalità** che acquisisce un selfie dal vivo e gli assegna un punteggio in base alla presenza di spoofing. * Un **confronto facciale** che confronta il volto acquisito con il volto di riferimento determinato durante la creazione della sessione (solo quando il Confronto facciale è abilitato nel workflow). Ogni volta che il workflow include il Confronto facciale, la creazione della sessione necessita di un volto di riferimento. Invia `portrait_image` (immagine codificata in base64, max 2MB), oppure omettilo e Didit riutilizzerà il volto già memorizzato per l'utente identificato da `vendor_data`: prima un volto approvato da un rilevamento della vitalità, poi la foto dal chip del passaporto elettronico, poi il ritratto del documento d'identità, quindi un volto del profilo registrato manualmente. Se né `portrait_image` né un volto memorizzato sono disponibili, la creazione della sessione restituisce `400` con `{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}`. In entrambi i casi, il riferimento determinato viene registrato nella nuova sessione, quindi il campo `source_image_session_id` dell'elemento di confronto facciale viene impostato sul `session_id` della sessione stessa (questo indica che il riferimento proviene dal ritratto memorizzato della sessione anziché da un ritratto del documento acquisito nella stessa sessione, il che lascerebbe il campo `null`). ## Dove compare | Chiave nella risposta di decisione | Plurale | Schema dell'elemento | | - | - | - | | `liveness_checks[]` | Uno per passaggio di rilevamento della vitalità (solitamente 1 nell'autenticazione biometrica) | [data-models#liveness-check](https://docs.didit.me/it/reference/data-models.md#rilevamento-della-vitalità) | | `face_matches[]` | Uno per passaggio di confronto facciale (`null` nei workflow con solo rilevamento della vitalità) | [data-models#face-match](https://docs.didit.me/it/reference/data-models.md#confronto-facciale) | Entrambi gli array vengono restituiti da [`GET /v3/session/{sessionId}/decision/`](https://docs.didit.me/it/sessions-api/retrieve-session) per le sessioni il cui tipo di workflow è `biometric_authentication`. Sono sempre array — mai singoli oggetti — e ciascuno è `null` finché il relativo passaggio non ha prodotto dati. Ogni elemento include un `node_id` in modo che i workflow con più istanze possano distinguere i passaggi. ## Riferimento dello schema L'elenco completo dei campi è definito una sola volta nella pagina dei modelli dati, in modo che ogni report che mostra queste funzionalità condivida un'unica fonte di riferimento: * [Schema dell'elemento di rilevamento della vitalità](https://docs.didit.me/it/reference/data-models.md#rilevamento-della-vitalità) — `status`, `method`, `score`, `reference_image`, `video_url`, `age_estimation`, `matches[]`, `face_quality`, `face_luminance`, `warnings[]`, `node_id`. * [Schema dell'elemento di confronto facciale](https://docs.didit.me/it/reference/data-models.md#confronto-facciale) — `status`, `score`, `source_image_session_id`, `source_image`, `target_image`, `warnings[]`, `node_id`. * [Struttura della voce di avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) — `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`. ## Valori di stato Sia `liveness_checks[].status` sia `face_matches[].status` utilizzano il ciclo di vita condiviso delle funzionalità ([stati a livello di funzionalità](https://docs.didit.me/it/reference/data-models.md#stati-a-livello-di-funzionalità)): | Stato | Significato | | - | - | | `Not Finished` | Il passaggio non ha ancora prodotto un risultato finale (l'utente non l'ha completato o ha abbandonato la procedura). Prima ancora che un passaggio inizi, il relativo array è semplicemente `null` nella risposta di decisione. | | `Approved` | Il controllo ha superato tutte le soglie configurate. | | `In Review` | Il punteggio è rientrato nell'intervallo di revisione, oppure un avviso configurabile è stato impostato per la revisione. | | `Declined` | Il punteggio è sceso fino alla soglia di rifiuto o al di sotto, oppure è scattato un avviso di rifiuto automatico (attacco al volto, nessun volto rilevato, volto in blocklist, nessuna immagine di riferimento per il confronto facciale). | | `Resub Requested` | Un revisore ha richiesto all'utente di ripetere questo passaggio. | Lo `status` complessivo della sessione aggrega entrambi gli elementi: qualsiasi funzionalità con esito `Declined` comporta il rifiuto della sessione, qualsiasi in `In Review` imposta la sessione in `In Review`, altrimenti `Approved` (dopo che tutte le funzionalità sono state completate). Per il comportamento delle soglie e l'elenco completo dei codici di avviso, consulta gli [avvisi di Autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/warnings-biometric-authentication.md). ## Esempio — rilevamento della vitalità + confronto facciale (approvato) Gli esempi sono abbreviati: la risposta decisionale completa include anche `session_url`, `metadata`, `callback`, `reviews`, `contact_details`, `expected_details`, `environment`, `created_at` ed `expires_at`. ```json theme={null} { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "session_number": 1234, "status": "Approved", "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa", "features": ["LIVENESS", "FACE_MATCH"], "vendor_data": "user-123", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "PASSIVE", "score": 89.92, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": 92.4, "face_luminance": 58.1, "warnings": [] } ], "face_matches": [ { "node_id": "feature_face_match", "status": "Approved", "score": 88.47, "source_image_session_id": "11111111-2222-3333-4444-555555555555", "source_image": "https:///.../source.jpg", "target_image": "https:///.../target.jpg", "warnings": [] } ], "id_verifications": null, "nfc_verifications": null, "poa_verifications": null, "phone_verifications": null, "email_verifications": null, "aml_screenings": null } ``` ## Esempio — solo rilevamento della vitalità (Confronto facciale disabilitato nel workflow) ```json theme={null} { "session_id": "22222222-3333-4444-5555-666666666666", "session_kind": "user", "status": "Approved", "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb", "features": ["LIVENESS"], "vendor_data": "user-456", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "ACTIVE_3D", "score": 96.10, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": null, "face_luminance": null, "warnings": [] } ], "face_matches": null } ``` La modalità con solo rilevamento della vitalità è una configurazione del workflow: quando il Confronto facciale è disabilitato, non è necessario alcun volto di riferimento durante la creazione della sessione e `face_matches` rimane `null`. Quando il Confronto facciale **è** abilitato, l'omissione di `portrait_image` non esegue un fallback al solo rilevamento della vitalità: Didit riutilizza il volto memorizzato per l'utente identificato da `vendor_data`, e se non esiste alcun volto memorizzato la creazione della sessione fallisce con `400`. ## Esempio — confronto facciale rifiutato per bassa somiglianza ```json theme={null} { "session_id": "33333333-4444-5555-6666-777777777777", "status": "Declined", "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa", "liveness_checks": [ { "node_id": "feature_liveness", "status": "Approved", "method": "PASSIVE", "score": 91.20, "reference_image": "https:///.../reference.jpg", "video_url": "https:///.../video.mp4", "age_estimation": null, "matches": [], "face_quality": 90.15, "face_luminance": 55.30, "warnings": [] } ], "face_matches": [ { "node_id": "feature_face_match", "status": "Declined", "score": 41.18, "source_image_session_id": "33333333-4444-5555-6666-777777777777", "source_image": "https:///.../source.jpg", "target_image": "https:///.../target.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "error", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match" } ] } ] } ``` ## Nota sulla sicurezza `reference_image`, `video_url`, `source_image` e `target_image` sono URL firmati che scadono dopo una finestra di validità limitata (4 ore per impostazione predefinita). Puntano a dati biometrici: non memorizzarli nella cache né esporli pubblicamente. Conserva il risultato della verifica (stato, punteggio, `source_image_session_id`) dal tuo lato; chiama nuovamente l'endpoint decisionale se hai bisogno di URL aggiornati. ## Correlati > [card] [Avvisi di Autenticazione biometrica](https://docs.didit.me/it/core-technology/biometric-auth/warnings-biometric-authentication.md) > > Codici di avviso, soglie e condizioni di rifiuto automatico. > [card] [Report sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/report-liveness.md) > > Riferimento completo dei campi per gli elementi di `liveness_checks[]`. > [card] [Report sul Confronto facciale](https://docs.didit.me/it/core-technology/face-match/report-face-match.md) > > Riferimento completo dei campi per gli elementi di `face_matches[]`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.