> ## 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.

# Informe de coincidència facial: JSON i puntuació

> Interpreta l'informe de coincidència facial 1:1 de Didit: estat, puntuació de similitud, URL d'imatges, advertències i dades a l'API.

## Visió general

L'**informe de coincidència facial** recull una comparació biomètrica 1:1 entre la selfie en directe capturada durant la prova de vida i una imatge de referència —més habitualment el retrat extret del document d'identitat. Retorna una única puntuació de similitud de 0 a 100, URL signades per a les dues imatges comparades, la sessió d'origen de la imatge de referència i qualsevol advertència generada per la coincidència.

L'informe es genera després que l'usuari completi tant el pas de prova de vida com el de document en un flux de treball (o, per a fluxos de treball basats en retrat com ara l'autenticació biomètrica, només després de la prova de vida), o directament mitjançant l'[API de coincidència facial](https://docs.didit.me/ca/standalone-apis/face-match.md) independent quan proporciones tu mateix dues imatges facials arbitràries.

Cada informe inclou el seu propi `status` —independent de l'estat general de la sessió— que reflecteix com s'ha resolt el pas de coincidència facial per si sol:

* **Aprovada** — `score` se situa per sobre del llindar de revisió i no s'ha activat cap advertència de rebuig automàtic.
* **En revisió** — `score` es troba entre els llindars de rebuig i de revisió, o no s'ha pogut calcular cap puntuació i `face_match_not_computed_action` és `REVIEW`.
* **Rebutjada** — `score` se situa en el llindar de rebuig o per sota, s'ha activat `NO_REFERENCE_IMAGE`, o no s'ha pogut calcular cap puntuació i `face_match_not_computed_action` és `DECLINE`.
* **Reenviament sol·licitat** — un revisor ha sol·licitat des de la consola que l'usuari torni a enviar aquest pas.
* **No finalitzat** — el pas de coincidència facial encara no ha generat cap resultat (inclòs mentre l'usuari reintenta una captura fallida).

## On apareix a les respostes de l'API

L'informe de coincidència facial s'envia dins de la matriu `face_matches[]` —**sempre una matriu JSON**, mai un objecte singular `face_match`. És `null` fins que almenys un pas de coincidència facial hagi generat dades, i apareixen múltiples entrades quan un flux de treball executa la coincidència facial més d'una vegada. Un flux de treball d'[Adaptive Age Verification](https://docs.didit.me/ca/core-technology/age-estimation/overview.md#estimació-d’edat-adaptativa) també l'omple quan s'executa l'alternativa de verificació d'identitat: aquesta entrada indica el node d'estimació d'edat com el seu `node_id`, ja que el flux de treball no té cap node de coincidència facial propi.

* **API de decisió de sessió** — `GET /v3/session/{sessionId}/decision/` retorna `face_matches[]` al nivell superior. Consulta [Recuperar la decisió de la sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md).
* **Webhooks** — els payloads de `session.status.updated` inclouen la mateixa matriu `face_matches[]` un cop el pas ha generat dades. Consulta [Webhooks](https://docs.didit.me/ca/integration/webhooks.md).
* **API independent de coincidència facial** — per a comparacions 1:1 directes, consulta l'[API independent de coincidència facial](https://docs.didit.me/ca/standalone-apis/face-match.md).

> [!NOTE]
>
> Llegeix `response.face_matches[0]` i itera per la matriu; l'estructura singular `face_match` a la qual feien referència alguns tutorials antics no existeix a l'endpoint de decisió v3.

## Esquema

L'esquema canònic camp per camp es troba a la pàgina de referència de [Models de dades](https://docs.didit.me/ca/reference/data-models.md#coincidència-facial). Els camps següents reflecteixen aquest esquema canònic.

| Camp | Tipus | Descripció |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Estat del pas de coincidència facial (`FeatureStatusChoices`). |
| `node_id` | string \| null | Node del graf del flux de treball que ha generat aquest informe. |
| `score` | number 0–100 \| null | Puntuació de similitud biomètrica, arrodonida a 2 decimals. `null` quan no ha estat possible fer cap comparació. |
| `source_image_session_id` | string \| null | UUID de la sessió el retrat emmagatzemat de la qual ha proporcionat la imatge de referència (origen); s'estableix en fluxos basats en retrat (autenticació biomètrica o un retrat proporcionat en crear la sessió). `null` quan la imatge de referència és el retrat del document capturat a la mateixa sessió. |
| `source_image` | string (URL signada) | La imatge de referència (normalment el retrat del document). URL signada de curta durada: descarrega-la ràpidament, no la persistisquis mai. |
| `target_image` | string (URL signada) | La imatge objectiu (normalment la selfie de la prova de vida). URL signada de curta durada: descarrega-la ràpidament, no la persistisquis mai. |
| `warnings[]` | array | Advertències a nivell de mòdul. Cada entrada inclou `feature` (sempre `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` i `node_id`; consulta [Advertències de coincidència facial](https://docs.didit.me/ca/core-technology/face-match/warnings-face-match.md). |

## Valors d'estat

| Estat | Significat | Efecte posterior |
| - | - | - |
| `Approved` | Puntuació per sobre del llindar de revisió i no s'ha activat cap advertència de rebuig automàtic. | Compta com a coincidència facial satisfactòria. |
| `In Review` | Puntuació per sobre del llindar de rebuig però en el llindar de revisió o per sota, o no s'ha pogut calcular cap puntuació (`FACE_MATCH_NOT_COMPUTED`, per exemple després d'una cerca sense document que no ha deixat cap referència) amb `face_match_not_computed_action` establert a `REVIEW`. | La sessió també passa a `In Review` fins que un revisor hi intervingui. |
| `Declined` | Puntuació en el llindar de rebuig o per sota, s'ha activat `NO_REFERENCE_IMAGE`, o no s'ha pogut calcular cap puntuació amb `face_match_not_computed_action` establert a `DECLINE`. | La sessió es rebutja tret que una altra branca aprovada compleixi el flux de treball. |
| `Resub Requested` | Un revisor ha sol·licitat reenviar aquest pas des de la consola. | Es demana a l'usuari que torni a fer la captura. |
| `Not Finished` | El pas de coincidència facial no ha generat cap resultat (mancava una entrada, el flux de treball mai ha arribat al pas de comparació o l'usuari encara es troba dins del cicle de reintent de captura). | La branca no s'ha completat. |

Les captures que fallen per baixa similitud es tornen a intentar abans que l'estat quedi fixat: l'usuari disposa de fins a `face_match_max_attempts` captures (3 per defecte), i només s'aplica la puntuació de l'últim intent. Les regles d'estat personalitzades configurades al node del flux de treball poden ajustar encara més l'estat resultant, combinant-se amb l'estat derivat de la puntuació sota la precedència `Declined` > `In Review` > `Approved`.

## Exemples

### Aprovada — coincidència clara

```json theme={null}
{
  "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": []
    }
  ]
}
```

### En revisió — similitud al límit

```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://<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"
        }
      ]
    }
  ]
}
```

### Rebutjada — sense imatge de referència per comparar

```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://<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 de seguretat

Les URL signades per a `source_image` i `target_image` són dades biomètriques i caduquen després d'una finestra de validesa curta. Tracta-les com a elements de curta durada: no les desis a la memòria cau ni les exposis públicament. Normalment la teva aplicació només necessita `status` i `score`: emmagatzema tan poc com sigui possible per minimitzar les dades biomètriques als teus servidors.

## Relacionat

* [Advertències de coincidència facial](https://docs.didit.me/ca/core-technology/face-match/warnings-face-match.md) — enum complet d'advertències, causes i resolució.
* [Informe de prova de vida](https://docs.didit.me/ca/core-technology/liveness/report-liveness.md) — el pas previ que captura la imatge objectiu.
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md) — escolta `session.status.updated` per rebre l'informe.
* [Models de dades — Coincidència facial](https://docs.didit.me/ca/reference/data-models.md#coincidència-facial) — esquema canònic amb tots els camps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.