> ## 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.

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

> Разбор отчёта сравнения лиц 1:1 от Didit: статус, оценка сходства, URL изображений, предупреждения и структура данных в ответах API.

## Обзор

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

Отчёт формируется после того, как пользователь завершит и шаг проверки живости, и шаг документа в сценарии (или, для сценариев на основе портрета, таких как биометрическая аутентификация, только после проверки живости), либо напрямую через отдельный [API сравнения лиц](https://docs.didit.me/ru/standalone-apis/face-match.md), когда вы сами передаёте два произвольных изображения лиц.

Каждый отчёт содержит собственный `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](https://docs.didit.me/ru/core-technology/age-estimation/overview.md#адаптивная-оценка-возраста) также заполняет его при срабатывании резервной проверки личности: в этой записи узел оценки возраста указывается в качестве `node_id`, поскольку в самом сценарии нет отдельного узла сравнения лиц.

* **API решения по сессии** — `GET /v3/session/{sessionId}/decision/` возвращает `face_matches[]` на верхнем уровне. См. [Получение решения по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md).
* **Вебхуки** — в payload события `session.status.updated` включается тот же массив `face_matches[]`, как только шаг сформирует данные. См. [Вебхуки](https://docs.didit.me/ru/integration/webhooks.md).
* **Отдельный Face Match API** — прямое сравнение 1:1 описано в разделе [Отдельный Face Match API](https://docs.didit.me/ru/standalone-apis/face-match.md).

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

## Схема

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

| Поле | Тип | Описание |
| - | - | - |
| `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` — см. [Предупреждения сравнения лиц](https://docs.didit.me/ru/core-technology/face-match/warnings-face-match.md). |

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

| Статус | Значение | Влияние на последующие шаги |
| - | - | - |
| `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`.

## Примеры

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

```json theme={null}
{
  "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": []
    }
  ]
}
```

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

```json theme={null}
{
  "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"
        }
      ]
    }
  ]
}
```

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

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

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

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


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