Informe de liveness: puntuación, método y coincidencias

Descripción general

El informe de prueba de vida recoge todo lo que Didit observó al verificar que había una persona real y viva frente a la cámara, y no una foto impresa, una reproducción en pantalla o un deepfake. Incluye el método de prueba de vida, una puntuación de confianza de 0 a 100, la selfie de referencia y el video de captura, una estimación de edad opcional, métricas de calidad de la prueba de vida pasiva y las coincidencias faciales entre sesiones con el historial y la lista de bloqueo de tu aplicación. El informe se genera cuando el usuario completa el paso de prueba de vida en un flujo de verificación (workflow) o cuando invoca el endpoint facial independiente. Didit ejecuta uno de los tres métodos de prueba de vida (3D activa, con destellos o pasiva), puntúa la captura, busca patrones de suplantación conocidos y compara biométricamente el rostro con todos los demás rostros que hayas registrado en tu aplicación. Cada informe tiene su propio status, independiente del estado general de la sesión, que refleja cómo se resolvió únicamente el paso de prueba de vida:

Aprobado: se detectó un rostro, la puntuación de prueba de vida supera el umbral de revisión y no se activó ninguna advertencia de rechazo automático.
En Revisión: se activaron una o más advertencias configuradas para enviarse a revisión, o la puntuación es igual o inferior al umbral de revisión pero superior al umbral de rechazo.
Rechazado: se cumplió una condición de rechazo automático (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST o los riesgos de edad en los flujos de estimación de edad), una advertencia configurable se envió a rechazo, o la puntuación es igual o inferior al umbral de rechazo.
No finalizado: el usuario nunca completó el paso de prueba de vida.

Dónde aparece en las respuestas de la API

El informe de prueba de vida aparece como liveness_checks[] en GET /v3/session/{sessionId}/decision/. Siempre es un array JSON, nunca un objeto liveness singular. Aparecen varias entradas cuando un flujo ejecuta la prueba de vida más de una vez (por ejemplo, una comprobación principal más una nueva captura).

API de decisión de sesión: GET /v3/session/{sessionId}/decision/ devuelve liveness_checks[] en el nivel superior. Consulta Obtener la decisión de la sesión.
Webhooks: los payloads de session.status.updated incluyen el mismo array liveness_checks[] una vez que el paso ha generado datos. Consulta Webhooks.
API independiente de prueba de vida: consulta API independiente de prueba de vida.

Lee response.liveness_checks[0] y recorre el array: la estructura singular liveness a la que hacían referencia algunos tutoriales antiguos no existe en el endpoint de decisión v3.

Esquema

El esquema canónico campo por campo está en la página de referencia Modelos de datos. Los campos de abajo reflejan ese esquema canónico.

Campo	Tipo	Descripción
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Estado del paso de prueba de vida (consulta más abajo).
`node_id`	string \| null	Nodo del grafo del flujo de verificación (workflow) que generó este informe.
`method`	`"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`	Método de prueba de vida que generó esta captura.
`score`	number 0–100 \| null	Puntuación de confianza de la prueba de vida, redondeada a 2 decimales.
`reference_image`	string (URL firmada) \| null	Selfie de referencia extraído de la captura. URL firmada con un período de validez limitado.
`video_url`	string (URL firmada) \| null	Video completo de la captura de prueba de vida (métodos activos). URL firmada con un período de validez limitado.
`age_estimation`	number \| null	Edad estimada en años del rostro más grande de la imagen de referencia.
`face_quality`	number 0–100 \| null	Calidad del rostro en la prueba de vida pasiva, normalizada a un porcentaje. Solo se rellena cuando `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Luminancia facial en la prueba de vida pasiva, normalizada de 0–255 a un porcentaje. Solo se rellena cuando `method = "PASSIVE"`.
`matches[]`	array	Coincidencias faciales entre sesiones (consulta más abajo).
`warnings[]`	array	Advertencias a nivel de módulo: consulta Advertencias de prueba de vida. Cada entrada sigue la estructura del objeto de advertencia (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Coincidencias faciales entre sesiones

matches[] enumera los rostros del historial de tu aplicación que superaron el umbral de similitud biométrica frente a este selfie: hasta 5 entradas, primero los rostros de la lista de bloqueo y de la lista de permitidos, y después por similitud descendente. Los candidatos elegibles son los rostros de la lista de bloqueo, los rostros de la lista de permitidos, los rostros de sesiones Approved y los rostros importados para tus usuarios del proveedor. Los rostros que pertenecen al mismo usuario (mismo vendor_data, o el mismo usuario de proveedor cuando está disponible) se excluyen de toda la búsqueda, tanto de la detección de duplicados como del análisis contra la lista de bloqueo. Cada entrada incluye:

Campo	Tipo	Descripción
`session_id`	string (UUID) \| null	La sesión coincidente. `null` cuando `source` es `imported` o `list_entry`.
`session_number`	number \| null	Número secuencial de la sesión coincidente. `null` para orígenes que no son sesiones.
`similarity_percentage`	number 0–100	Puntuación de similitud biométrica, limitada al rango 0–100.
`vendor_data`	string \| null	Tus datos de referencia de la sesión coincidente (o del usuario de proveedor, en el caso de rostros importados).
`verification_date`	string (ISO 8601) \| null	Cuándo se creó la sesión coincidente (o el rostro importado).
`user_details`	object \| null	`{ full_name, document_type, document_number }` del KYC de la sesión coincidente. Los rostros importados solo rellenan `full_name` (los dos campos del documento son `null`); `null` cuando no hay datos registrados.
`match_image_url`	string (URL firmada) \| null	Rostro de referencia de la sesión coincidente, del rostro importado o de la entrada de la lista.
`status`	string \| null	Estado de la sesión coincidente (por ejemplo, `"Approved"`). `null` para orígenes que no son sesiones.
`is_blocklisted`	boolean	`true` cuando el rostro coincidente está en tu lista de bloqueo de rostros.
`is_allowlisted`	boolean	`true` cuando el rostro coincidente está en tu lista de permitidos de rostros (se omiten las acciones por rostro duplicado).
`api_service`	string \| null	Se establece cuando el rostro coincidente procede de una llamada independiente a la API (por ejemplo, `"PASSIVE_LIVENESS"`); `null` para sesiones de flujo y orígenes que no son sesiones.
`source`	`"session" \| "imported" \| "list_entry"`	De dónde procede el rostro coincidente: otra sesión de verificación, un rostro subido para un usuario de proveedor o un rostro de una lista de permitidos o de bloqueo gestionada por la organización.

Valores de estado

Los estados proceden del enum compartido de estados de función (FeatureStatusChoices).

Estado	Significado	Efecto posterior
`Approved`	Se detectó un rostro, la puntuación de prueba de vida está por encima del umbral de revisión y no se activó ninguna advertencia de rechazo automático.	Cuenta como una comprobación de prueba de vida superada.
`In Review`	La puntuación es igual o inferior al umbral de revisión pero superior al umbral de rechazo, o se activó una advertencia configurada para enviarse a revisión.	La sesión también pasa a `In Review` hasta que un revisor actúe.
`Declined`	Se activó un riesgo de rechazo automático (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST` o los riesgos de edad en flujos de estimación de edad), una advertencia configurable se envió a rechazo, o la puntuación es igual o inferior al umbral de rechazo.	La sesión se rechaza, salvo que otra rama aprobada cumpla los requisitos del flujo.
`Not Finished`	El usuario abandonó el paso de prueba de vida (o un fallo de captura que admite reintento está a la espera de otro intento).	La rama de prueba de vida no generó ningún resultado.
`Resub Requested`	Un revisor solicitó desde la consola que se volviera a enviar este paso.	Transitorio: se reemplaza cuando el usuario vuelve a hacer la captura.

Ejemplos

Approved: captura 3D activa sin incidencias

{
  "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: prueba de vida pasiva, captura de baja calidad y un posible duplicado

{
  "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 calidad del rostro (12.4) está por debajo del umbral de revisión predeterminado (15), la luminancia (18.7) está por debajo del mínimo predeterminado (20) y la acción del flujo para rostros duplicados está configurada en Review, así que las tres advertencias llevan log_type: "warning" y el informe queda en In Review.

Nota de seguridad

Los videos y selfies de prueba de vida son datos biométricos: las URL firmadas son temporales y caducan (después de 4 horas de forma predeterminada). Trátalas como recursos de corta duración: no las almacenes en caché ni las expongas públicamente. Normalmente tu aplicación solo necesita status, score y las advertencias; guarda lo mínimo posible para reducir los datos biométricos en tus servidores.

Relacionado

Advertencias de prueba de vida: enum completo de advertencias, causas y cómo resolverlas.
Webhooks: escucha session.status.updated para recibir el informe.
Modelos de datos: comprobación de prueba de vida: esquema canónico con todos los campos.
Informe de coincidencia facial: la coincidencia facial 1:1 complementaria con el retrato del documento.

Autenticación

Verificación

Monitorización

Plataforma

Informe de liveness: puntuación, método y coincidencias

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Coincidencias faciales entre sesiones

Valores de estado

Ejemplos

Approved: captura 3D activa sin incidencias

In Review: prueba de vida pasiva, captura de baja calidad y un posible duplicado

Nota de seguridad

Relacionado

​Descripción general

​Dónde aparece en las respuestas de la API

​Esquema

​Coincidencias faciales entre sesiones

​Valores de estado

​Ejemplos

​Approved: captura 3D activa sin incidencias

​In Review: prueba de vida pasiva, captura de baja calidad y un posible duplicado

​Nota de seguridad

​Relacionado

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Coincidencias faciales entre sesiones

Valores de estado

Ejemplos

Approved: captura 3D activa sin incidencias

In Review: prueba de vida pasiva, captura de baja calidad y un posible duplicado

Nota de seguridad

Relacionado