Informe de autenticación biométrica: esquema JSON

El informe de Autenticación biométrica es la forma en que Didit comunica el resultado de la reverificación de un usuario recurrente. El flujo de verificación (workflow) ejecuta una nueva prueba de vida y, cuando la Coincidencia facial está habilitada en el flujo, una coincidencia facial 1:1 con el rostro de referencia determinado al crear la sesión (la portrait_image que proporcionaste o el rostro almacenado del usuario, localizado mediante vendor_data). Ambas comprobaciones aparecen como elementos estándar de las funciones en la respuesta de decisión de sesión V3.

Informe de autenticación biométrica de Didit que combina la prueba de vida y la coincidencia facial con un retrato almacenado

Visión general

La Autenticación biométrica es un tipo de flujo (workflow_type: "biometric_authentication"), no un objeto de respuesta independiente. Cuando el flujo se ejecuta, emite:

Una prueba de vida que captura una selfie en vivo y la evalúa para detectar suplantación.
Una coincidencia facial que compara el rostro capturado con el rostro de referencia determinado al crear la sesión (solo cuando la Coincidencia facial está habilitada en el flujo).

Siempre que el flujo incluye la Coincidencia facial, la creación de la sesión necesita un rostro de referencia. Envía portrait_image (imagen codificada en base64, máximo 2MB) u omítela, y Didit reutilizará el rostro ya almacenado para el usuario de vendor_data: primero un rostro de una prueba de vida aprobada, después la foto del chip del pasaporte electrónico, después el retrato del documento de identidad y, por último, un rostro de perfil registrado manualmente. Si no hay ni portrait_image ni un rostro almacenado disponible, la creación de la sesión devuelve 400 con

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

. En ambos casos, la referencia determinada se registra en la nueva sesión, por lo que el source_image_session_id del elemento de coincidencia facial se establece en el propio session_id de esa sesión (esto indica que la referencia procede del retrato almacenado de la sesión y no de un retrato de documento capturado en la misma sesión, que dejaría el campo en null).

Dónde aparece

Clave de la respuesta de decisión	Cantidad	Esquema del elemento
`liveness_checks[]`	Uno por cada paso de prueba de vida (normalmente 1 en la autenticación biométrica)	data-models#liveness-check
`face_matches[]`	Uno por cada paso de coincidencia facial (`null` en flujos solo de prueba de vida)	data-models#face-match

Ambos arrays los devuelve GET /v3/session/{sessionId}/decision/ para las sesiones cuyo tipo de flujo es biometric_authentication. Siempre son arrays, nunca objetos individuales, y cada elemento es null hasta que su paso ha generado datos. Cada elemento incluye un node_id para que los flujos con varias instancias puedan distinguir los pasos.

Referencia del esquema

La lista completa de campos se define una sola vez en la página de modelos de datos, para que todos los informes que muestran estas funciones compartan una única fuente de verdad:

Esquema del elemento de prueba de vida: status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Esquema del elemento de coincidencia facial: status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Estructura de una entrada de advertencia: feature, risk, additional_data, log_type, short_description, long_description, node_id.

Valores de estado

Tanto liveness_checks[].status como face_matches[].status usan el ciclo de vida compartido de las funciones (estados a nivel de función):

Estado	Significado
`Not Finished`	El paso aún no ha generado un resultado final (el usuario no lo ha completado o lo ha abandonado). Antes de que un paso empiece, su array es simplemente `null` en la respuesta de decisión.
`Approved`	La comprobación superó todos los umbrales configurados.
`In Review`	La puntuación quedó en la franja de revisión, o una advertencia configurable estaba ajustada para enviar a revisión.
`Declined`	La puntuación quedó en el umbral de rechazo o por debajo, o se activó una advertencia de rechazo automático (ataque facial, ningún rostro detectado, rostro en la lista de bloqueo, sin imagen de referencia para la coincidencia facial).
`Resub Requested`	Un revisor pidió al usuario que reintentara este paso.

El status general de la sesión agrega ambos elementos: cualquier función en Declined rechaza la sesión, cualquiera en In Review pone la sesión en In Review y, en caso contrario, queda en Approved (cuando todas las funciones han terminado). Para el comportamiento de los umbrales y la lista completa de códigos de advertencia, consulta Advertencias de Autenticación biométrica.

Ejemplo — prueba de vida + coincidencia facial (aprobado)

Los ejemplos están abreviados: la estructura completa de la decisión también incluye session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at y expires_at.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

Ejemplo — solo prueba de vida (Coincidencia facial deshabilitada en el flujo)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}

El modo de solo prueba de vida es una configuración del flujo: cuando la Coincidencia facial está deshabilitada, no se necesita un rostro de referencia al crear la sesión y face_matches permanece en null. Cuando la Coincidencia facial está habilitada, omitir portrait_image no activa el modo de solo prueba de vida: Didit reutiliza el rostro almacenado para el usuario de vendor_data y, si no existe ningún rostro almacenado, la creación de la sesión falla con 400.

Ejemplo — coincidencia facial rechazada por baja similitud

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "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"
        }
      ]
    }
  ]
}

Nota de seguridad

reference_image, video_url, source_image y target_image son URL firmadas que caducan tras un periodo de validez limitado (4 horas de forma predeterminada). Apuntan a datos biométricos: no las almacenes en caché ni las expongas públicamente. Guarda el resultado de la verificación (estado, puntuación, source_image_session_id) en tu sistema; vuelve a consultar el endpoint de decisión si necesitas URL nuevas.

Relacionado

Advertencias de autenticación biométrica

Códigos de advertencia, umbrales y condiciones de rechazo automático.

Informe de prueba de vida

Referencia completa de los campos de los elementos de liveness_checks[].

Informe de coincidencia facial

Referencia completa de los campos de los elementos de face_matches[].

Autenticación

Verificación

Monitorización

Plataforma

Informe de autenticación biométrica: esquema JSON

Visión general

Dónde aparece

Referencia del esquema

Valores de estado

Ejemplo — prueba de vida + coincidencia facial (aprobado)

Ejemplo — solo prueba de vida (Coincidencia facial deshabilitada en el flujo)

Ejemplo — coincidencia facial rechazada por baja similitud

Nota de seguridad

Relacionado

Advertencias de autenticación biométrica

Informe de prueba de vida

Informe de coincidencia facial

​Visión general

​Dónde aparece

​Referencia del esquema

​Valores de estado

​Ejemplo — prueba de vida + coincidencia facial (aprobado)

​Ejemplo — solo prueba de vida (Coincidencia facial deshabilitada en el flujo)

​Ejemplo — coincidencia facial rechazada por baja similitud

​Nota de seguridad

​Relacionado

Advertencias de autenticación biométrica

Informe de prueba de vida

Informe de coincidencia facial

Visión general

Dónde aparece

Referencia del esquema

Valores de estado

Ejemplo — prueba de vida + coincidencia facial (aprobado)

Ejemplo — solo prueba de vida (Coincidencia facial deshabilitada en el flujo)

Ejemplo — coincidencia facial rechazada por baja similitud

Nota de seguridad

Relacionado