Informe de prova de vida: puntuació i coincidències

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ó.
Webhooks — Els payloads de session.status.updated inclouen el mateix array liveness_checks[] un cop el pas ha generat dades. Consulta Webhooks.
API autònoma de prova de vida — consulta API autònoma de prova de vida.

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. 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. Cada entrada segueix l’estructura de l’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

{
  "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

{
  "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 — enumeració completa d’advertències, causes i mesures correctives.
Webhooks — escolta session.status.updated per rebre l’informe.
Models de dades — Comprovació de la prova de vida — esquema canònic amb tots els camps.
Informe de coincidència facial — la coincidència facial 1:1 complementària amb el retrat del document.

Autenticació

Verificació

Monitoratge

Plataforma

Informe de prova de vida: puntuació i coincidències

Visió general

On apareix a les respostes de l’API

Esquema

Coincidències facials entre sessions

Valors d’estat

Exemples

Approved — captura neta de 3D activa

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

Nota de seguretat

Relacionats

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Coincidències facials entre sessions

​Valors d’estat

​Exemples

​Approved — captura neta de 3D activa

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

​Nota de seguretat

​Relacionats

Visió general

On apareix a les respostes de l’API

Esquema

Coincidències facials entre sessions

Valors d’estat

Exemples

Approved — captura neta de 3D activa

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

Nota de seguretat

Relacionats