> ## 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. # Confronto facciale: report JSON, punteggio di somiglianza > Il report di confronto facciale 1:1 di Didit include stato, punteggio di somiglianza, URL immagini, avvisi e dati nelle risposte API. ## 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](https://docs.didit.me/it/standalone-apis/face-match.md) 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](https://docs.didit.me/it/core-technology/age-estimation/overview.md#stima-dell’età-adattiva) 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](https://docs.didit.me/it/sessions-api/retrieve-session.md). * **Webhook** — i payload di `session.status.updated` includono lo stesso array `face_matches[]` una volta che il passaggio ha prodotto dati. Vedi [Webhook](https://docs.didit.me/it/integration/webhooks.md). * **API autonoma di confronto facciale** — per confronti diretti 1:1, vedi [API autonoma di confronto facciale](https://docs.didit.me/it/standalone-apis/face-match.md). > [!NOTE] > > 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](https://docs.didit.me/it/reference/data-models.md#confronto-facciale). 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](https://docs.didit.me/it/core-technology/face-match/warnings-face-match.md). | ## 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 ```json theme={null} { "face_matches": [ { "status": "Approved", "node_id": "feature_face_match_1", "score": 96.42, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [] } ] } ``` ### In revisione — somiglianza al limite ```json theme={null} { "face_matches": [ { "status": "In Review", "node_id": "feature_face_match_1", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///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 ```json theme={null} { "face_matches": [ { "status": "Declined", "node_id": "feature_face_match_1", "score": null, "source_image_session_id": null, "source_image": null, "target_image": "https:///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](https://docs.didit.me/it/core-technology/face-match/warnings-face-match.md) — enum completo degli avvisi, le cause e le misure correttive. * [Report sul rilevamento della vitalità](https://docs.didit.me/it/core-technology/liveness/report-liveness.md) — il passaggio a monte che acquisisce l'immagine target. * [Webhook](https://docs.didit.me/it/integration/webhooks.md) — resta in ascolto di `session.status.updated` per ricevere il report. * [Modelli di dati — Confronto facciale](https://docs.didit.me/it/reference/data-models.md#confronto-facciale) — schema canonico con ogni campo. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.