Avvisi e codici di errore del Confronto facciale

Panoramica

Gli avvisi nel report di confronto facciale segnalano ogni condizione rilevata da Didit durante l’esecuzione del confronto facciale 1:1. Vengono inseriti nell’array warnings[] di ogni elemento di face_matches[] (vedi Report di confronto facciale). Ciascuna voce include anche feature: "FACEMATCH" e il node_id del nodo del workflow che l’ha generata. Ogni avviso si articola su tre livelli:

Il codice risk — un identificatore stabile su cui puoi basare i controlli nel tuo codice.
Il log_type — information, warning o error, derivato dalle soglie del punteggio di similarità del tuo workflow.
L’impatto sulla decisione — determinato dalle soglie di revisione e rifiuto del workflow per il punteggio di similarità.

Il modulo di confronto facciale è intenzionalmente essenziale — esistono esattamente cinque codici di rischio, elencati di seguito per intero.

Condizioni di rifiuto automatico

Il seguente rischio impone sempre lo stato Declined per il report di confronto facciale (e per la sessione):

Rischio	Trigger
`NO_REFERENCE_IMAGE`	Manca `source_image` (riferimento) oppure `target_image` (selfie), rendendo impossibile qualsiasi confronto.

Quando scatta NO_REFERENCE_IMAGE, LOW_FACE_MATCH_SIMILARITY viene soppresso (non c’è nulla a cui assegnare un punteggio). C’è un’eccezione. Quando il passaggio di verifica dell’identità è stato completato tramite una ricerca non documentale il cui registro non restituisce alcun ritratto e non verifica alcun volto, il confronto facciale non ha nulla con cui confrontare l’acquisizione dal vivo per progettazione. Questo caso viene segnalato come FACE_MATCH_NOT_COMPUTED con un punteggio null e deciso da face_match_not_computed_action (di seguito), e non come rifiuto automatico.

Impostazioni di verifica configurabili

Nella console Didit, il punteggio di similarità del confronto facciale è regolato da due soglie (nessun selettore Approva/Revisione/Rifiuta):

Impostazione	Valore predefinito	Comportamento
`face_match_score_review_threshold`	70	Quando `score` ≤ questo valore, scatta `LOW_FACE_MATCH_SIMILARITY` e lo stato passa a `In Review`.
`face_match_score_decline_threshold`	50	Quando `score` ≤ questo valore, lo stesso avviso passa a `error` e lo stato si sposta su `Declined`.

Aumenta la soglia di revisione se riscontri troppe approvazioni false; abbassa la soglia di rifiuto se riscontri troppi rifiuti falsi. Un’impostazione separata controlla cosa accade quando un punteggio di similarità non può essere calcolato affatto: non è stato rilevato alcun volto in una delle immagini oppure una ricerca non documentale non ha lasciato alcun riferimento con cui effettuare il confronto:

Impostazione	Valore predefinito	Comportamento
`face_match_not_computed_action`	`REVIEW`	Azione applicata una volta che l’esito “impossibile calcolare” diventa definitivo. `REVIEW` invia il report a `In Review`; `DECLINE` lo imposta su `Declined`. (Non è prevista alcuna opzione di approvazione automatica — un punteggio mai calcolato non viene mai approvato silenziosamente.)

Questa azione gestisce FACE_MATCH_NOT_COMPUTED (nessun volto nel ritratto del documento, o nessun riferimento dopo una ricerca non documentale) e un caso NO_FACE_IN_SELFIE esaurito (nessun volto nel selfie dopo i nuovi tentativi dell’utente). Quando il problema è il selfie, all’utente viene prima chiesto di effettuare una nuova acquisizione — vedi sotto — e l’azione si applica solo se il volto continua a non essere rilevato una volta esaurito il numero massimo di tentativi a disposizione. Anche i fallimenti per bassa similarità entrano in un ciclo di tentativi di acquisizione prima che lo stato diventi definitivo: l’utente ha a disposizione fino a face_match_max_attempts tentativi totali (valore predefinito 3, configurabile tra 2 e 5 per nodo del workflow) per ripetere l’acquisizione. Un fallimento NO_FACE_IN_SELFIE utilizza lo stesso ciclo di nuovi tentativi, poiché l’acquisizione di un selfie più nitido può risolvere il problema. Un fallimento FACE_MATCH_NOT_COMPUTED non prevede nuovi tentativi — il ritratto del documento non può essere riacquisito in questo passaggio. Solo quando i tentativi a disposizione sono esauriti viene applicato lo stato dell’ultimo tentativo — e viene registrato FACE_MATCH_MAX_ATTEMPTS_EXCEEDED. Sull’API Face Match autonoma esiste solo una soglia di rifiuto (opzione della richiesta face_match_score_decline_threshold, valore predefinito 30); qualsiasi avviso attivato rifiuta la richiesta, e NO_REFERENCE_IMAGE scatta quando non è stato possibile confrontare alcun volto.

Avvisi generati

Rischio	Causa	Gravità	Influisce sullo stato?	Rimedio
`LOW_FACE_MATCH_SIMILARITY`	`score` ≤ `face_match_score_review_threshold`. Soppresso quando è presente anche `NO_REFERENCE_IMAGE`.	`warning` tra le soglie; `error` alla soglia di rifiuto o al di sotto di essa	`In Review` tra le soglie; `Declined` alla soglia di rifiuto o al di sotto di essa	Modifica le soglie oppure accetta tramite revisione manuale.
`FACE_MATCH_NOT_COMPUTED`	Non è stato possibile calcolare un punteggio di somiglianza perché non è stato rilevato alcun volto nella foto del documento, oppure perché il passaggio ID era una ricerca senza documento che non ha lasciato alcun riferimento con cui effettuare il confronto (un registro che non restituisce foto e non verifica volti). Soppresso quando è presente anche `NO_REFERENCE_IMAGE`.	`warning` quando `face_match_not_computed_action` è `REVIEW`; `error` quando è `DECLINE`	`In Review` o `Declined`, in base a `face_match_not_computed_action`	L’immagine del documento non può essere riacquisita in questo passaggio: risolvi tramite revisione manuale, oppure riacquisisci il documento prima nel flusso. Dopo una ricerca basata solo sui dati, imposta `face_match_not_computed_action` sull’esito desiderato, oppure richiedi un documento nei paesi in cui il confronto biometrico è fondamentale.
`NO_FACE_IN_SELFIE`	Non è stato possibile calcolare un punteggio di somiglianza perché non è stato rilevato alcun volto nel selfie dell’utente. All’utente viene chiesto di ripetere il selfie prima che questo esito diventi definitivo.	`warning` quando `face_match_not_computed_action` è `REVIEW`; `error` quando è `DECLINE`	`In Review` o `Declined`, in base a `face_match_not_computed_action`, una volta esauriti i tentativi	L’utente acquisisce nuovamente un selfie più nitido, ben illuminato e frontale.
`NO_REFERENCE_IMAGE`	Manca l’immagine di riferimento o l’immagine di destinazione (a eccezione di un riferimento mai prodotto da una ricerca senza documento, che genera invece `FACE_MATCH_NOT_COMPUTED`).	`error`	Rifiuto automatico	Assicurati che vengano acquisiti sia la foto del documento sia il selfie per il rilevamento della vitalità. Per l’API autonoma, passa due immagini di volti valide.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	L’utente ha esaurito il numero massimo di nuovi tentativi di acquisizione (`face_match_max_attempts`) a seguito di ripetuti fallimenti per bassa somiglianza.	`information`	No — registra che è stato applicato lo stato calcolato dell’ultimo tentativo (rifiuto o revisione)	Aumenta `face_match_max_attempts` sul nodo del workflow, oppure risolvi tramite revisione manuale.

Esempi

In revisione — somiglianza al limite

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "warning",
    "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_1"
  }
]

In revisione — impossibilità di calcolare il confronto facciale

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

Rifiuto automatico — riferimento mancante

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]

Tentativi esauriti — applicato lo stato dell’ultimo tentativo

"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_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]

L’API del confronto facciale autonoma restituisce la stessa struttura di avvisi senza node_id (il confronto non è vincolato a un nodo del workflow).

Tipi di avviso

A ciascun rischio viene assegnata una gravità in base alla configurazione della tua applicazione. Le tre gravità sono:

Correlati

Report del confronto facciale — schema completo del report e stati.
Avvisi sul rilevamento della vitalità — avvisi a monte sull’acquisizione del selfie.
Webhook — session.status.updated include gli avvisi non appena il passaggio termina.
Modelli di dati — Confronto facciale — schema canonico.
Modelli di dati — Oggetto avviso — la struttura di ciascuna voce in warnings[].

Autenticazione

Verifica

Monitoraggio

Piattaforma

Avvisi e codici di errore del Confronto facciale

Panoramica

Condizioni di rifiuto automatico

Impostazioni di verifica configurabili

Avvisi generati

Esempi

In revisione — somiglianza al limite

In revisione — impossibilità di calcolare il confronto facciale

Rifiuto automatico — riferimento mancante

Tentativi esauriti — applicato lo stato dell’ultimo tentativo

Tipi di avviso

Correlati

​Panoramica

​Condizioni di rifiuto automatico

​Impostazioni di verifica configurabili

​Avvisi generati

​Esempi

​In revisione — somiglianza al limite

​In revisione — impossibilità di calcolare il confronto facciale

​Rifiuto automatico — riferimento mancante

​Tentativi esauriti — applicato lo stato dell’ultimo tentativo

​Tipi di avviso

​Correlati

Panoramica

Condizioni di rifiuto automatico

Impostazioni di verifica configurabili

Avvisi generati

Esempi

In revisione — somiglianza al limite

In revisione — impossibilità di calcolare il confronto facciale

Rifiuto automatico — riferimento mancante

Tentativi esauriti — applicato lo stato dell’ultimo tentativo

Tipi di avviso

Correlati