> ## 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 vitalità: punteggio, metodo e corrispondenze > Scopri il report Didit sul rilevamento della vitalità: stato, punteggio di affidabilità, metodo, stima dell'età e corrispondenze tra sessioni. ## Panoramica Il **report di rilevamento della vitalità** raccoglie tutto ciò che Didit ha osservato durante la verifica che davanti alla fotocamera fosse presente una persona reale e in carne e ossa — non una foto stampata, la riproduzione su uno schermo o un deepfake. Include il metodo di rilevamento della vitalità, un punteggio di affidabilità da 0 a 100, il selfie di riferimento e il video di acquisizione, una stima dell'età opzionale, le metriche di qualità del rilevamento passivo della vitalità e i confronti facciali tra sessioni diverse rispetto allo storico della tua applicazione e alla blocklist. Il report viene generato dopo che l'utente completa il passaggio di rilevamento della vitalità in un workflow (oppure chiama l'endpoint facciale autonomo). Didit esegue uno dei tre metodi di rilevamento della vitalità (3D attivo, flashing o passivo), assegna un punteggio all'acquisizione, effettua uno screening per individuare pattern di spoofing noti e confronta il volto biometricamente con ogni altro volto registrato nella tua applicazione. Ogni report include un proprio `status` — indipendente dallo stato generale della sessione — che riflette l'esito del solo passaggio di rilevamento della vitalità: * **Approvata** — volto rilevato, punteggio di vitalità superiore alla soglia di revisione, nessun avviso di rifiuto automatico attivato. * **In revisione** — sono stati attivati uno o più avvisi instradati alla revisione, oppure il punteggio è pari o inferiore alla soglia di revisione ma superiore a quella di rifiuto. * **Rifiutata** — è stata attivata una condizione di rifiuto automatico (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` o i rischi legati all'età nei flussi di stima dell'età), un avviso configurabile è stato instradato al rifiuto oppure il punteggio è pari o inferiore alla soglia di rifiuto. * **Non completato** — l'utente non ha mai completato il passaggio di rilevamento della vitalità. ## Dove compare nelle risposte API Il report di rilevamento della vitalità compare come `liveness_checks[]` in `GET /v3/session/{sessionId}/decision/` — **sempre come array JSON**, mai come singolo oggetto `liveness`. Vengono visualizzate più voci quando un workflow esegue il rilevamento della vitalità più di una volta (ad esempio un controllo principale e una nuova acquisizione). * **API di decisione della sessione** — `GET /v3/session/{sessionId}/decision/` restituisce `liveness_checks[]` al livello principale. Consulta [Recupera la decisione della sessione](https://docs.didit.me/it/sessions-api/retrieve-session.md). * **Webhook** — i payload di `session.status.updated` includono lo stesso array `liveness_checks[]` non appena il passaggio ha prodotto dati. Consulta [Webhook](https://docs.didit.me/it/integration/webhooks.md). * **API standalone per il rilevamento della vitalità** — consulta [API standalone per il rilevamento della vitalità](https://docs.didit.me/it/standalone-apis/passive-liveness.md). > [!NOTE] > > Leggi `response.liveness_checks[0]` e itera sull'array — la struttura singolare `liveness` a cui facevano riferimento alcuni tutorial meno recenti non esiste sull'endpoint di decisione v3. ## Schema Lo schema canonico campo per campo si trova nella pagina di riferimento [Modelli di dati](https://docs.didit.me/it/reference/data-models.md#rilevamento-della-vitalità). I campi sottostanti rispecchiano tale schema canonico. | Campo | Tipo | Descrizione | | - | - | - | | `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Stato del passaggio di rilevamento della vitalità (vedere sotto). | | `node_id` | string \| null | Nodo del grafo del workflow che ha generato questo report. | | `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | Il metodo di rilevamento della vitalità che ha prodotto questa acquisizione. | | `score` | number 0–100 \| null | Punteggio di affidabilità del rilevamento della vitalità, arrotondato a 2 decimali. | | `reference_image` | string (URL firmato) \| null | Selfie di riferimento estratto dall'acquisizione. URL firmato con una finestra temporale di validità limitata. | | `video_url` | string (URL firmato) \| null | Video completo dell'acquisizione della vitalità (metodi attivi). URL firmato con una finestra temporale di validità limitata. | | `age_estimation` | number \| null | Età stimata in anni del volto più grande presente nell'immagine di riferimento. | | `face_quality` | number 0–100 \| null | Qualità del volto per il rilevamento passivo della vitalità, normalizzata in percentuale. Valorizzato solo quando `method = "PASSIVE"`. | | `face_luminance` | number 0–100 \| null | Luminanza facciale per il rilevamento passivo della vitalità, normalizzata da 0–255 in percentuale. Valorizzato solo quando `method = "PASSIVE"`. | | `matches[]` | array | Corrispondenze facciali tra sessioni (vedere sotto). | | `warnings[]` | array | Avvisi a livello di modulo — vedere [Avvisi di rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md). Ciascuna voce segue la struttura dell'[Oggetto avviso](https://docs.didit.me/it/reference/data-models.md#oggetto-avviso) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). | ### Corrispondenze facciali tra sessioni `matches[]` elenca i volti nella cronologia della tua applicazione che hanno superato la soglia di somiglianza biometrica rispetto a questo selfie — fino a 5 voci, con i volti presenti in blocklist e allowlist per primi, seguiti poi dai volti in ordine decrescente di somiglianza. I candidati idonei sono volti in blocklist, volti in allowlist, volti da sessioni `Approved` e volti importati associati ai tuoi utenti vendor. I volti appartenenti allo stesso utente (stesso `vendor_data` o stesso utente vendor, se disponibile) sono esclusi dall'**intera** ricerca — sia per il rilevamento dei duplicati che per lo screening delle blocklist. Ciascuna voce include: | Campo | Tipo | Descrizione | | - | - | - | | `session_id` | string (UUID) \| null | La sessione corrispondente. `null` quando `source` è `imported` o `list_entry`. | | `session_number` | number \| null | Numero sequenziale di sessione per la sessione corrispondente. `null` per origini diverse da una sessione. | | `similarity_percentage` | number 0–100 | Punteggio di somiglianza biometrica, vincolato a 0–100. | | `vendor_data` | string \| null | I tuoi dati di riferimento della sessione corrispondente (o dell'utente vendor, per i volti importati). | | `verification_date` | string (ISO 8601) \| null | Quando è stata creata la sessione corrispondente (o il volto importato). | | `user_details` | object \| null | `{ full_name, document_type, document_number }` dal KYC della sessione corrispondente. I volti importati valorizzano solo `full_name` (i due campi relativi al documento sono `null`); `null` quando non ci sono dettagli registrati. | | `match_image_url` | string (URL firmato) \| null | Volto di riferimento dalla sessione corrispondente, volto importato o voce di elenco. | | `status` | string \| null | Stato della sessione corrispondente (ad es. `"Approved"`). `null` per origini diverse da una sessione. | | `is_blocklisted` | boolean | `true` quando il volto corrispondente si trova nella tua blocklist dei volti. | | `is_allowlisted` | boolean | `true` quando il volto corrispondente si trova nella tua allowlist dei volti (le azioni per volti duplicati vengono ignorate). | | `api_service` | string \| null | Impostato quando il volto corrispondente proviene da una chiamata API autonoma (ad es. `"PASSIVE_LIVENESS"`); `null` per le sessioni di workflow e per origini diverse da una sessione. | | `source` | `"session" \| "imported" \| "list_entry"` | Origine del volto corrispondente: un'altra sessione di verifica, un volto caricato per un utente vendor o un volto inserito in una allowlist o blocklist gestita dall'organizzazione. | ## Valori di stato Gli stati provengono dall'enum condiviso di stato delle funzionalità (`FeatureStatusChoices`). | Stato | Significato | Effetto a valle | | - | - | - | | `Approved` | Volto rilevato, punteggio di vitalità superiore alla soglia di revisione, nessun avviso di rifiuto automatico attivato. | Vale come controllo di vitalità riuscito. | | `In Review` | Punteggio pari o inferiore alla soglia di revisione ma superiore alla soglia di rifiuto, oppure è stato attivato un avviso instradato alla revisione. | Anche la sessione passa a `In Review` fino all'intervento di un revisore. | | `Declined` | È stato attivato un rischio con rifiuto automatico (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` o i rischi legati all'età nei flussi di stima dell'età), un avviso configurabile è stato instradato al rifiuto oppure il punteggio è pari o inferiore alla soglia di rifiuto. | La sessione viene rifiutata, a meno che un altro ramo approvato non soddisfi il workflow. | | `Not Finished` | L'utente ha abbandonato il passaggio di rilevamento della vitalità (oppure un errore di acquisizione per il quale è possibile effettuare un nuovo tentativo è in attesa di tale tentativo). | Il ramo del rilevamento della vitalità non ha prodotto alcun risultato. | | `Resub Requested` | Un revisore ha richiesto il reinvio di questo passaggio dalla console. | Transitorio — sostituito una volta che l'utente effettua nuovamente l'acquisizione. | ## Esempi ### Approved — acquisizione 3D attiva corretta ```json theme={null} { "liveness_checks": [ { "status": "Approved", "node_id": "liveness_primary", "method": "ACTIVE_3D", "score": 92.4, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": "https:///.../liveness.mp4?signature=...", "age_estimation": 24.3, "face_quality": null, "face_luminance": null, "matches": [], "warnings": [] } ] } ``` ### In Review — rilevamento passivo della vitalità, acquisizione di bassa qualità e possibile duplicato ```json theme={null} { "liveness_checks": [ { "status": "In Review", "node_id": "liveness_primary", "method": "PASSIVE", "score": 76.1, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": 31.0, "face_quality": 12.4, "face_luminance": 18.7, "matches": [ { "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f", "session_number": 123, "similarity_percentage": 96.8, "vendor_data": "user-555", "verification_date": "2024-07-15T10:23:45Z", "user_details": { "full_name": "John Smith", "document_type": "Passport", "document_number": "SAMPLE-DOC-12345" }, "match_image_url": "https:///.../matched.jpg?signature=...", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session" } ], "warnings": [ { "feature": "LIVENESS", "risk": "LOW_FACE_QUALITY", "additional_data": null, "log_type": "warning", "short_description": "Low face quality", "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "LOW_FACE_LUMINANCE", "additional_data": null, "log_type": "warning", "short_description": "Low face luminance", "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.", "node_id": "liveness_primary" }, { "feature": "LIVENESS", "risk": "POSSIBLE_DUPLICATED_FACE", "additional_data": { "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f", "duplicated_session_number": 123, "api_service": null }, "log_type": "warning", "short_description": "Possible duplicated face from other approved session", "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.", "node_id": "liveness_primary" } ] } ] } ``` In questo caso, la qualità del volto (12.4) è inferiore alla soglia predefinita di revisione (15), la luminanza (18.7) è inferiore al minimo predefinito (20) e l'azione per volti duplicati del workflow è impostata su Review — pertanto tutti e tre gli avvisi contengono `log_type: "warning"` e il report risulta `In Review`. ## Nota sulla sicurezza I video del rilevamento della vitalità e i selfie sono dati biometrici — gli URL firmati sono temporanei e scadono (dopo 4 ore per impostazione predefinita). Trattali come risorse di breve durata: non memorizzarli nella cache né esporli pubblicamente. In genere la tua applicazione ha bisogno solo di `status`, `score` e dei relativi avvisi — memorizza il meno possibile per ridurre al minimo i dati biometrici sui tuoi server. ## Correlati * [Avvisi sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/warnings-liveness.md) — enum completo degli avvisi, cause e risoluzione. * [Webhook](https://docs.didit.me/it/integration/webhooks.md) — resta in ascolto di `session.status.updated` per ricevere il report. * [Modelli di dati — Controllo della vitalità](https://docs.didit.me/it/reference/data-models.md#rilevamento-della-vitalità) — schema canonico con ogni campo. * [Report di confronto facciale](https://docs.didit.me/it/core-technology/face-match/report-face-match.md) — il confronto facciale 1:1 complementare rispetto alla foto del documento. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.