Report vitalità: punteggio, metodo e corrispondenze

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.
Webhook — i payload di session.status.updated includono lo stesso array liveness_checks[] non appena il passaggio ha prodotto dati. Consulta Webhook.
API standalone per il rilevamento della vitalità — consulta API standalone per il rilevamento della vitalità.

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. 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à. Ciascuna voce segue la struttura dell’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

{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../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

{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../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://<media-host>/.../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à — enum completo degli avvisi, cause e risoluzione.
Webhook — resta in ascolto di session.status.updated per ricevere il report.
Modelli di dati — Controllo della vitalità — schema canonico con ogni campo.
Report di confronto facciale — il confronto facciale 1:1 complementare rispetto alla foto del documento.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report vitalità: punteggio, metodo e corrispondenze

Panoramica

Dove compare nelle risposte API

Schema

Corrispondenze facciali tra sessioni

Valori di stato

Esempi

Approved — acquisizione 3D attiva corretta

In Review — rilevamento passivo della vitalità, acquisizione di bassa qualità e possibile duplicato

Nota sulla sicurezza

Correlati

​Panoramica

​Dove compare nelle risposte API

​Schema

​Corrispondenze facciali tra sessioni

​Valori di stato

​Esempi

​Approved — acquisizione 3D attiva corretta

​In Review — rilevamento passivo della vitalità, acquisizione di bassa qualità e possibile duplicato

​Nota sulla sicurezza

​Correlati

Panoramica

Dove compare nelle risposte API

Schema

Corrispondenze facciali tra sessioni

Valori di stato

Esempi

Approved — acquisizione 3D attiva corretta

In Review — rilevamento passivo della vitalità, acquisizione di bassa qualità e possibile duplicato

Nota sulla sicurezza

Correlati