Advertències i codis d'autenticació biomètrica

L’Autenticació biomètrica combina una comprovació de prova de vida amb una coincidència facial 1:1 opcional respecte a la cara de referència resolta en crear la sessió (la portrait_image proporcionada, o la cara emmagatzemada de l’usuari consultada mitjançant vendor_data). Cada pas emet les seves pròpies advertències al payload de decisió V3. Aquesta pàgina enumera cada codi, on apareix i com es tradueixen els llindars en un estat final de la sessió.

Visió general

Quan s’executa una sessió d’autenticació biomètrica, Didit:

Captura una selfie en directe utilitzant 3D Action, Flash o Prova de vida passiva (method: ACTIVE_3D, FLASHING o PASSIVE).
Extreu la cara més gran de la captura i puntua la seva prova de vida.
Si el flux de treball inclou Coincidència facial, compara la cara capturada amb la cara de referència de la sessió (la portrait_image proporcionada o la cara emmagatzemada de l’usuari).
Escriu el resultat de cada pas i qualsevol advertència a la decisió de la sessió.

Les advertències mantenen l’estructura compartida de l’objecte d’advertència utilitzada a tota la plataforma: feature, risk, additional_data, log_type, short_description, long_description i node_id.

On apareixen les advertències

Clau de la resposta de decisió	Etiqueta de funcionalitat a l’advertència	Quan s’activa
`liveness_checks[].warnings[]`	`LIVENESS`	Puntuació de prova de vida, qualitat facial, lluminositat, múltiples cares i comprovacions de llista de bloqueig / llista de permisos / cares duplicades.
`face_matches[].warnings[]`	`FACEMATCH`	Coincidència facial respecte a la cara de referència de la sessió (la `portrait_image` proporcionada o la cara emmagatzemada de l’usuari).

En una sessió típica d’autenticació biomètrica hi ha un element a cadascuna de les matrius. En fluxos de treball amb múltiples instàncies, el node_id de cada advertència desambigua quin pas l’ha produït.

Condicions de rebuig automàtic

Les advertències següents sempre rebutgen el seu pas (log_type: "error") independentment de com hagis configurat el flux de treball:

Risc	Funcionalitat	Per què es rebutja automàticament
`FACE_IN_BLOCKLIST`	`LIVENESS`	La cara ha coincidit amb una entrada de la teva llista de bloqueig de cares.
`NO_FACE_DETECTED`	`LIVENESS`	No s’ha localitzat cap cara durant la captura de prova de vida, o l’usuari ha esgotat els intents de captura.
`LIVENESS_FACE_ATTACK`	`LIVENESS`	S’ha detectat un atac de presentació (màscara, reproducció en pantalla, suplantació de tipus deepfake).
`NO_REFERENCE_IMAGE`	`FACEMATCH`	No hi havia cap imatge de referència disponible per executar la comparació. Quan s’activa això, `LOW_FACE_MATCH_SIMILARITY` se suprimeix.

Quan s’activa NO_FACE_DETECTED, se suprimeix LOW_LIVENESS_SCORE (no hi ha cap cara per puntuar).

Llindars i accions configurables

Aquestes advertències es puntuen i després s’assignen a un estat mitjançant els llindars i les accions que defineixis per flux de treball:

Risc	Funcionalitat	Comportament configurable
`LOW_LIVENESS_SCORE`	`LIVENESS`	Puntuació igual o inferior al llindar de revisió → `In Review`; igual o inferior al llindar de rebuig → `Declined`.
`LOW_FACE_MATCH_SIMILARITY`	`FACEMATCH`	Puntuació igual o inferior al llindar de revisió (per defecte 70) → `In Review`; igual o inferior al llindar de rebuig (per defecte 50) → `Declined`.
`LOW_FACE_QUALITY`	`LIVENESS`	Llindar de revisió (per defecte 15) → `In Review`; llindar de rebuig (per defecte 0, és a dir, rebuig desactivat) → `Declined`. Només per a Prova de vida passiva.
`LOW_FACE_LUMINANCE`	`LIVENESS`	Per sota del llindar mínim de lluminositat (per defecte 20): Cap acció / Revisió (per defecte) / Rebuig. Només per a Prova de vida passiva.
`HIGH_FACE_LUMINANCE`	`LIVENESS`	Per sobre del llindar màxim de lluminositat (per defecte 80): Cap acció / Revisió (per defecte) / Rebuig. Només per a Prova de vida passiva.
`MULTIPLE_FACES_DETECTED`	`LIVENESS`	Cap acció (per defecte) / Revisió / Rebuig quan es captura més d’una cara. Només per a Prova de vida passiva.
`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`	`LIVENESS`	Una acció compartida de cara duplicada: Cap acció (per defecte) / Revisió / Rebuig per a coincidències amb cares aprovades o importades d’altres usuaris.
`DUPLICATED_FACE_NAME_MISMATCH`	`LIVENESS`	Acció pròpia (`face_liveness_duplicated_face_name_mismatch_action`): Cap acció / Revisió (per defecte) / Rebuig. S’emet juntament amb `DUPLICATED_FACE` quan la identitat de la sessió amb què s’ha coincidit no coincideix amb el nom resolt d’aquesta sessió; consulta Advertències de prova de vida.

POSSIBLE_FACE_IN_BLOCKLIST (LIVENESS) no és configurable: una coincidència de menor confiança amb la llista de bloqueig sempre s’encamina a Revisió (log_type: "warning").

Reintents de captura

Els errors provocats únicament per riscos corregibles de qualitat de la captura (puntuació baixa, cap cara, qualitat, lluminositat, múltiples cares, i baixa similitud en la coincidència facial) entren en un bucle de reintents abans que l’estat es consolidi: l’usuari disposa de fins a face_liveness_max_attempts / face_match_max_attempts intents en total (per defecte 3, configurable de 2 a 5 per node del flux de treball). Quan s’han esgotat els intents disponibles, s’aplica l’estat calculat de l’últim intent i es registra LIVENESS_MAX_ATTEMPTS_EXCEEDED o FACE_MATCH_MAX_ATTEMPTS_EXCEEDED com a information per deixar-ne constància.

Advertències de prova de vida

L’API retorna exactament aquestes cadenes de short_description i long_description:

`risk`	`short_description`	`long_description`
`LOW_LIVENESS_SCORE`	Puntuació de prova de vida baixa	La comprovació de prova de vida ha donat una puntuació baixa, la qual cosa indica un ús potencial de representacions facials que no corresponen a una persona viva o dades biomètriques de baixa qualitat.
`NO_FACE_DETECTED`	No s’ha detectat cap cara a la prova de vida	El sistema no ha pogut identificar cap cara durant la comprovació de prova de vida, cosa que pot ser deguda a una mala qualitat de la imatge, una posició incorrecta o problemes tècnics.
`LIVENESS_FACE_ATTACK`	Atac facial a la prova de vida	El sistema ha detectat un intent potencial d’eludir la comprovació de prova de vida.
`FACE_IN_BLOCKLIST`	Cara a la llista de bloqueig	El sistema ha identificat una cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible cara a la llista de bloqueig	El sistema ha identificat una possible cara a la llista de bloqueig, la qual cosa significa que no es permet verificar la cara.
`FACE_IN_ALLOWLIST`	Cara a la llista d’admesos	La cara ha coincidit amb la llista de cares admeses de l’aplicació, de manera que s’han omès les accions per cares duplicades per a aquest senyal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible cara a la llista d’admesos	És possible que la cara hagi coincidit amb la llista de cares admeses de l’aplicació, de manera que s’han omès les possibles accions per cares duplicades per a aquest senyal.
`DUPLICATED_FACE`	Cara duplicada d’una altra sessió aprovada	El sistema ha identificat una cara duplicada d’una altra sessió aprovada, la qual cosa requereix una investigació addicional.
`POSSIBLE_DUPLICATED_FACE`	Possible cara duplicada d’una altra sessió aprovada	El sistema ha identificat una possible cara duplicada d’una altra sessió aprovada, la qual cosa requereix una investigació addicional.
`DUPLICATED_FACE_NAME_MISMATCH`	Cara duplicada amb un nom diferent	La mateixa cara ja s’havia aprovat en una altra sessió, però amb un nom diferent. La identitat associada al duplicat no coincideix amb la identitat declarada en aquesta sessió, cosa que és un fort indicador de frau d’identitat.
`MULTIPLE_FACES_DETECTED` (Només en mode passiu)	Múltiples cares detectades	S’han detectat múltiples cares a la imatge de prova de vida. El sistema utilitza la cara més gran per a la verificació de prova de vida i la comparació facial, però la presència de múltiples cares pot requerir una revisió addicional.
`LOW_FACE_QUALITY` (Només en mode passiu)	Baixa qualitat de la cara	La qualitat de la imatge facial està per sota del llindar acceptable, cosa que pot afectar la fiabilitat de la detecció de prova de vida. Això es podria deure a la resolució de la càmera, l’enfocament o artefactes de compressió.
`LOW_FACE_LUMINANCE` (Només en mode passiu)	Baixa lluminositat facial	La imatge facial és massa fosca, cosa que pot afectar la precisió de la detecció de prova de vida. Es recomanen millors condicions d’il·luminació.
`HIGH_FACE_LUMINANCE` (Només en mode passiu)	Alta lluminositat facial	La imatge facial és massa brillant o sobreexposada, cosa que pot afectar la precisió de la detecció de prova de vida. Es recomana reduir la il·luminació o evitar la llum directa.
`LIVENESS_MAX_ATTEMPTS_EXCEEDED`	S’ha superat el nombre màxim d’intents de prova de vida	S’ha assolit el nombre màxim d’intents de captura de prova de vida. S’ha aplicat l’estat calculat de l’últim intent (rebuig o revisió).

Les coincidències amb llista de bloqueig, llista d’admesos i duplicats inclouen additional_data amb la sessió coincident (blocklisted_session_id / allowlisted_session_id / duplicated_session_id, el *_session_number coincident i api_service). Només apareix un d’aquests sis codis per informe. DUPLICATED_FACE_NAME_MISMATCH és l’excepció: s’emet a més de DUPLICATED_FACE, mai en lloc d’aquest, quan la identitat de la sessió coincident no coincideix amb el nom resolt d’aquesta sessió. El seu additional_data afegeix name_match_score als mateixos camps de sessió duplicada. Un nom escrit en un sistema d’escriptura diferent a cada costat no es considera una discrepància quan els documents d’identitat de les dues sessions comparteixen l’estat emissor, un número de document o d’identificació personal exacte i una data de naixement no contradictòria. Consulta Advertències de prova de vida.

Advertències de coincidència facial

`risk`	`short_description`	`long_description`
`LOW_FACE_MATCH_SIMILARITY`	Baixa similitud de coincidència facial	Els trets facials de la imatge proporcionada no coincideixen prou amb la imatge de referència, cosa que suggereix una possible discrepància d’identitat.
`NO_REFERENCE_IMAGE`	No s’ha trobat cap imatge d’origen per fer la coincidència facial	Manca una imatge de referència per a la comparació facial, fet que impedeix al sistema completar el procés de coincidència facial.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	S’ha superat el nombre màxim d’intents de coincidència facial	S’ha assolit el nombre màxim d’intents de captura de coincidència facial. S’ha aplicat l’estat calculat de l’últim intent (rebuig o revisió).

Exemple: rebutjada per atac 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
}

Exemple: en revisió per baixa 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ó (58.70) se situa entre el llindar de rebuig (per defecte 50) i el llindar de revisió (per defecte 70), de manera que l’advertència porta log_type: "warning" i l’estat de coincidència facial és In Review. En aquest exemple, l’advertència s’ha activat en una sessió el session_id de la qual és 11111111-2222-3333-4444-555555555555; source_image_session_id porta l’identificador propi de la sessió perquè la referència provenia del retrat emmagatzemat en crear la sessió.

Tipus d’advertències

A cada risc se li assigna un tipus d’advertència segons la configuració de la teva aplicació. Les advertències es classifiquen en tres categories de gravetat:

Relacionat

Informe d'autenticació biomètrica

On apareixen liveness_checks[] i face_matches[] a la decisió de la V3.

Advertències de prova de vida

Referència completa d’advertències de prova de vida, incloent-hi la coincidència de cares duplicades.

Advertències de coincidència facial

Referència completa d’advertències de coincidència facial per a comparacions 1:1.

Autenticació

Verificació

Monitoratge

Plataforma

Advertències i codis d'autenticació biomètrica

Visió general

On apareixen les advertències

Condicions de rebuig automàtic

Llindars i accions configurables

Reintents de captura

Advertències de prova de vida

Advertències de coincidència facial

Exemple: rebutjada per atac facial

Exemple: en revisió per baixa similitud

Tipus d’advertències

Relacionat

Informe d'autenticació biomètrica

Advertències de prova de vida

Advertències de coincidència facial

​Visió general

​On apareixen les advertències

​Condicions de rebuig automàtic

​Llindars i accions configurables

​Reintents de captura

​Advertències de prova de vida

​Advertències de coincidència facial

​Exemple: rebutjada per atac facial

​Exemple: en revisió per baixa similitud

​Tipus d’advertències

​Relacionat

Informe d'autenticació biomètrica

Advertències de prova de vida

Advertències de coincidència facial

Visió general

On apareixen les advertències

Condicions de rebuig automàtic

Llindars i accions configurables

Reintents de captura

Advertències de prova de vida

Advertències de coincidència facial

Exemple: rebutjada per atac facial

Exemple: en revisió per baixa similitud

Tipus d’advertències

Relacionat