> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Отчёт Didit о проверке живости: статус, оценка уверенности, метод, оценка возраста, совпадения лиц между сессиями и структура ответа.

## Обзор

**Отчёт о проверке живости** содержит все данные, которые 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[]` на верхнем уровне. См. [Получение решения по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md).
* **Webhook** — payload события `session.status.updated` содержит тот же массив `liveness_checks[]`, как только на шаге появляются данные. См. [Webhook](https://docs.didit.me/ru/integration/webhooks.md).
* **Отдельный API проверки живости** — см. [Отдельный API проверки живости](https://docs.didit.me/ru/standalone-apis/passive-liveness.md).

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

## Схема

Каноническая схема с описанием каждого поля приведена на справочной странице [Модели данных](https://docs.didit.me/ru/reference/data-models.md#проверка-живости). Поля ниже дублируют эту каноническую схему.

| Поле | Тип | Описание |
| - | - | - |
| `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 | Предупреждения на уровне модуля — см. раздел [Предупреждения проверки живости](https://docs.didit.me/ru/core-technology/liveness/warnings-liveness.md). Каждая запись соответствует структуре [объекта предупреждения](https://docs.didit.me/ru/reference/data-models.md#объект-предупреждения) (`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-методом

```json theme={null}
{
  "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 — пассивная проверка живости, низкое качество захвата и возможный дубликат

```json theme={null}
{
  "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` и предупреждения — храните как можно меньше данных, чтобы минимизировать объём биометрической информации на ваших серверах.

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

* [Предупреждения проверки живости](https://docs.didit.me/ru/core-technology/liveness/warnings-liveness.md) — полный перечень значений enum предупреждений, их причины и способы устранения.
* [Webhook](https://docs.didit.me/ru/integration/webhooks.md) — отслеживайте `session.status.updated` для получения отчёта.
* [Модели данных — Проверка живости](https://docs.didit.me/ru/reference/data-models.md#проверка-живости) — каноническая схема со всеми полями.
* [Отчёт о сравнении лиц](https://docs.didit.me/ru/core-technology/face-match/report-face-match.md) — сопутствующее сравнение лиц 1:1 с портретом из документа.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.