Отчёт о биометрической аутентификации: схема JSON

Отчёт по биометрической аутентификации представляет собой способ, с помощью которого Didit передаёт результаты повторной верификации возвращающегося пользователя. Сценарий выполняет новую проверку живости и, если в сценарии включено Сравнение лиц, сравнение лиц 1:1 с эталонным лицом, определённым при создании сессии (переданное вами portrait_image или сохранённое лицо пользователя, найденное по vendor_data). Обе проверки отображаются как стандартные элементы функций в ответе с решением по сессии V3.

Отчёт Didit по биометрической аутентификации, объединяющий проверку живости и сравнение лиц с сохранённым портретом

Обзор

Биометрическая аутентификация представляет собой тип сценария (workflow_type: "biometric_authentication"), а не отдельный объект ответа. При выполнении сценария формируются:

Одна проверка живости, которая снимает селфи в реальном времени и оценивает его на наличие спуфинга.
Одно сравнение лиц, сравнивающее полученное лицо с эталонным лицом, определённым при создании сессии (только если Сравнение лиц включено в сценарии).

Всякий раз, когда сценарий включает Сравнение лиц, для создания сессии требуется эталонное лицо. Передайте portrait_image (изображение в кодировке base64, максимум 2MB) или опустите его, и Didit повторно использует лицо, уже сохранённое для пользователя с этим vendor_data: сначала одобренное лицо из проверки живости, затем фото с чипа электронного паспорта, затем портрет из документа, удостоверяющего личность, затем лицо из профиля, зарегистрированное вручную. Если недоступны ни portrait_image, ни сохранённое лицо, создание сессии возвращает 400 с

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

. В обоих случаях определённый эталон записывается в новой сессии, поэтому поле source_image_session_id элемента сравнения лиц получает значение session_id самой этой сессии (это указывает на то, что эталон взят из сохранённого портрета сессии, а не из портрета в документе, полученного в рамках той же сессии, что оставило бы поле со значением null).

Где появляется

Ключ в ответе с решением	Множественное число	Схема элемента
`liveness_checks[]`	По одному на каждый шаг проверки живости (обычно 1 в биометрической аутентификации)	data-models#liveness-check
`face_matches[]`	По одному на каждый шаг сравнения лиц (`null` в сценариях только с проверкой живости)	data-models#face-match

Оба массива возвращает endpoint GET /v3/session/{sessionId}/decision/ для сессий с типом сценария biometric_authentication. Они всегда являются массивами — никогда отдельными объектами — и каждый из них равен null до тех пор, пока соответствующий шаг не сгенерирует данные. Каждый элемент содержит node_id, чтобы сценарии с несколькими экземплярами могли однозначно различать шаги.

Справочник по схеме

Полный список полей определён один раз на странице моделей данных, чтобы у каждого отчёта, использующего эти функции, был единый источник истины:

Схема элемента проверки живости — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
Схема элемента сравнения лиц — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
Формат записи предупреждения — feature, risk, additional_data, log_type, short_description, long_description, node_id.

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

И liveness_checks[].status, и face_matches[].status используют общий жизненный цикл функции (статусы на уровне функций):

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

Общий status сессии агрегирует оба элемента: любая функция в статусе Declined отклоняет сессию, любая в статусе In Review переводит сессию в статус In Review, иначе Approved (после завершения работы всех функций). Подробнее о поведении порогов и полный список кодов предупреждений см. в разделе Предупреждения биометрической аутентификации.

Пример — проверка живости + сравнение лиц (одобрено)

Примеры сокращены: полная структура ответа также содержит session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at и expires_at.

{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

Пример — только проверка живости (Сравнение лиц отключено в сценарии)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "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": []
    }
  ],
  "face_matches": null
}

Режим только проверки живости представляет собой конфигурацию сценария: когда Сравнение лиц отключено, эталонное лицо при создании сессии не требуется, и face_matches остаётся null. Когда Сравнение лиц включено, пропуск portrait_image не приводит к переключению в режим только проверки живости: Didit повторно использует лицо, сохранённое для пользователя с данным vendor_data, а если сохранённого лица нет, создание сессии завершается ошибкой 400.

Пример — сравнение лиц отклонено из-за низкого сходства

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "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": "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"
        }
      ]
    }
  ]
}

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

Поля reference_image, video_url, source_image и target_image представляют собой подписанные URL-адреса, срок действия которых ограничен (по умолчанию 4 часа). Они ведут на биометрические данные — не кешируйте и не публикуйте их в открытом доступе. Сохраняйте результат верификации (статус, оценка, source_image_session_id) на своей стороне; повторно вызовите endpoint решения, если вам нужны свежие URL-адреса.

Связанные материалы

Предупреждения биометрической аутентификации

Коды предупреждений, пороги и условия автоматического отклонения.

Отчёт по проверке живости

Полный справочник полей для элементов liveness_checks[].

Отчёт по сравнению лиц

Полный справочник полей для элементов face_matches[].

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

Верификация

Мониторинг

Платформа

Отчёт о биометрической аутентификации: схема JSON

Обзор

Где появляется

Справочник по схеме

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

Пример — проверка живости + сравнение лиц (одобрено)

Пример — только проверка живости (Сравнение лиц отключено в сценарии)

Пример — сравнение лиц отклонено из-за низкого сходства

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

Связанные материалы

Предупреждения биометрической аутентификации

Отчёт по проверке живости

Отчёт по сравнению лиц

​Обзор

​Где появляется

​Справочник по схеме

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

​Пример — проверка живости + сравнение лиц (одобрено)

​Пример — только проверка живости (Сравнение лиц отключено в сценарии)

​Пример — сравнение лиц отклонено из-за низкого сходства

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

​Связанные материалы

Предупреждения биометрической аутентификации

Отчёт по проверке живости

Отчёт по сравнению лиц

Обзор

Где появляется

Справочник по схеме

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

Пример — проверка живости + сравнение лиц (одобрено)

Пример — только проверка живости (Сравнение лиц отключено в сценарии)

Пример — сравнение лиц отклонено из-за низкого сходства

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

Связанные материалы