Informe de coincidència facial: JSON i puntuació

Visió general

L’informe de coincidència facial recull una comparació biomètrica 1:1 entre la selfie en directe capturada durant la prova de vida i una imatge de referència —més habitualment el retrat extret del document d’identitat. Retorna una única puntuació de similitud de 0 a 100, URL signades per a les dues imatges comparades, la sessió d’origen de la imatge de referència i qualsevol advertència generada per la coincidència. L’informe es genera després que l’usuari completi tant el pas de prova de vida com el de document en un flux de treball (o, per a fluxos de treball basats en retrat com ara l’autenticació biomètrica, només després de la prova de vida), o directament mitjançant l’API de coincidència facial independent quan proporciones tu mateix dues imatges facials arbitràries. Cada informe inclou el seu propi status —independent de l’estat general de la sessió— que reflecteix com s’ha resolt el pas de coincidència facial per si sol:

Aprovada — score se situa per sobre del llindar de revisió i no s’ha activat cap advertència de rebuig automàtic.
En revisió — score es troba entre els llindars de rebuig i de revisió, o no s’ha pogut calcular cap puntuació i face_match_not_computed_action és REVIEW.
Rebutjada — score se situa en el llindar de rebuig o per sota, s’ha activat NO_REFERENCE_IMAGE, o no s’ha pogut calcular cap puntuació i face_match_not_computed_action és DECLINE.
Reenviament sol·licitat — un revisor ha sol·licitat des de la consola que l’usuari torni a enviar aquest pas.
No finalitzat — el pas de coincidència facial encara no ha generat cap resultat (inclòs mentre l’usuari reintenta una captura fallida).

On apareix a les respostes de l’API

L’informe de coincidència facial s’envia dins de la matriu face_matches[] —sempre una matriu JSON, mai un objecte singular face_match. És null fins que almenys un pas de coincidència facial hagi generat dades, i apareixen múltiples entrades quan un flux de treball executa la coincidència facial més d’una vegada. Un flux de treball d’Adaptive Age Verification també l’omple quan s’executa l’alternativa de verificació d’identitat: aquesta entrada indica el node d’estimació d’edat com el seu node_id, ja que el flux de treball no té cap node de coincidència facial propi.

API de decisió de sessió — GET /v3/session/{sessionId}/decision/ retorna face_matches[] al nivell superior. Consulta Recuperar la decisió de la sessió.
Webhooks — els payloads de session.status.updated inclouen la mateixa matriu face_matches[] un cop el pas ha generat dades. Consulta Webhooks.
API independent de coincidència facial — per a comparacions 1:1 directes, consulta l’API independent de coincidència facial.

Llegeix response.face_matches[0] i itera per la matriu; l’estructura singular face_match a la qual feien referència alguns tutorials antics no existeix a l’endpoint de decisió v3.

Esquema

L’esquema canònic camp per camp es troba a la pàgina de referència de Models de dades. Els camps següents reflecteixen aquest esquema canònic.

Camp	Tipus	Descripció
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Estat del pas de coincidència facial (`FeatureStatusChoices`).
`node_id`	string \| null	Node del graf del flux de treball que ha generat aquest informe.
`score`	number 0–100 \| null	Puntuació de similitud biomètrica, arrodonida a 2 decimals. `null` quan no ha estat possible fer cap comparació.
`source_image_session_id`	string \| null	UUID de la sessió el retrat emmagatzemat de la qual ha proporcionat la imatge de referència (origen); s’estableix en fluxos basats en retrat (autenticació biomètrica o un retrat proporcionat en crear la sessió). `null` quan la imatge de referència és el retrat del document capturat a la mateixa sessió.
`source_image`	string (URL signada)	La imatge de referència (normalment el retrat del document). URL signada de curta durada: descarrega-la ràpidament, no la persistisquis mai.
`target_image`	string (URL signada)	La imatge objectiu (normalment la selfie de la prova de vida). URL signada de curta durada: descarrega-la ràpidament, no la persistisquis mai.
`warnings[]`	array	Advertències a nivell de mòdul. Cada entrada inclou `feature` (sempre `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` i `node_id`; consulta Advertències de coincidència facial.

Valors d’estat

Estat	Significat	Efecte posterior
`Approved`	Puntuació per sobre del llindar de revisió i no s’ha activat cap advertència de rebuig automàtic.	Compta com a coincidència facial satisfactòria.
`In Review`	Puntuació per sobre del llindar de rebuig però en el llindar de revisió o per sota, o no s’ha pogut calcular cap puntuació (`FACE_MATCH_NOT_COMPUTED`, per exemple després d’una cerca sense document que no ha deixat cap referència) amb `face_match_not_computed_action` establert a `REVIEW`.	La sessió també passa a `In Review` fins que un revisor hi intervingui.
`Declined`	Puntuació en el llindar de rebuig o per sota, s’ha activat `NO_REFERENCE_IMAGE`, o no s’ha pogut calcular cap puntuació amb `face_match_not_computed_action` establert a `DECLINE`.	La sessió es rebutja tret que una altra branca aprovada compleixi el flux de treball.
`Resub Requested`	Un revisor ha sol·licitat reenviar aquest pas des de la consola.	Es demana a l’usuari que torni a fer la captura.
`Not Finished`	El pas de coincidència facial no ha generat cap resultat (mancava una entrada, el flux de treball mai ha arribat al pas de comparació o l’usuari encara es troba dins del cicle de reintent de captura).	La branca no s’ha completat.

Les captures que fallen per baixa similitud es tornen a intentar abans que l’estat quedi fixat: l’usuari disposa de fins a face_match_max_attempts captures (3 per defecte), i només s’aplica la puntuació de l’últim intent. Les regles d’estat personalitzades configurades al node del flux de treball poden ajustar encara més l’estat resultant, combinant-se amb l’estat derivat de la puntuació sota la precedència Declined > In Review > Approved.

Exemples

Aprovada — coincidència clara

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

En revisió — similitud al límit

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.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_1"
        }
      ]
    }
  ]
}

Rebutjada — sense imatge de referència per comparar

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "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"
        }
      ]
    }
  ]
}

Nota de seguretat

Les URL signades per a source_image i target_image són dades biomètriques i caduquen després d’una finestra de validesa curta. Tracta-les com a elements de curta durada: no les desis a la memòria cau ni les exposis públicament. Normalment la teva aplicació només necessita status i score: emmagatzema tan poc com sigui possible per minimitzar les dades biomètriques als teus servidors.

Relacionat

Advertències de coincidència facial — enum complet d’advertències, causes i resolució.
Informe de prova de vida — el pas previ que captura la imatge objectiu.
Webhooks — escolta session.status.updated per rebre l’informe.
Models de dades — Coincidència facial — esquema canònic amb tots els camps.

Autenticació

Verificació

Monitoratge

Plataforma

Informe de coincidència facial: JSON i puntuació

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Exemples

Aprovada — coincidència clara

En revisió — similitud al límit

Rebutjada — sense imatge de referència per comparar

Nota de seguretat

Relacionat

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Valors d’estat

​Exemples

​Aprovada — coincidència clara

​En revisió — similitud al límit

​Rebutjada — sense imatge de referència per comparar

​Nota de seguretat

​Relacionat

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Exemples

Aprovada — coincidència clara

En revisió — similitud al límit

Rebutjada — sense imatge de referència per comparar

Nota de seguretat

Relacionat