> ## 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 prova de vida: puntuació i coincidències

> Llegeix l'informe de prova de vida de Didit: estat, puntuació de confiança, mètode de detecció, estimació d'edat, coincidències i respostes.

## Visió general

L'**informe de prova de vida** recull tot el que Didit ha observat en verificar que hi havia una persona real i viva davant de la càmera —no pas una foto impresa, una reproducció en pantalla o un deepfake. Inclou el mètode de prova de vida, una puntuació de confiança de 0 a 100, la selfie de referència i el vídeo de captura, una estimació d'edat opcional, mètriques de qualitat de la prova de vida passiva i coincidències facials entre sessions amb l'historial i la llista de bloqueig de la teva aplicació.

L'informe es genera després que l'usuari completi el pas de prova de vida en un flux de treball (o cridi l'endpoint facial autònom). Didit executa un dels tres mètodes de prova de vida (3D actiu, parpelleig de llum o passiu), puntua la captura, fa un cribratge de patrons coneguts de suplantació i compara la cara biomètricament amb totes les altres cares que hagis vist a la teva aplicació.

Cada informe inclou el seu propi `status` —independent de l'estat general de la sessió— que reflecteix com s'ha resolt únicament el pas de prova de vida:

* **Aprovada** — cara detectada, puntuació de prova de vida per sobre del llindar de revisió, no s'ha activat cap advertència de rebuig automàtic.
* **En revisió** — s'han activat una o més advertències enviades a revisió, o la puntuació és igual o inferior al llindar de revisió però per sobre del llindar de rebuig.
* **Rebutjada** — s'ha activat una condició de rebuig automàtic (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, o els riscos d'edat en fluxos d'estimació d'edat), una advertència configurable s'ha enviat a rebuig, o la puntuació és igual o inferior al llindar de rebuig.
* **No finalitzat** — l'usuari mai no ha completat el pas de prova de vida.

## On apareix a les respostes de l'API

L'informe de prova de vida apareix com a `liveness_checks[]` a `GET /v3/session/{sessionId}/decision/` —**sempre com un array JSON**, mai com un objecte `liveness` singular. Apareixen múltiples entrades quan un flux de treball executa la prova de vida més d'una vegada (per exemple, una comprovació principal més una recaptura).

* **API de decisió de la sessió** — `GET /v3/session/{sessionId}/decision/` retorna `liveness_checks[]` al nivell superior. Consulta [Obtenir la decisió de la sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md).
* **Webhooks** — Els payloads de `session.status.updated` inclouen el mateix array `liveness_checks[]` un cop el pas ha generat dades. Consulta [Webhooks](https://docs.didit.me/ca/integration/webhooks.md).
* **API autònoma de prova de vida** — consulta [API autònoma de prova de vida](https://docs.didit.me/ca/standalone-apis/passive-liveness.md).

> [!NOTE]
>
> Llegeix `response.liveness_checks[0]` i itera sobre l'array; l'estructura singular `liveness` 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 [Models de dades](https://docs.didit.me/ca/reference/data-models.md#prova-de-vida). Els camps següents reflecteixen aquest esquema canònic.

| Camp | Tipus | Descripció |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Estat del pas de prova de vida (vegeu més avall). |
| `node_id` | string \| null | Node del graf del flux de treball que ha generat aquest informe. |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | El mètode de prova de vida que ha generat aquesta captura. |
| `score` | number 0–100 \| null | Puntuació de confiança de la prova de vida, arrodonida a 2 decimals. |
| `reference_image` | string (URL signada) \| null | Selfie de referència extret de la captura. URL signada amb una finestra de validesa limitada. |
| `video_url` | string (URL signada) \| null | Vídeo complet de la captura de prova de vida (mètodes actius). URL signada amb una finestra de validesa limitada. |
| `age_estimation` | number \| null | Edat estimada en anys de la cara més gran de la imatge de referència. |
| `face_quality` | number 0–100 \| null | Qualitat facial de la prova de vida passiva, normalitzada a un percentatge. Només s'omple quan `method = "PASSIVE"`. |
| `face_luminance` | number 0–100 \| null | Lluminància facial de la prova de vida passiva, normalitzada de 0–255 a un percentatge. Només s'omple quan `method = "PASSIVE"`. |
| `matches[]` | array | Coincidències facials entre sessions (vegeu més avall). |
| `warnings[]` | array | Advertències a nivell de mòdul — vegeu [Advertències de prova de vida](https://docs.didit.me/ca/core-technology/liveness/warnings-liveness.md). Cada entrada segueix l'estructura de l'[Objecte d'advertència](https://docs.didit.me/ca/reference/data-models.md#objecte-d’advertència) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). |

### Coincidències facials entre sessions

`matches[]` llista les cares de l'historial de la teva aplicació que han superat el llindar de similitud biomètrica respecte a aquest selfie — fins a 5 entrades, primer les cares a la llista de bloqueig i a la llista d'admesos, i després per similitud descendent. Els candidats aptes són cares a la llista de bloqueig, cares a la llista d'admesos, cares de sessions `Approved` i cares importades per als teus usuaris de proveïdor. Les cares que pertanyen al mateix usuari (mateix `vendor_data`, o el mateix usuari de proveïdor quan estigui disponible) s'exclouen de **tota** la cerca — tant de la detecció de duplicats com del cribratge en llistes de bloqueig.

Cada entrada inclou:

| Camp | Tipus | Descripció |
| - | - | - |
| `session_id` | string (UUID) \| null | La sessió coincident. `null` quan `source` és `imported` o `list_entry`. |
| `session_number` | number \| null | Número de sessió seqüencial per a la sessió coincident. `null` per a fonts que no són sessions. |
| `similarity_percentage` | number 0–100 | Puntuació de similitud biomètrica, acotada a 0–100. |
| `vendor_data` | string \| null | Les teves dades de referència de la sessió coincident (o de l'usuari de proveïdor, per a cares importades). |
| `verification_date` | string (ISO 8601) \| null | Quan es va crear la sessió coincident (o la cara importada). |
| `user_details` | object \| null | `{ full_name, document_type, document_number }` del KYC de la sessió coincident. Les cares importades només omplen `full_name` (els dos camps de document són `null`); `null` quan no hi ha detalls registrats. |
| `match_image_url` | string (URL signada) \| null | Cara de referència de la sessió coincident, cara importada o entrada de llista. |
| `status` | string \| null | Estat de la sessió coincident (p. ex. `"Approved"`). `null` per a fonts que no són sessions. |
| `is_blocklisted` | boolean | `true` quan la cara coincident és a la teva llista de bloqueig facial. |
| `is_allowlisted` | boolean | `true` quan la cara coincident és a la teva llista de cares permeses (s'ometen les accions per cara duplicada). |
| `api_service` | string \| null | S'estableix quan la cara coincident prové d'una crida d'API independent (p. ex. `"PASSIVE_LIVENESS"`); `null` per a sessions de flux de treball i fonts que no són sessions. |
| `source` | `"session" \| "imported" \| "list_entry"` | D'on prové la cara coincident: una altra sessió de verificació, una cara pujada per a un usuari de proveïdor, o una cara de la llista d'admesos/bloqueig gestionada per l'organització. |

## Valors d'estat

Els estats provenen de l'enum compartit d'estats de funcionalitats (`FeatureStatusChoices`).

| Estat | Significat | Efecte posterior |
| - | - | - |
| `Approved` | Cara detectada, puntuació de prova de vida per sobre del llindar de revisió, cap advertència de rebuig automàtic activada. | Compta com una comprovació de prova de vida satisfactòria. |
| `In Review` | Puntuació igual o per sota del llindar de revisió però per sobre del llindar de rebuig, o s'ha activat una advertència dirigida a revisió. | La sessió també passa a `In Review` fins que un revisor actuï. |
| `Declined` | S'ha activat un risc de rebuig automàtic (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, o els riscos d'edat en fluxos d'estimació d'edat), s'ha dirigit una advertència configurable a rebuig, o la puntuació és igual o inferior al llindar de rebuig. | La sessió es rebutja tret que una altra branca aprovada satisfaci el flux de treball. |
| `Not Finished` | L'usuari ha abandonat el pas de prova de vida (o una fallada de captura reintentable està esperant un altre intent). | La branca de prova de vida no ha generat cap resultat. |
| `Resub Requested` | Un revisor ha sol·licitat que es torni a enviar aquest pas des de la consola. | Transitori — es substitueix un cop l'usuari torna a fer la captura. |

## Exemples

### Approved — captura neta de 3D activa

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — prova de vida passiva, captura de baixa qualitat i possible duplicat

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

Aquí la qualitat facial (12.4) se situa per sota del llindar de revisió predeterminat (15), la lluminància (18.7) se situa per sota del mínim predeterminat (20) i l'acció per cara duplicada del flux de treball està configurada com a Review — per tant, les tres advertències inclouen `log_type: "warning"` i l'informe es resol com a `In Review`.

## Nota de seguretat

Els vídeos i selfies de prova de vida són dades biomètriques — les URL signades són temporals i caduquen (després de 4 hores per defecte). Tracta-les com a elements de curta durada: no les emmagatzemis a la memòria cau ni les exposis públicament. Normalment, la teva aplicació només necessita `status`, `score` i les advertències — emmagatzema el mínim possible per reduir les dades biomètriques als teus servidors.

## Relacionats

* [Advertències de prova de vida](https://docs.didit.me/ca/core-technology/liveness/warnings-liveness.md) — enumeració completa d'advertències, causes i mesures correctives.
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md) — escolta `session.status.updated` per rebre l'informe.
* [Models de dades — Comprovació de la prova de vida](https://docs.didit.me/ca/reference/data-models.md#prova-de-vida) — esquema canònic amb tots els camps.
* [Informe de coincidència facial](https://docs.didit.me/ca/core-technology/face-match/report-face-match.md) — la coincidència facial 1:1 complementària amb el retrat del document.


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