Advertencias y códigos de autenticación biométrica

La autenticación biométrica combina una prueba de vida con una coincidencia facial 1:1 opcional contra el rostro de referencia que se determina al crear la sesión (la portrait_image proporcionada, o el rostro almacenado del usuario, que se busca mediante vendor_data). Cada paso emite sus propias advertencias en el payload de decisión V3. Esta página enumera cada código, dónde aparece y cómo los umbrales se traducen en el estado final de la sesión.

Visión general

Cuando se ejecuta una sesión de autenticación biométrica, Didit:

Captura una selfie en vivo mediante 3D Action, Flash o Passive Liveness (method: ACTIVE_3D, FLASHING o PASSIVE).
Extrae el rostro más grande de la captura y asigna una puntuación a su prueba de vida.
Si el flujo de verificación (workflow) incluye coincidencia facial, compara el rostro capturado con el rostro de referencia de la sesión (la portrait_image proporcionada o el rostro almacenado del usuario).
Registra el resultado de cada paso y cualquier advertencia en la decisión de la sesión.

Las advertencias siguen la estructura compartida del objeto de advertencia que se usa en toda la plataforma: feature, risk, additional_data, log_type, short_description, long_description y node_id.

Dónde aparecen las advertencias

Clave de la respuesta de decisión	Etiqueta de función en la advertencia	Cuándo se activa
`liveness_checks[].warnings[]`	`LIVENESS`	Puntuación de prueba de vida, calidad del rostro, luminancia, múltiples rostros y comprobaciones de lista de bloqueo, lista de permitidos y rostro duplicado.
`face_matches[].warnings[]`	`FACEMATCH`	Coincidencia facial contra el rostro de referencia de la sesión (la `portrait_image` proporcionada o el rostro almacenado del usuario).

En una sesión típica de autenticación biométrica hay un elemento en cada array. En los flujos con varias instancias, el node_id de cada advertencia indica qué paso la generó.

Condiciones de rechazo automático

Las siguientes advertencias siempre provocan el rechazo de su paso (log_type: "error"), independientemente de cómo hayas configurado el flujo:

Riesgo	Función	Por qué se rechaza automáticamente
`FACE_IN_BLOCKLIST`	`LIVENESS`	El rostro coincidió con una entrada de tu lista de bloqueo de rostros.
`NO_FACE_DETECTED`	`LIVENESS`	No se localizó ningún rostro durante la captura de prueba de vida, o el usuario agotó los reintentos de captura.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	Se detectó un ataque de presentación (máscara, reproducción en pantalla, suplantación mediante deepfake).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	No había ninguna imagen de referencia disponible para realizar la comparación. Cuando se activa, `LOW_FACE_MATCH_SIMILARITY` se suprime.

Cuando se activa NO_FACE_DETECTED, LOW_LIVENESS_SCORE se suprime (no hay ningún rostro que puntuar).

Umbrales y acciones configurables

Estas advertencias se puntúan y luego se asignan a un estado mediante los umbrales y las acciones que configuras en cada flujo:

Riesgo	Función	Comportamiento configurable
`LOW_LIVENESS_SCORE`	`LIVENESS`	Puntuación igual o inferior al umbral de revisión → `In Review`; igual o inferior al umbral de rechazo → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	Puntuación igual o inferior al umbral de revisión (70 por defecto) → `In Review`; igual o inferior al umbral de rechazo (50 por defecto) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Umbral de revisión (15 por defecto) → `In Review`; umbral de rechazo (0 por defecto, es decir, rechazo desactivado) → `Declined`. Solo en Passive Liveness.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Por debajo del umbral mínimo de luminancia (20 por defecto): Sin acción / Revisión (por defecto) / Rechazo. Solo en Passive Liveness.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Por encima del umbral máximo de luminancia (80 por defecto): Sin acción / Revisión (por defecto) / Rechazo. Solo en Passive Liveness.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	Sin acción (por defecto) / Revisión / Rechazo cuando se captura más de un rostro. Solo en Passive Liveness.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	Una única acción compartida para rostros duplicados: Sin acción (por defecto) / Revisión / Rechazo para coincidencias con rostros aprobados o importados de otros usuarios.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	Acción propia (`face_liveness_duplicated_face_name_mismatch_action`): Sin acción / Revisión (por defecto) / Rechazo. Se emite junto con `DUPLICATED_FACE` cuando la identidad de la sesión coincidente no se corresponde con el nombre resuelto de esta sesión; consulta Advertencias de prueba de vida.

POSSIBLE_FACE_IN_BLOCKLIST (LIVENESS) no es configurable: una coincidencia con la lista de bloqueo de menor confianza siempre se envía a revisión (log_type: "warning").

Reintentos de captura

Los fallos causados únicamente por riesgos de calidad de captura que se pueden corregir (puntuación baja, sin rostro, calidad, luminancia, múltiples rostros y, en la coincidencia facial, similitud baja) entran en un ciclo de reintentos antes de que el estado se fije: el usuario dispone de hasta face_liveness_max_attempts / face_match_max_attempts intentos en total (3 por defecto, configurables entre 2 y 5 por nodo del flujo). Cuando se agotan los intentos, se aplica el estado calculado en el último intento y se registra LIVENESS_MAX_ATTEMPTS_EXCEEDED o FACE_MATCH_MAX_ATTEMPTS_EXCEEDED como information para dejar constancia.

Advertencias de prueba de vida

La API devuelve exactamente estas cadenas de short_description y long_description:

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Puntuación de prueba de vida baja	La prueba de vida obtuvo una puntuación baja, lo que indica un posible uso de representaciones faciales no vivas o datos biométricos de baja calidad.
`NO_FACE_DETECTED`	No se detectó ningún rostro en la prueba de vida	El sistema no pudo identificar un rostro durante la prueba de vida, lo que puede deberse a una mala calidad de imagen, una posición incorrecta o problemas técnicos.
`LIVENESS_FACE_ATTACK`	Ataque facial en la prueba de vida	El sistema detectó un posible intento de eludir la prueba de vida.
`FACE_IN_BLOCKLIST`	Rostro en la lista de bloqueo	El sistema identificó un rostro en la lista de bloqueo, lo que significa que no se permite verificar ese rostro.
`POSSIBLE_FACE_IN_BLOCKLIST`	Posible rostro en la lista de bloqueo	El sistema identificó un posible rostro en la lista de bloqueo, lo que significa que no se permite verificar ese rostro.
`FACE_IN_ALLOWLIST`	Rostro en la lista de permitidos	El rostro coincidió con la lista de rostros permitidos de la aplicación, por lo que se omitieron las acciones por rostro duplicado para esta señal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Posible rostro en la lista de permitidos	El rostro posiblemente coincidió con la lista de rostros permitidos de la aplicación, por lo que se omitieron las acciones por posible rostro duplicado para esta señal.
`DUPLICATED_FACE`	Rostro duplicado de otra sesión aprobada	El sistema identificó un rostro duplicado de otra sesión aprobada, lo que requiere una investigación adicional.
`POSSIBLE_DUPLICATED_FACE`	Posible rostro duplicado de otra sesión aprobada	El sistema identificó un posible rostro duplicado de otra sesión aprobada, lo que requiere una investigación adicional.
`DUPLICATED_FACE_NAME_MISMATCH`	Rostro duplicado con un nombre distinto	Ya se aprobó otra sesión con el mismo rostro, pero con un nombre distinto. La identidad detrás del duplicado no coincide con la identidad declarada en esta sesión, lo que es un fuerte indicio de fraude de identidad.
`MULTIPLE_FACES_DETECTED` (solo pasiva)	Se detectaron varios rostros	Se detectaron varios rostros en la imagen de la prueba de vida. El sistema usa el rostro más grande para la verificación de prueba de vida y la comparación facial, pero la presencia de varios rostros puede requerir una revisión adicional.
`LOW_FACE_QUALITY` (solo pasiva)	Baja calidad del rostro	La calidad de la imagen facial está por debajo del umbral aceptable, lo que puede afectar a la fiabilidad de la prueba de vida. Puede deberse a la resolución de la cámara, el enfoque o artefactos de compresión.
`LOW_FACE_LUMINANCE` (solo pasiva)	Baja luminancia del rostro	La imagen facial es demasiado oscura, lo que puede afectar a la precisión de la prueba de vida. Se recomiendan mejores condiciones de iluminación.
`HIGH_FACE_LUMINANCE` (solo pasiva)	Alta luminancia del rostro	La imagen facial es demasiado brillante o está sobreexpuesta, lo que puede afectar a la precisión de la prueba de vida. Se recomienda reducir la iluminación o evitar la luz directa.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	Se superó el número máximo de intentos de prueba de vida	Se alcanzó el número máximo de intentos de captura de prueba de vida. Se aplicó el estado calculado del último intento (rechazo o revisión).

Las coincidencias con la lista de bloqueo, con la lista de permitidos y con duplicados incluyen additional_data con la sesión coincidente (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, el *_session_number correspondiente y api_service). Solo aparece uno de esos seis códigos por informe. DUPLICATED_FACE_NAME_MISMATCH es la excepción: se emite además de DUPLICATED_FACE, nunca en su lugar, cuando la identidad de la sesión coincidente no coincide con el nombre resuelto de esta sesión. Su additional_data añade name_match_score a los mismos campos de la sesión duplicada. Un nombre escrito en un sistema de escritura distinto en cada lado no se considera una discrepancia cuando los documentos de identidad de ambas sesiones comparten el estado emisor, un número de documento o número personal idéntico y fechas de nacimiento que no se contradicen. Consulta Advertencias de prueba de vida.

Advertencias de coincidencia facial

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Baja similitud en la coincidencia facial	Los rasgos faciales de la imagen proporcionada no se parecen lo suficiente a los de la imagen de referencia, lo que sugiere una posible discrepancia de identidad.
`NO_REFERENCE_IMAGE`	No se encontró una imagen de origen para realizar la coincidencia facial	Falta una imagen de referencia para la comparación facial, lo que impide que el sistema complete el proceso de coincidencia facial.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	Se superó el número máximo de intentos de coincidencia facial	Se alcanzó el número máximo de intentos de captura para la coincidencia facial. Se aplicó el estado calculado del último intento (rechazo o revisión).

Ejemplo: rechazado por ataque facial

{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "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": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}

Ejemplo: en revisión por baja similitud

{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "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": "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"
        }
      ]
    }
  ]
}

La puntuación (58.70) se sitúa entre el umbral de rechazo (50 por defecto) y el umbral de revisión (70 por defecto), por lo que la advertencia tiene log_type: "warning" y el estado de la coincidencia facial es In Review. En este ejemplo, la advertencia se activó en una sesión cuyo session_id es 11111111-2222-3333-4444-555555555555: source_image_session_id contiene el id de la propia sesión porque la referencia procede del retrato almacenado al crear la sesión.

Tipos de advertencia

A cada riesgo se le asigna un tipo de advertencia según la configuración de tu aplicación. Las advertencias se dividen en tres categorías de gravedad:

Relacionado

Informe de autenticación biométrica

Dónde aparecen liveness_checks[] y face_matches[] en la decisión V3.

Advertencias de prueba de vida

Referencia completa de las advertencias de prueba de vida, incluida la detección de rostros duplicados.

Advertencias de coincidencia facial

Referencia completa de las advertencias de coincidencia facial para comparaciones 1:1.

Autenticación

Verificación

Monitorización

Plataforma

Advertencias y códigos de autenticación biométrica

Visión general

Dónde aparecen las advertencias

Condiciones de rechazo automático

Umbrales y acciones configurables

Reintentos de captura

Advertencias de prueba de vida

Advertencias de coincidencia facial

Ejemplo: rechazado por ataque facial

Ejemplo: en revisión por baja similitud

Tipos de advertencia

Relacionado

Informe de autenticación biométrica

Advertencias de prueba de vida

Advertencias de coincidencia facial

​Visión general

​Dónde aparecen las advertencias

​Condiciones de rechazo automático

​Umbrales y acciones configurables

​Reintentos de captura

​Advertencias de prueba de vida

​Advertencias de coincidencia facial

​Ejemplo: rechazado por ataque facial

​Ejemplo: en revisión por baja similitud

​Tipos de advertencia

​Relacionado

Informe de autenticación biométrica

Advertencias de prueba de vida

Advertencias de coincidencia facial

Visión general

Dónde aparecen las advertencias

Condiciones de rechazo automático

Umbrales y acciones configurables

Reintentos de captura

Advertencias de prueba de vida

Advertencias de coincidencia facial

Ejemplo: rechazado por ataque facial

Ejemplo: en revisión por baja similitud

Tipos de advertencia

Relacionado