Отчёт о сравнении лиц: JSON и оценка сходства

Обзор

Отчёт сравнения лиц фиксирует биометрическое сравнение 1:1 между селфи, сделанным в ходе проверки живости, и эталонным изображением — чаще всего портретом, извлечённым из документа, удостоверяющего личность. Он возвращает единую оценку сходства от 0 до 100, подписанные URL-адреса для двух сравниваемых изображений, исходную сессию для эталонного изображения и любые предупреждения, возникшие при сопоставлении. Отчёт формируется после того, как пользователь завершит и шаг проверки живости, и шаг документа в сценарии (или, для сценариев на основе портрета, таких как биометрическая аутентификация, только после проверки живости), либо напрямую через отдельный API сравнения лиц, когда вы сами передаёте два произвольных изображения лиц. Каждый отчёт содержит собственный status — независимый от общего статуса сессии, — который отражает результат выполнения именно шага сравнения лиц:

Одобрено — score выше порога отправки на проверку, и предупреждений с автоматическим отклонением не возникло.
На проверке — score находится между порогами отклонения и отправки на проверку, либо оценку не удалось рассчитать и параметр face_match_not_computed_action имеет значение REVIEW.
Отклонено — score находится на уровне порога отклонения или ниже него, сработало предупреждение NO_REFERENCE_IMAGE, либо оценку не удалось рассчитать и параметр face_match_not_computed_action имеет значение DECLINE.
Запрошена повторная отправка — проверяющий запросил повторную отправку этого шага пользователем из консоли.
Не завершено — шаг сравнения лиц ещё не сформировал результат (в том числе пока пользователь повторяет неудачную попытку съёмки).

Где это отображается в ответах API

Отчёт сравнения лиц передаётся внутри массива face_matches[] — всегда в виде массива JSON, а не единичного объекта face_match. Он имеет значение null до тех пор, пока хотя бы один шаг сравнения лиц не сформирует данные; если сценарий запускает сравнение лиц несколько раз, в массиве появляется несколько записей. Сценарий Adaptive Age Verification также заполняет его при срабатывании резервной проверки личности: в этой записи узел оценки возраста указывается в качестве node_id, поскольку в самом сценарии нет отдельного узла сравнения лиц.

API решения по сессии — GET /v3/session/{sessionId}/decision/ возвращает face_matches[] на верхнем уровне. См. Получение решения по сессии.
Вебхуки — в payload события session.status.updated включается тот же массив face_matches[], как только шаг сформирует данные. См. Вебхуки.
Отдельный Face Match API — прямое сравнение 1:1 описано в разделе Отдельный Face Match API.

Считывайте response.face_matches[0] и выполняйте итерацию по массиву — единичная структура face_match, упоминавшаяся в некоторых старых руководствах, в endpoint решения v3 отсутствует.

Схема

Каноническая схема с построчным описанием полей находится на странице справочника Модели данных. Поля ниже соответствуют этой канонической схеме.

Поле	Тип	Описание
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Статус шага сравнения лиц (`FeatureStatusChoices`).
`node_id`	string \| null	Узел графа сценария, который сформировал этот отчёт.
`score`	number 0–100 \| null	Оценка биометрического сходства, округлённая до 2 знаков после запятой. `null`, если сравнение выполнить не удалось.
`source_image_session_id`	string \| null	UUID сессии, из которой сохранённый портрет был использован в качестве эталонного (исходного) изображения — задаётся в сценариях на основе портрета (биометрическая аутентификация или портрет, переданный при создании сессии). `null`, если эталонным изображением служит портрет из документа, снятого в той же сессии.
`source_image`	string (signed URL)	Эталонное изображение (обычно портрет из документа). Подписанный URL с коротким сроком действия — скачивайте сразу, сохранять сам URL запрещено.
`target_image`	string (signed URL)	Целевое изображение (обычно селфи проверки живости). Подписанный URL с коротким сроком действия — скачивайте сразу, сохранять сам URL запрещено.
`warnings[]`	array	Предупреждения на уровне модуля. Каждая запись содержит поля `feature` (всегда `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` и `node_id` — см. Предупреждения сравнения лиц.

Значения статуса

Статус	Значение	Влияние на последующие шаги
`Approved`	Оценка выше порога проверки, предупреждений с автоматическим отклонением нет.	Считается успешным сравнением лиц.
`In Review`	Оценка выше порога отклонения, но на уровне порога проверки или ниже него, либо оценку не удалось рассчитать (`FACE_MATCH_NOT_COMPUTED`, например, после поиска без документа, не оставившего эталона) при значении `face_match_not_computed_action`, равном `REVIEW`.	Сессия также переходит в статус `In Review`, пока проверяющий не выполнит действие.
`Declined`	Оценка на уровне порога отклонения или ниже него, сработало предупреждение `NO_REFERENCE_IMAGE`, либо оценку не удалось рассчитать при значении `face_match_not_computed_action`, равном `DECLINE`.	Сессия отклоняется, если только другая одобренная ветвь не удовлетворяет условиям сценария.
`Resub Requested`	Проверяющий запросил повторную отправку этого шага из консоли.	Пользователю предлагается выполнить съёмку повторно.
`Not Finished`	Шаг сравнения лиц не сформировал результат (отсутствовали входные данные, сценарий так и не дошёл до шага сравнения или пользователь всё ещё находится в цикле повторных попыток съёмки).	Ветвь не завершилась.

При неудачах из-за низкого сходства съёмка повторяется до окончательной фиксации статуса: пользователю даётся до face_match_max_attempts попыток (по умолчанию 3), и учитывается оценка только последней попытки. Пользовательские правила статусов, настроенные на узле сценария, могут дополнительно скорректировать итоговый статус, объединяясь со статусом, полученным на основе оценки, по приоритету Declined > In Review > Approved.

Примеры

Одобрено — чистое совпадение

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

На проверке — пограничное сходство

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

Отклонено — нет эталонного изображения для сравнения

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

Примечание по безопасности

Подписанные URL-адреса для source_image и target_image представляют собой биометрические данные, и срок их действия истекает через короткий промежуток времени. Относитесь к ним как к кратковременным: не кэшируйте их и не делайте общедоступными. Как правило, вашему приложению нужны только status и score — сохраняйте как можно меньше данных, чтобы минимизировать объем биометрических данных на ваших серверах.

Связанные разделы

Предупреждения сравнения лиц — полное перечисление предупреждений, причины и способы исправления.
Отчёт о проверке живости — предшествующий шаг, на котором выполняется захват целевого изображения.
Webhook — настройте получение события session.status.updated, чтобы получать отчёт.
Модели данных — Сравнение лиц — каноническая схема со всеми полями.

Аутентификация

Верификация

Мониторинг

Платформа

Отчёт о сравнении лиц: JSON и оценка сходства

Обзор

Где это отображается в ответах API

Схема

Значения статуса

Примеры

Одобрено — чистое совпадение

На проверке — пограничное сходство

Отклонено — нет эталонного изображения для сравнения

Примечание по безопасности

Связанные разделы

​Обзор

​Где это отображается в ответах API

​Схема

​Значения статуса

​Примеры

​Одобрено — чистое совпадение

​На проверке — пограничное сходство

​Отклонено — нет эталонного изображения для сравнения

​Примечание по безопасности

​Связанные разделы

Обзор

Где это отображается в ответах API

Схема

Значения статуса

Примеры

Одобрено — чистое совпадение

На проверке — пограничное сходство

Отклонено — нет эталонного изображения для сравнения

Примечание по безопасности

Связанные разделы