Report di autenticazione biometrica: schema JSON

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

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
`face_matches[]`	Uno per passaggio di confronto facciale (`null` nei workflow con solo rilevamento della vitalità)	data-models#face-match

Entrambi gli array vengono restituiti da GET /v3/session/{sessionId}/decision/ 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à — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Schema dell’elemento di confronto facciale — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Struttura della voce di 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à):

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.

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.

{
  "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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../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)

{
  "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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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

{
  "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://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../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://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../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

Avvisi di Autenticazione biometrica

Codici di avviso, soglie e condizioni di rifiuto automatico.

Report sul rilevamento della vitalità

Riferimento completo dei campi per gli elementi di liveness_checks[].

Report sul Confronto facciale

Riferimento completo dei campi per gli elementi di face_matches[].

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report di autenticazione biometrica: schema JSON

Panoramica

Dove compare

Riferimento dello schema

Valori di stato

Esempio — rilevamento della vitalità + confronto facciale (approvato)

Esempio — solo rilevamento della vitalità (Confronto facciale disabilitato nel workflow)

Esempio — confronto facciale rifiutato per bassa somiglianza

Nota sulla sicurezza

Correlati

Avvisi di Autenticazione biometrica

Report sul rilevamento della vitalità

Report sul Confronto facciale

​Panoramica

​Dove compare

​Riferimento dello schema

​Valori di stato

​Esempio — rilevamento della vitalità + confronto facciale (approvato)

​Esempio — solo rilevamento della vitalità (Confronto facciale disabilitato nel workflow)

​Esempio — confronto facciale rifiutato per bassa somiglianza

​Nota sulla sicurezza

​Correlati

Avvisi di Autenticazione biometrica

Report sul rilevamento della vitalità

Report sul Confronto facciale

Panoramica

Dove compare

Riferimento dello schema

Valori di stato

Esempio — rilevamento della vitalità + confronto facciale (approvato)

Esempio — solo rilevamento della vitalità (Confronto facciale disabilitato nel workflow)

Esempio — confronto facciale rifiutato per bassa somiglianza

Nota sulla sicurezza

Correlati