Coincidència facial: advertències i codis d'error

Visió general

Les advertències a l’informe de coincidència facial assenyalen cada condició que Didit ha detectat en executar la comparació facial 1:1. Es recullen a l’array warnings[] de cada element de face_matches[] (consulta Informe de coincidència facial). Cada entrada també inclou feature: "FACEMATCH" i el node_id del node del flux de treball que l’ha generada. Cada advertència té tres capes:

El codi de risk — un identificador estable amb què pots fer comparacions al teu codi.
El log_type — information, warning o error, derivat dels llindars de puntuació de similitud del teu flux de treball.
L’impacte en la decisió — determinat pels llindars de revisió i rebuig del flux de treball per a la puntuació de similitud.

El mòdul de coincidència facial és intencionadament reduït: hi ha exactament cinc codis de risc, que es detallen a continuació.

Condicions de rebuig automàtic

El risc següent sempre força l’estat de l’informe de coincidència facial (i de la sessió) a Declined:

Risc	Activador
`NO_REFERENCE_IMAGE`	Falta una de les dues imatges, `source_image` (referència) o `target_image` (selfie), de manera que no ha estat possible fer cap comparació.

Quan s’activa NO_REFERENCE_IMAGE, se suprimeix LOW_FACE_MATCH_SIMILARITY (no hi ha res per puntuar). Hi ha una excepció. Quan el pas d’identificació s’ha completat mitjançant una consulta sense document en què el registre no retorna cap retrat ni comprova cap cara, Coincidència facial no té res amb què comparar la captura en directe per disseny. Això s’informa com a FACE_MATCH_NOT_COMPUTED amb una puntuació null i es decideix mitjançant face_match_not_computed_action (més avall), no pas com un rebuig automàtic.

Configuració de verificació

A la consola de Didit, la puntuació de similitud de coincidència facial es regeix per dos llindars (sense commutador Approve/Review/Decline):

Configuració	Per defecte	Comportament
`face_match_score_review_threshold`	70	Quan `score` és inferior o igual a aquest valor, s’activa `LOW_FACE_MATCH_SIMILARITY` i l’estat passa a `In Review`.
`face_match_score_decline_threshold`	50	Quan `score` és inferior o igual a aquest valor, la mateixa advertència s’eleva al nivell `error` i l’estat passa a `Declined`.

Ajusta el llindar de revisió a un valor més alt si detectes massa aprovacions falses; ajusta el llindar de rebuig a un valor més baix si detectes massa rebuigs falsos. Una configuració independent controla què passa quan una puntuació de similitud no es pot calcular de cap manera: no s’ha detectat cap cara en una de les imatges, o bé una consulta sense document no ha deixat cap referència contra la qual comparar:

Configuració	Per defecte	Comportament
`face_match_not_computed_action`	`REVIEW`	Acció que s’aplica un cop el resultat de «no s’ha pogut calcular» esdevé definitiu. `REVIEW` envia l’informe a `In Review`; `DECLINE` l’estableix a `Declined`. (No hi ha cap opció d’aprovació automàtica: una puntuació que no s’ha calculat mai no s’aprova silenciosament).

Aquesta acció regeix FACE_MATCH_NOT_COMPUTED (sense cara al retrat del document, o sense cap referència després d’una consulta sense document) i un NO_FACE_IN_SELFIE esgotat (sense cara a la selfie després dels reintents de l’usuari). Quan el problema és la selfie, primer es demana a l’usuari que torni a fer la captura (consulta més avall) i l’acció només s’aplica si encara no es pot detectar cap cara un cop s’ha esgotat el límit d’intents. Els errors per baixa similitud també entren en un bucle de reintent de captura abans que l’estat es consolidi: l’usuari disposa de fins a face_match_max_attempts intents en total (3 per defecte, configurable entre 2 i 5 per node del flux de treball) per tornar a fer la captura. Un error per NO_FACE_IN_SELFIE utilitza el mateix bucle de reintents, ja que tornar a fer una captura més clara de la selfie pot solucionar-ho. Un error per FACE_MATCH_NOT_COMPUTED no es reintenta: el retrat del document no es pot tornar a capturar en aquest pas. Només quan s’esgota el límit d’intents s’aplica l’estat del darrer intent, i es registra FACE_MATCH_MAX_ATTEMPTS_EXCEEDED per deixar-ne constància. A l’API de coincidència facial autònoma només existeix un llindar de rebuig (opció de sol·licitud face_match_score_decline_threshold, per defecte 30); qualsevol advertència que s’activi rebutja la sol·licitud, i NO_REFERENCE_IMAGE s’activa quan no s’ha pogut comparar cap cara en absolut.

Advertències generades

Risc	Causa	Gravetat	Afecta l’estat?	Solució
`LOW_FACE_MATCH_SIMILARITY`	`score` ≤ `face_match_score_review_threshold`. Se suprimeix quan `NO_REFERENCE_IMAGE` també és present.	`warning` entre els llindars; `error` al llindar de rebuig o per sota	`In Review` entre els llindars; `Declined` al llindar de rebuig o per sota	Ajusta els llindars o accepta mitjançant revisió manual.
`FACE_MATCH_NOT_COMPUTED`	No s’ha pogut calcular una puntuació de similitud perquè no s’ha detectat cap cara al retrat del document, o perquè el pas d’identificació era una consulta sense document que no ha deixat cap referència amb la qual comparar (un registre que no retorna cap retrat i no comprova cap cara). Se suprimeix quan `NO_REFERENCE_IMAGE` també és present.	`warning` quan `face_match_not_computed_action` és `REVIEW`; `error` quan és `DECLINE`	`In Review` o `Declined`, segons `face_match_not_computed_action`	La imatge del document no es pot tornar a capturar en aquest pas: resol mitjançant revisió manual o torna a capturar el document prèviament en el flux. Després d’una consulta de només dades, defineix `face_match_not_computed_action` amb el resultat que vulguis, o exigeix un document en països on la coincidència biomètrica sigui rellevant.
`NO_FACE_IN_SELFIE`	No s’ha pogut calcular una puntuació de similitud perquè no s’ha detectat cap cara a la selfie de l’usuari. Es demana a l’usuari que torni a fer-se la selfie abans que es confirmi aquesta advertència.	`warning` quan `face_match_not_computed_action` és `REVIEW`; `error` quan és `DECLINE`	`In Review` o `Declined`, segons `face_match_not_computed_action`, un cop esgotats els reintents	L’usuari torna a capturar una selfie més clara, ben il·luminada i frontal.
`NO_REFERENCE_IMAGE`	Falta la imatge de referència o la imatge d’objectiu (tret d’una referència que una consulta sense document mai no hagi generat, que és `FACE_MATCH_NOT_COMPUTED`).	`error`	Rebuig automàtic	Assegura’t que es capturin tant el retrat del document com la selfie de prova de vida. Per a l’API independent, passa dues imatges facials vàlides.
`FACE_MATCH_MAX_ATTEMPTS_EXCEEDED`	L’usuari ha esgotat el límit de reintents de captura (`face_match_max_attempts`) després de fallades repetides de baixa similitud.	`information`	No: registra que s’ha aplicat l’estat calculat de l’últim intent (rebuig o revisió)	Augmenta `face_match_max_attempts` al node del flux de treball o resol mitjançant revisió manual.

Exemples

En revisió: similitud limítrofa

"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_1"
  }
]

En revisió: no s’ha pogut calcular la coincidència facial

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]

Rebuig automàtic: falta la referència

"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]

Reintents esgotats: s’ha aplicat l’estat de l’últim intent

"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_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]

L’API de coincidència facial independent retorna la mateixa estructura d’advertència menys node_id (la comparació no està vinculada a un node del flux de treball).

Tipus d’advertència

A cada risc se li assigna una gravetat basada en la configuració de la teva aplicació. Les tres gravetats són:

Relacionat

Informe de coincidència facial: esquema complet de l’informe i estats.
Advertències de prova de vida: advertències prèvies durant la captura de la selfie.
Webhooks: session.status.updated transmet les advertències tan bon punt finalitza el pas.
Models de dades: Coincidència facial: esquema canònic.
Models de dades: Objecte d’advertència: estructura de cada entrada de warnings[].

Autenticació

Verificació

Monitoratge

Plataforma

Coincidència facial: advertències i codis d'error

Visió general

Condicions de rebuig automàtic

Configuració de verificació

Advertències generades

Exemples

En revisió: similitud limítrofa

En revisió: no s’ha pogut calcular la coincidència facial

Rebuig automàtic: falta la referència

Reintents esgotats: s’ha aplicat l’estat de l’últim intent

Tipus d’advertència

Relacionat

​Visió general

​Condicions de rebuig automàtic

​Configuració de verificació

​Advertències generades

​Exemples

​En revisió: similitud limítrofa

​En revisió: no s’ha pogut calcular la coincidència facial

​Rebuig automàtic: falta la referència

​Reintents esgotats: s’ha aplicat l’estat de l’últim intent

​Tipus d’advertència

​Relacionat

Visió general

Condicions de rebuig automàtic

Configuració de verificació

Advertències generades

Exemples

En revisió: similitud limítrofa

En revisió: no s’ha pogut calcular la coincidència facial

Rebuig automàtic: falta la referència

Reintents esgotats: s’ha aplicat l’estat de l’últim intent

Tipus d’advertència

Relacionat