Отчёт о проверке живости: оценки, методы и совпадения

Обзор

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

Одобрена — лицо обнаружено, оценка проверки живости выше порога отправки на проверку, ни одно предупреждение с автоматическим отклонением не сработало.
На проверке — сработало одно или несколько предупреждений, направленных на ручную проверку, либо оценка находится на уровне или ниже порога проверки, но выше порога отклонения.
Отклонена — сработало условие автоматического отклонения (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST или риски по возрасту в сценариях с оценкой возраста), настраиваемое предупреждение было направлено на отклонение, либо оценка находится на уровне или ниже порога отклонения.
Не завершена — пользователь так и не завершил шаг проверки живости.

Где отчёт появляется в ответах API

Отчёт о проверке живости возвращается в виде liveness_checks[] в GET /v3/session/{sessionId}/decision/ — всегда в виде JSON-массива, а не единичного объекта liveness. Несколько записей появляются в тех случаях, когда сценарий запускает проверку живости более одного раза (например, основная проверка плюс повторный захват).

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

Читайте response.liveness_checks[0] и перебирайте элементы массива — структуры в виде единичного объекта liveness, упоминавшейся в некоторых устаревших руководствах, в endpoint решения v3 не существует.

Схема

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

Поле	Тип	Описание
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Статус шага проверки живости (см. ниже).
`node_id`	string \| null	Узел графа сценария, сформировавший этот отчёт.
`method`	`"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`	Метод проверки живости, использованный для этого захвата.
`score`	number 0–100 \| null	Оценка уверенности проверки живости, округлённая до 2 знаков после запятой.
`reference_image`	string (подписанный URL) \| null	Эталонное селфи, извлечённое из захвата. Подписанный URL с ограниченным сроком действия.
`video_url`	string (подписанный URL) \| null	Полное видео захвата проверки живости (активные методы). Подписанный URL с ограниченным сроком действия.
`age_estimation`	number \| null	Оценочный возраст (в годах) наибольшего лица на эталонном изображении.
`face_quality`	number 0–100 \| null	Качество лица при пассивной проверке живости, нормализованное в процентах. Заполняется только при `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Освещённость лица при пассивной проверке живости, нормализованная из диапазона 0–255 в проценты. Заполняется только при `method = "PASSIVE"`.
`matches[]`	array	Межсессионные совпадения лиц (см. ниже).
`warnings[]`	array	Предупреждения на уровне модуля — см. раздел Предупреждения проверки живости. Каждая запись соответствует структуре объекта предупреждения (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Межсессионные совпадения лиц

matches[] содержит список лиц из истории вашего приложения, которые превысили порог биометрического сходства с этим селфи, — до 5 записей: сначала лица из списков блокировки и разрешений, затем по убыванию сходства. Допустимыми кандидатами являются лица из списков блокировки, списков разрешений, лица из сессий со статусом Approved и лица, импортированные для ваших пользователей вендора. Лица, принадлежащие тому же пользователю (тот же vendor_data или тот же пользователь вендора при наличии), исключаются из всего поиска — как при обнаружении дубликатов, так и при проверке по спискам блокировки. Каждая запись включает в себя:

Поле	Тип	Описание
`session_id`	string (UUID) \| null	Совпавшая сессия. `null`, если `source` равен `imported` или `list_entry`.
`session_number`	number \| null	Порядковый номер совпавшей сессии. `null` для источников, не являющихся сессиями.
`similarity_percentage`	number 0–100	Оценка биометрического сходства в диапазоне от 0 до 100.
`vendor_data`	string \| null	Ваши исходные данные из совпавшей сессии (или пользователя вендора для импортированных лиц).
`verification_date`	string (ISO 8601) \| null	Дата и время создания совпавшей сессии (или импортированного лица).
`user_details`	object \| null	`{ full_name, document_type, document_number }` из KYC совпавшей сессии. Для импортированных лиц заполняется только `full_name` (оба поля документа равны `null`); `null`, если данные отсутствуют.
`match_image_url`	string (подписанный URL) \| null	Эталонное лицо из совпавшей сессии, импортированного лица или записи списка.
`status`	string \| null	Статус совпавшей сессии (например, `"Approved"`). `null` для источников, не являющихся сессиями.
`is_blocklisted`	boolean	`true`, если совпавшее лицо находится в вашем списке блокировки лиц.
`is_allowlisted`	boolean	`true`, если совпавшее лицо находится в вашем списке разрешений лиц (действия при обнаружении дубликатов лиц пропускаются).
`api_service`	string \| null	Указывается, если совпавшее лицо получено из отдельного вызова API (например, `"PASSIVE_LIVENESS"`); `null` для сессий сценария и источников, не являющихся сессиями.
`source`	`"session" \| "imported" \| "list_entry"`	Источник совпавшего лица: другая сессия верификации, лицо, загруженное для пользователя вендора, или лицо из списка разрешений/блокировки организации.

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

Статусы поступают из общего перечисления статусов функций (FeatureStatusChoices).

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

Примеры

Approved — корректный захват с активным 3D-методом

{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}

In Review — пассивная проверка живости, низкое качество захвата и возможный дубликат

{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}

Здесь качество лица (12.4) ниже стандартного порога проверки (15), освещённость (18.7) ниже стандартного минимума (20), а действие сценария при обнаружении дубликатов лиц настроено на Review — поэтому все три предупреждения имеют log_type: "warning", и отчёт получает статус In Review.

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

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

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

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

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

Верификация

Мониторинг

Платформа

Отчёт о проверке живости: оценки, методы и совпадения

Обзор

Где отчёт появляется в ответах API

Схема

Межсессионные совпадения лиц

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

Примеры

Approved — корректный захват с активным 3D-методом

In Review — пассивная проверка живости, низкое качество захвата и возможный дубликат

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

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

​Обзор

​Где отчёт появляется в ответах API

​Схема

​Межсессионные совпадения лиц

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

​Примеры

​Approved — корректный захват с активным 3D-методом

​In Review — пассивная проверка живости, низкое качество захвата и возможный дубликат

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

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

Обзор

Где отчёт появляется в ответах API

Схема

Межсессионные совпадения лиц

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

Примеры

Approved — корректный захват с активным 3D-методом

In Review — пассивная проверка живости, низкое качество захвата и возможный дубликат

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

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