Confronto facciale: report JSON, punteggio di somiglianza

Panoramica

Il report di confronto facciale acquisisce un confronto biometrico 1:1 tra il selfie dal vivo acquisito durante il rilevamento della vitalità e un’immagine di riferimento, più comunemente la fototessera estratta dal documento d’identità. Restituisce un singolo punteggio di somiglianza da 0 a 100, URL firmati per le due immagini confrontate, la sessione di origine per l’immagine di riferimento ed eventuali avvisi generati dal confronto. Il report viene generato dopo che l’utente ha completato sia il passaggio di rilevamento della vitalità sia quello del documento in un workflow (oppure, per i workflow basati su fototessera come l’autenticazione biometrica, solo dopo la vitalità), o direttamente tramite l’API autonoma di confronto facciale quando fornisci tu stesso due immagini facciali arbitrarie. Ogni report include un proprio status, indipendente dallo stato generale della sessione, che riflette l’esito del solo passaggio di confronto facciale:

Approvato — score è superiore alla soglia di revisione e non è scattato alcun avviso di rifiuto automatico.
In revisione — score è compreso tra la soglia di rifiuto e quella di revisione, oppure non è stato possibile calcolare alcun punteggio e face_match_not_computed_action è impostato su REVIEW.
Rifiutato — score è pari o inferiore alla soglia di rifiuto, è scattato NO_REFERENCE_IMAGE, oppure non è stato possibile calcolare alcun punteggio e face_match_not_computed_action è impostato su DECLINE.
Nuova richiesta di invio — un revisore ha richiesto che l’utente invii nuovamente questo passaggio dalla console.
Non completato — il passaggio di confronto facciale non ha ancora prodotto un risultato (incluso il caso in cui l’utente stia ritentando un’acquisizione non riuscita).

Dove compare nelle risposte API

Il report di confronto facciale è incluso all’interno dell’array face_matches[] — sempre un array JSON, mai un singolo oggetto face_match. È null finché almeno un passaggio di confronto facciale non ha prodotto dati, e compaiono più voci quando un workflow esegue il confronto facciale più di una volta. Anche un workflow di Adaptive Age Verification lo compila quando viene eseguito il fallback con verifica dell’identità: tale voce riporta il nodo di stima dell’età come proprio node_id, poiché il workflow non include un nodo di confronto facciale dedicato.

API di decisione della sessione — GET /v3/session/{sessionId}/decision/ restituisce face_matches[] al livello principale. Vedi Recupera la decisione della sessione.
Webhook — i payload di session.status.updated includono lo stesso array face_matches[] una volta che il passaggio ha prodotto dati. Vedi Webhook.
API autonoma di confronto facciale — per confronti diretti 1:1, vedi API autonoma di confronto facciale.

Leggi response.face_matches[0] e itera sull’array: la struttura singolare face_match a cui facevano riferimento alcuni vecchi tutorial 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" \| "Resub Requested" \| "Not Finished"`	Stato del passaggio di confronto facciale (`FeatureStatusChoices`).
`node_id`	string \| null	Nodo del grafo del workflow che ha prodotto questo report.
`score`	number 0–100 \| null	Punteggio di somiglianza biometrica, arrotondato a 2 decimali. `null` quando non è stato possibile effettuare alcun confronto.
`source_image_session_id`	string \| null	UUID della sessione la cui fototessera memorizzata ha fornito l’immagine di riferimento (di origine), impostato nei flussi basati su fototessera (autenticazione biometrica o fototessera fornita alla creazione della sessione). `null` quando l’immagine di riferimento è la fototessera del documento acquisita nella stessa sessione.
`source_image`	string (URL firmato)	L’immagine di riferimento (generalmente la fototessera del documento). URL firmato di breve durata: scarica tempestivamente, non memorizzare mai l’URL in modo persistente.
`target_image`	string (URL firmato)	L’immagine di destinazione (generalmente il selfie del rilevamento della vitalità). URL firmato di breve durata: scarica tempestivamente, non memorizzare mai l’URL in modo persistente.
`warnings[]`	array	Avvisi a livello di modulo. Ogni voce contiene `feature` (sempre `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` e `node_id` — vedi Avvisi di confronto facciale.

Valori di stato

Stato	Significato	Effetto a valle
`Approved`	Punteggio superiore alla soglia di revisione e nessun avviso di rifiuto automatico attivato.	Viene conteggiato come un confronto facciale riuscito.
`In Review`	Punteggio superiore alla soglia di rifiuto ma pari o inferiore alla soglia di revisione, oppure non è stato possibile calcolare alcun punteggio (`FACE_MATCH_NOT_COMPUTED`, ad esempio dopo una ricerca non documentale che non ha lasciato alcuna immagine di riferimento) con `face_match_not_computed_action` impostato su `REVIEW`.	Anche la sessione passa a `In Review` fino all’intervento di un revisore.
`Declined`	Punteggio pari o inferiore alla soglia di rifiuto, `NO_REFERENCE_IMAGE` attivato, oppure non è stato possibile calcolare alcun punteggio con `face_match_not_computed_action` impostato su `DECLINE`.	La sessione viene rifiutata a meno che un altro ramo approvato non soddisfi il workflow.
`Resub Requested`	Un revisore ha richiesto il reinvio di questo passaggio dalla console.	All’utente viene richiesto di ripetere l’acquisizione.
`Not Finished`	Il passaggio di confronto facciale non ha prodotto un risultato (mancava un input, il workflow non ha mai raggiunto il passaggio di confronto, o l’utente si trova ancora nel ciclo di nuovi tentativi di acquisizione).	Il ramo non è stato completato.

I fallimenti dovuti a bassa somiglianza prevedono nuovi tentativi prima che lo stato diventi definitivo: l’utente ha a disposizione fino a face_match_max_attempts acquisizioni (3 per impostazione predefinita), e viene applicato solo il punteggio dell’ultimo tentativo. Le regole di stato personalizzate configurate sul nodo del workflow possono modificare ulteriormente lo stato risultante, combinandosi con lo stato derivato dal punteggio secondo la precedenza Declined > In Review > Approved.

Esempi

Approvato — corrispondenza netta

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

In revisione — somiglianza al limite

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "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"
        }
      ]
    }
  ]
}

Rifiutato — nessuna immagine di riferimento con cui effettuare il confronto

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "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"
        }
      ]
    }
  ]
}

Nota sulla sicurezza

Gli URL firmati per source_image e target_image costituiscono dati biometrici e scadono dopo un breve intervallo di validità. Trattali come temporanei: non memorizzarli nella cache né esporli pubblicamente. In genere la tua applicazione ha bisogno solo di status e score: memorizza la minor quantità possibile di informazioni per ridurre al minimo i dati biometrici sui tuoi server.

Correlati

Avvisi sul confronto facciale — enum completo degli avvisi, le cause e le misure correttive.
Report sul rilevamento della vitalità — il passaggio a monte che acquisisce l’immagine target.
Webhook — resta in ascolto di session.status.updated per ricevere il report.
Modelli di dati — Confronto facciale — schema canonico con ogni campo.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Confronto facciale: report JSON, punteggio di somiglianza

Panoramica

Dove compare nelle risposte API

Schema

Valori di stato

Esempi

Approvato — corrispondenza netta

In revisione — somiglianza al limite

Rifiutato — nessuna immagine di riferimento con cui effettuare il confronto

Nota sulla sicurezza

Correlati

​Panoramica

​Dove compare nelle risposte API

​Schema

​Valori di stato

​Esempi

​Approvato — corrispondenza netta

​In revisione — somiglianza al limite

​Rifiutato — nessuna immagine di riferimento con cui effettuare il confronto

​Nota sulla sicurezza

​Correlati

Panoramica

Dove compare nelle risposte API

Schema

Valori di stato

Esempi

Approvato — corrispondenza netta

In revisione — somiglianza al limite

Rifiutato — nessuna immagine di riferimento con cui effettuare il confronto

Nota sulla sicurezza

Correlati