Informe de Face Match: JSON de puntuación de similitud

Descripción general

El informe de coincidencia facial recoge una comparación biométrica 1:1 entre la selfie en vivo capturada durante la prueba de vida y una imagen de referencia, que suele ser el retrato extraído del documento de identidad. Devuelve una única puntuación de similitud de 0 a 100, URL firmadas de las dos imágenes comparadas, la sesión de origen de la imagen de referencia y las advertencias que haya generado la comparación. El informe se genera cuando el usuario completa tanto el paso de prueba de vida como el paso de documento en un flujo de verificación (workflow) (o, en flujos basados en retrato como la autenticación biométrica, solo tras la prueba de vida). También se genera directamente con la API de coincidencia facial independiente cuando tú mismo proporcionas dos imágenes de rostro cualesquiera. Cada informe tiene su propio status, independiente del estado general de la sesión, que refleja solo cómo se resolvió el paso de coincidencia facial:

Approved: score supera el umbral de revisión y no se activó ninguna advertencia de rechazo automático.
In Review: score está entre los umbrales de rechazo y de revisión, o no se pudo calcular ninguna puntuación y face_match_not_computed_action es REVIEW.
Declined: score es igual o inferior al umbral de rechazo, se activó NO_REFERENCE_IMAGE, o no se pudo calcular ninguna puntuación y face_match_not_computed_action es DECLINE.
Resub Requested: un revisor solicitó desde la consola que el usuario vuelva a enviar este paso.
Not Finished: el paso de coincidencia facial aún no ha producido un resultado (también mientras el usuario reintenta una captura fallida).

Dónde aparece en las respuestas de la API

El informe de coincidencia facial se incluye en el array face_matches[], que siempre es un array JSON y nunca un objeto face_match singular. Es null hasta que al menos un paso de coincidencia facial haya producido datos, y aparecen varias entradas cuando un flujo ejecuta la coincidencia facial más de una vez. Un flujo de verificación de edad adaptativa también lo rellena cuando se ejecuta el mecanismo alternativo de verificación de identidad: esa entrada indica el ID del nodo de estimación de edad en su node_id, ya que el flujo no tiene un nodo propio de coincidencia facial.

API de decisión de sesión: GET /v3/session/{sessionId}/decision/ devuelve face_matches[] en el nivel superior. Consulta Obtener la decisión de la sesión.
Webhooks: los payloads de session.status.updated incluyen el mismo array face_matches[] en cuanto el paso ha producido datos. Consulta Webhooks.
API de coincidencia facial independiente: para comparaciones 1:1 directas, consulta la API independiente de coincidencia facial.

Lee response.face_matches[0] y recorre el array: la estructura singular face_match que mencionaban algunos tutoriales antiguos no existe en el endpoint de decisión v3.

Esquema

El esquema canónico campo por campo se encuentra en la página de referencia Modelos de datos. Los campos siguientes reflejan ese esquema canónico.

Campo	Tipo	Descripción
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Estado del paso de coincidencia facial (`FeatureStatusChoices`).
`node_id`	string \| null	Nodo del grafo del flujo de trabajo que generó este informe.
`score`	number 0–100 \| null	Puntuación de similitud biométrica, redondeada a 2 decimales. `null` cuando no fue posible realizar la comparación.
`source_image_session_id`	string \| null	UUID de la sesión cuyo retrato almacenado proporcionó la imagen de referencia (origen). Se establece en flujos basados en retrato (autenticación biométrica o un retrato proporcionado al crear la sesión). `null` cuando la imagen de referencia es el retrato del documento capturado en la misma sesión.
`source_image`	string (URL firmada)	La imagen de referencia (normalmente el retrato del documento). URL firmada de corta duración: descárgala cuanto antes y nunca guardes la URL.
`target_image`	string (URL firmada)	La imagen objetivo (normalmente la selfie de la prueba de vida). URL firmada de corta duración: descárgala cuanto antes y nunca guardes la URL.
`warnings[]`	array	Advertencias del módulo. Cada entrada incluye `feature` (siempre `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` y `node_id`. Consulta Advertencias de coincidencia facial.

Valores de estado

Estado	Significado	Efecto posterior
`Approved`	La puntuación supera el umbral de revisión y no se activó ninguna advertencia de rechazo automático.	Cuenta como una coincidencia facial exitosa.
`In Review`	La puntuación supera el umbral de rechazo pero es igual o inferior al umbral de revisión, o no se pudo calcular ninguna puntuación (`FACE_MATCH_NOT_COMPUTED`, por ejemplo tras una consulta que no es de documento y que no dejó ninguna referencia) con `face_match_not_computed_action` configurado como `REVIEW`.	La sesión también pasa a `In Review` hasta que un revisor actúe.
`Declined`	La puntuación es igual o inferior al umbral de rechazo, se activó `NO_REFERENCE_IMAGE`, o no se pudo calcular ninguna puntuación con `face_match_not_computed_action` configurado como `DECLINE`.	La sesión se rechaza salvo que otra rama aprobada cumpla los requisitos del flujo.
`Resub Requested`	Un revisor solicitó desde la consola que se vuelva a enviar este paso.	Se pide al usuario que vuelva a realizar la captura.
`Not Finished`	El paso de coincidencia facial no ha producido un resultado (faltaba una entrada, el flujo nunca llegó al paso de comparación o el usuario sigue dentro del ciclo de reintentos de captura).	La rama no se completó.

Los fallos por baja similitud se reintentan antes de que el estado quede fijado: el usuario dispone de hasta face_match_max_attempts intentos de captura (3 por defecto) y solo se aplica la puntuación del último intento. Las reglas de estado personalizadas configuradas en el nodo del flujo pueden ajustar además el estado resultante, combinándose con el estado derivado de la puntuación según la precedencia Declined > In Review > Approved.

Ejemplos

Aprobado: coincidencia limpia

{
  "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ón: similitud dudosa

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

Rechazado: no hay imagen de referencia con la que 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 seguridad

Las URL firmadas de source_image y target_image son datos biométricos y caducan tras un breve periodo de validez. Trátalas como datos de corta duración: no las almacenes en caché ni las expongas públicamente. Normalmente tu aplicación solo necesita status y score: guarda lo mínimo posible para reducir los datos biométricos en tus servidores.

Relacionado

Advertencias de coincidencia facial — enum completo de advertencias, causas y cómo resolverlas.
Informe de prueba de vida — el paso previo que captura la imagen objetivo.
Webhooks — escucha session.status.updated para recibir el informe.
Modelos de datos — Coincidencia facial — esquema canónico con todos los campos.

Autenticación

Verificación

Monitorización

Plataforma

Informe de Face Match: JSON de puntuación de similitud

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Ejemplos

Aprobado: coincidencia limpia

En revisión: similitud dudosa

Rechazado: no hay imagen de referencia con la que comparar

Nota de seguridad

Relacionado

​Descripción general

​Dónde aparece en las respuestas de la API

​Esquema

​Valores de estado

​Ejemplos

​Aprobado: coincidencia limpia

​En revisión: similitud dudosa

​Rechazado: no hay imagen de referencia con la que comparar

​Nota de seguridad

​Relacionado

Descripción general

Dónde aparece en las respuestas de la API

Esquema

Valores de estado

Ejemplos

Aprobado: coincidencia limpia

En revisión: similitud dudosa

Rechazado: no hay imagen de referencia con la que comparar

Nota de seguridad

Relacionado