Отчёт о верификации личности: поля и оценки качества

Обзор

Отчёт о верификации личности содержит все данные, которые Didit извлёк и проверил из официального удостоверения личности государственного образца — паспортов, ID-карт, водительских удостоверений и видов на жительство. Он объединяет распознанные с помощью OCR биографические данные и поля документа, подписанные URL-адреса полученных медиафайлов, разобранные и геолоцированные адресные данные, оценки качества изображений для каждой стороны, содержимое MRZ, детализацию по нескольким системам письма (латиница / нелатиница), а также кросс-сессионные совпадения документов. Отчёт формируется после того, как пользователь завершает шаг захвата документа в сценарии (или вызывает отдельный endpoint для OCR). Didit определяет тип документа, выполняет OCR, проверяет MRZ / штрихкод / QR-код, разбирает адрес, проверяет документ на признаки подделки (съёмка с экрана, распечатанная копия, манипуляции с портретом) и сравнивает документ со всеми другими документами, полученными в вашем приложении. Каждый отчёт имеет собственный status — независимый от общего статуса сессии, — который отражает результат выполнения исключительно шага верификации личности:

Одобрена — документ распознан, все обязательные поля извлечены, предупреждений, ведущих к отклонению, не возникло.
На проверке — сработало одно или несколько предупреждений, и ваш сценарий направляет их на проверку.
Отклонена — сработало условие автоматического отклонения (неподдерживаемый документ, просроченный документ, отсутствует портрет, совпадение со списком блокировки, ошибка адаптивной оценки возраста) либо предупреждение, для которого настроено действие Отклонить (для минимального/максимального возраста по умолчанию задано действие Отклонить).
Истекла — expiration_date документа наступила после верификации. Постоянный мониторинг сроков действия в Didit переводит статус отчёта из Approved в Expired, добавляет предупреждение DOCUMENT_EXPIRED и переводит одобренную сессию в статус сессии Kyc Expired.
Не завершена — пользователь так и не завершил шаг захвата.

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

Отчёт о верификации личности передаётся внутри массива id_verifications[] — всегда в виде JSON-массива, а не отдельного объекта id_verification. Несколько записей появляются, когда сценарий выполняет более одного шага с документами (например, основной документ плюс дополнительный).

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

Считывайте response.id_verifications[0] и выполняйте итерацию по массиву. Структура в виде одиночного объекта id_verification существует только в отдельном OCR API — её нет в endpoint решения v3.

Схема

Каноническая схема с построчным описанием полей приведена на справочной странице Модели данных. Поля ниже взяты напрямую из IDVerificationV3Serializer, который расширяет IDVerificationV2Serializer и добавляет node_id, массив межсессионных совпадений matches[] и массив Silent Capture document_selfie_face_matches[].

Поля верхнего уровня

Поле	Тип	Описание
`status`	`"Approved" \| "Declined" \| "In Review" \| "Expired" \| "Not Finished"`	Статус шага верификации личности.
`node_id`	string \| null	Узел графа сценария, сформировавший этот отчёт.
`document_type`	`"Passport" \| "Identity Card" \| "Driver's License" \| "Residence Permit" \| "Health Insurance Card" \| "Tax Card" \| "Social Security Card" \| "Work Permit" \| "Visa" \| "Public Service Card" \| "Birth Certificate" \| "Firearm License" \| "Other" \| null`	Распознанное семейство документов верхнего уровня (в читаемом виде).
`document_subtype`	string \| null	Код подтипа документа из реестра документов Didit, отфильтрованный с учётом настроек документов сценария. Документы конкретных регионов содержат указание региона, например `QUEENSLAND_DRIVER_LICENSE_GENERIC`. Полный список кодов, включая способ отличить коммерческие водительские права США (CDL) от стандартных, см. в разделе Подтипы документов.
`document_number`	string	Номер документа, распознанный через OCR. О водительских удостоверениях, на которых напечатаны как номер удостоверения, так и номер карты, см. примечание под таблицей.
`personal_number`	string	Личный / национальный идентификационный номер, распознанный через OCR, если он отличается от номера документа.
`portrait_image`, `front_image`, `front_video`, `back_image`, `back_video`, `full_front_image`, `full_back_image`	string (signed URL)	Захваченные медиафайлы. URL являются подписанными и ограничены по времени — скачивайте их своевременно и никогда не сохраняйте URL.
`front_image_camera_front`, `back_image_camera_front`	string (signed URL) \| null	Кадры, снятые фронтальной камерой пользователя во время захвата документа. Используются для проверки лица между камерами и сопоставляются с вашим списком блокировки лиц; каждый из них также можно добавить в список блокировки лиц.
`front_image_camera_front_face_match_score`, `back_image_camera_front_face_match_score`	float (0–100) \| null	Оценка сходства между кадром с фронтальной камеры и портретом на документе.
`document_selfie_face_matches`	array \| null	Предыдущие сессии или записи в списке блокировки лиц, лица из которых совпали с селфи, сделанным во время захвата документа (Поиск по лицу Silent Capture). Формат записей такой же, как в `liveness_checks[].matches`; `match_image_url` представляет собой предварительно подписанный URL с ограниченным сроком действия. `null` для более старых сессий или если поиск не выполнялся, `[]`, если поиск выполнялся и ничего не нашёл.
`front_image_quality_score`, `back_image_quality_score`	object \| null	Оценка качества для каждой стороны (см. Оценки качества изображений).
`document_liveness`	object \| null	Оценки живости документа по типам мошенничества с порогами, с которыми их сравнивали (см. Оценки живости документа). Только в V3.
`date_of_birth`, `expiration_date`, `date_of_issue`	string (YYYY-MM-DD)	Даты документа.
`age`	number	Возраст владельца в годах, рассчитанный на основе `date_of_birth`.
`issuing_state`	string (ISO 3166-1 alpha-3)	Код страны выдачи.
`issuing_state_name`	string	Локализованное название страны.
`first_name`, `last_name`, `full_name`	string	Имя владельца в системе письма, выбранной параметром `preferred_characters` (см. ниже).
`gender`	`"M" \| "F" \| "U"`	Пол, если он указан в документе (`U` = неизвестен).
`address`, `formatted_address`	string	Исходная и геокодированная/отформатированная строки адреса.
`place_of_birth`	string	Место рождения, распознанное через OCR.
`marital_status`	`"SINGLE" \| "MARRIED" \| "DIVORCED" \| "WIDOWED" \| "UNKNOWN"`	Семейное положение, если указано в документе.
`nationality`	string (ISO 3166-1 alpha-3)	Гражданство владельца, если оно отличается от страны выдачи.
`extra_fields`	object	Дополнительные данные, специфичные для документа (категории водительских прав, группа крови, имена в альтернативных системах письма, `tax_number`, …).
`mrz`	object \| null	Разобранные поля MRZ типа «ключ/значение».
`parsed_address`	object \| null	Структурированный геокодированный адрес (`street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location`, `raw_results`, `is_best_match`).
`extra_files[]`	array of signed URLs	Дополнительные изображения, прикреплённые к этому документу.
`matches[]`	array	Межсессионные совпадения документов (см. Межсессионные совпадения).
`warnings[]`	array	Предупреждения уровня модуля — см. Предупреждения верификации личности.

issuing_state всегда указывает на уровень страны, а не субнациональный регион. Для любого типа документа, включая водительские удостоверения, выданные штатом или провинцией (Австралия, США, Канада), issuing_state и issuing_state_name содержат страну (например, AUS / Australia), а не штат. Субнациональное значение, если оно присутствует в документе, доступно отдельно в parsed_address.region (при отсутствии этого значения для некоторых типов документов используется extra_fields.state). В обзоре сессии в Business Console это отображается как строка Регион под полем Государство выдачи, если данные присутствуют.

Водительские удостоверения с двумя номерами (Австралия). На австралийских правах напечатаны как номер удостоверения, который идентифицирует право на вождение и остаётся неизменным при замене карты, так и номер карты, который идентифицирует физическую карту и меняется при каждом перевыпуске. Для таких удостоверений Didit всегда сопоставляет номера одинаковым образом:

personal_number — номер удостоверения
document_number — номер карты

Это правило действует для каждого австралийского штата и территории (NSW, VIC, QLD, WA, SA, TAS, ACT, NT). В некоторых вариантах номер карты напечатан только на обратной стороне, поэтому он считывается только при захвате обратной стороны удостоверения. Если номер карты считать не удаётся, номер удостоверения передаётся одновременно в document_number и personal_number, поэтому document_number всегда содержит идентификатор после завершения верификации. personal_number в любом случае остаётся номером удостоверения. Для других типов документов document_number остаётся основным номером, распознанным через OCR, и сам по себе может являться идентификатором владельца.

Аргентинский CUIL передаётся в extra_fields.tax_number, и никогда в personal_number. В аргентинских документах CUIL — 11-значный идентификатор, по которому осуществляют поиск AFIP, ANSES и бюро кредитных историй, — напечатан в разных местах в зависимости от документа, а на DNI рядом с ним напечатан второй 11-значный номер:

в водительском удостоверении CUIL передаётся в personal_number;
в DNI поле personal_number содержит número de trámite, который идентифицирует заявление на выдачу карты и не является идентификатором владельца. CUIL на DNI считывается из отдельного напечатанного поля.

Поэтому personal_number не является надёжным источником CUIL для Аргентины: в случае DNI это 11-значный номер, по которому ни один реестр без предупреждения не вернёт результатов. Используйте вместо этого extra_fields.tax_number. Didit возвращает его только тогда, когда значение проходит валидацию как настоящий CUIL (префикс физического лица плюс контрольная цифра по модулю 11) в виде канонических цифр без разделителей (27111111117), независимо от того, какой аргентинский документ предоставил владелец. Если CUIL с карты не удалось считать, ключ отсутствует, а не заполняется числом, не являющимся CUIL — чтобы охватить таких пользователей, запросите водительское удостоверение в качестве второго документа либо соберите CUIL через ответ в анкете или metadata сессии.

Оценки качества изображения

Поля front_image_quality_score и back_image_quality_score возвращают:

Поле	Тип	Что измеряет
`focus_score`	number 0–100	Чёткость — локальная дисперсия лапласиана для 10% наиболее резких областей, устойчивая к однородному фону. Вес 45%.
`brightness_score`	number 0–100	Штрафует слишком тёмные или переэкспонированные изображения. Вес 30%.
`brightness_issue`	`"ok" \| "too_dark" \| "too_bright"`	Характер проблемы с яркостью, если `brightness_score` низкий.
`resolution_score`	number 0–100	На основе общего количества пикселей снимка. Вес 25%.
`is_document_fully_visible`	boolean \| null	`true`, если видны все четыре угла документа, `false`, если хотя бы один угол обрезан, `null`, если определение углов было недоступно.
`overall_score`	number 0–100	Взвешенная итоговая оценка (фокус 45%, яркость 30%, разрешение 25%).

Используйте overall_score для быстрой проверки пригодности — оценки выше 70, как правило, указывают на снимок достаточного качества для надёжной верификации.

Оценки проверки живости документа

В поле document_liveness передаются результаты проверки живости документа, независимо от того, было ли сгенерировано предупреждение. Предупреждение возникает только тогда, когда оценка опускается ниже одного из порогов сценария, поэтому до появления этого поля одобренный документ вообще не содержал свидетельств проверки живости - данное поле позволяет провести аудит успешно пройденной сессии. Значение равно null, если проверка не выполнялась (например, при методе без использования документов или при сбое модели, зафиксированном в журналах сессии). Оно содержит по одному объекту для каждого типа мошенничества - portrait_replace, printed_copy и screen_replay - каждый со следующими полями:

Поле	Тип	Значение
`score`	number 0–100 \| null	Вероятность того, что документ подлинный в отношении данного типа мошенничества (чем выше, тем вероятнее подлинность). Это наименьшее значение из двух сторон, которое и использовалось при принятии решения. `null`, если ни одна из сторон не дала пригодной для использования оценки - например, оценка портрета не учитывается для стороны, где портрет не был обнаружен.
`front`, `back`	number 0–100 \| null	Оценка для каждой снятой стороны. `null` для стороны, которая не была сфотографирована или оценка которой не учитывалась.
`decline_threshold`, `review_threshold`	number \| null	Пороги, сохранённые в момент, когда узел Верификации личности оценивал этот документ. Последующие изменения сценария их не меняют. `null`, если исторические данные оценки недоступны.
`bucket`	`"approve" \| "review" \| "decline" \| null`	В какую категорию попадает `score` по отношению к этим порогам: ниже `decline_threshold` → `decline`, ниже `review_threshold` → `review`, иначе `approve`. `null`, если пригодная оценка отсутствует, проверка не применялась или исторические данные оценки недоступны. Категория описывает проверку конкретного типа мошенничества, а не общий статус сессии.

"document_liveness": {
  "portrait_replace": {
    "score": 96.46,
    "front": 96.46,
    "back": 98.2,
    "decline_threshold": 35,
    "review_threshold": 70,
    "bucket": "approve"
  },
  "printed_copy": {
    "score": 91.2,
    "front": 91.2,
    "back": 93.7,
    "decline_threshold": 35,
    "review_threshold": 77,
    "bucket": "approve"
  },
  "screen_replay": {
    "score": 99.9,
    "front": 99.9,
    "back": 99.5,
    "decline_threshold": 30,
    "review_threshold": 70,
    "bucket": "approve"
  }
}

Для более старых документов без сохранённых данных оценки записанные баллы остаются видимыми, однако оба порога и bucket равны null. Текущие настройки сценария никогда не используются для реконструкции исторического результата. То же относится и к снимку, оценка документа по которому ещё не завершена. В Business Console те же три строки отображаются в блоке Проверка живости документа раздела «Верификация личности» сессии.

Совпадения между сессиями

В matches[] перечислено до 5 других документов в вашем приложении, совпадающих с данным — одинаковая дата рождения, одинаковая страна выдачи и очень близкое полное имя. Для документов из списка блокировки дополнительно требуется точное совпадение номера документа. Сессии, принадлежащие тому же пользователю (одинаковый vendor_data), исключаются. Каждая запись содержит session_id, session_number, vendor_data, verification_date, user_details (name, document_type, document_number), status, is_blocklisted (true, если документ был добавлен в ваш список блокировки), api_service и подписанный front_image_url.

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

Статус	Значение	Влияние на дальнейший процесс
`Approved`	Документ распознан, обязательные поля извлечены, все проверки пройдены в рамках настроенных порогов.	Считается успешной верификацией личности.
`In Review`	Сработало одно или несколько предупреждений, и сценарий направляет их на проверку.	Сессия также переходит в статус `In Review`, пока проверяющий не выполнит действие.
`Declined`	Сработало условие автоматического отклонения (неподдерживаемый документ, документ с истекшим сроком действия, отсутствует фотография, совпадение со списком блокировки, непрохождение адаптивной проверки возраста) или сработало предупреждение, настроенное на отклонение.	Сессия отклоняется, если другая одобренная ветвь не удовлетворяет условиям сценария.
`Expired`	Срок действия документа истёк после одобрения. Устанавливается постоянным мониторингом документов Didit, который включён по умолчанию (за исключением стран и типов документов, для которых параметр Expiration mode установлен в Allow expired), вместе с предупреждением `DOCUMENT_EXPIRED`.	Одобренная сессия переходит в статус `Kyc Expired`.
`Not Finished`	Пользователь прервал этап съёмки.	Ветвь верификации личности не сформировала результат.

Документы с несколькими системами письма (латиница / нелатиница)

Некоторые документы — кыргызские, казахские, российские, японские, корейские, китайские, арабские, тайские и другие — содержат имя, адрес или место рождения владельца как в латинской транслитерации, так и в местной системе письма. Вы можете выбрать, какая система письма используется для полей верхнего уровня, с помощью настройки сценария (или автономного API) preferred_characters:

Значение	Заполняет поля верхнего уровня	Противоположная система письма помещается в
`latin` (по умолчанию)	Латинская транслитерация, указанная в документе	`extra_fields.*_non_latin`
`non_latin`	Значения в местной системе письма, указанные в документе	`extra_fields.*_latin`

Значения в альтернативной системе письма находятся внутри extra_fields под ключами с соответствующими суффиксами: first_name_non_latin, last_name_non_latin, middle_name_non_latin, full_name_non_latin, address_non_latin, place_of_birth_non_latin (или соответствующие варианты _latin).

Когда появляются поля с альтернативной системой письма

Только когда обе системы письма действительно присутствуют в документе. Если OCR-поле с номинальной меткой «Surname-Kyrgyz (Cyrillic)» извлекается как текст на латинице (омоглифы или латинская транслитерация), оно не считается нелатинской альтернативой, и этот ключ опускается.
full_name_non_latin (и full_name_latin) всегда воссоздаются из отдельных компонентов имени, отчества и фамилии, когда доступны оба варианта — исходное поле «Full Name» из OCR игнорируется для обеспечения согласованности.
Если задан параметр preferred_characters=latin, но документ содержит только нелатинский текст (из-за чего поля верхнего уровня оказываются не на латинице), Didit выполняет транслитерацию и предоставляет поля first_name_latin, last_name_latin, middle_name_latin, full_name_latin, place_of_birth_latin и address_latin в качестве резервного варианта на латинице.

{
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "extra_fields": {
    "first_name_non_latin": "Айна"
  }
}

Поле last_name_non_latin отсутствует, так как в этом образце поле документа «Surname (Cyrillic)» вернуло латинские символы — подлинная нелатинская фамилия для извлечения отсутствовала.

Примеры

Approved — испанское удостоверение личности без замечаний (все поля)

{
  "id_verifications": [
    {
      "status": "Approved",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "personal_number": "SAMPLE-PER-12345",
      "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
      "front_image": "https://<media-host>/.../front.jpg?signature=...",
      "front_video": "https://<media-host>/.../front.mp4?signature=...",
      "back_image": "https://<media-host>/.../back.jpg?signature=...",
      "back_video": "https://<media-host>/.../back.mp4?signature=...",
      "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
      "full_back_image": "https://<media-host>/.../full_back.jpg?signature=...",
      "front_image_camera_front": null,
      "back_image_camera_front": null,
      "front_image_camera_front_face_match_score": null,
      "back_image_camera_front_face_match_score": null,
      "front_image_quality_score": {
        "focus_score": 85.3,
        "brightness_score": 92.1,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 84.6
      },
      "back_image_quality_score": {
        "focus_score": 79.1,
        "brightness_score": 90.5,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 81.5
      },
      "date_of_birth": "1990-01-01",
      "age": 35,
      "expiration_date": "2031-06-02",
      "date_of_issue": "2021-06-02",
      "issuing_state": "ESP",
      "issuing_state_name": "Spain",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "gender": "M",
      "address": "Avda de Madrid 34",
      "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
      "place_of_birth": "Madrid",
      "marital_status": "SINGLE",
      "nationality": "ESP",
      "extra_fields": {},
      "mrz": {
        "document_number": "SAMPLE-DOC-12345",
        "surname": "DOE",
        "name": "JOHN",
        "birth_date": "900101",
        "expiry_date": "310602"
      },
      "parsed_address": {
        "street_1": "Avda de Madrid 34",
        "street_2": null,
        "city": "Madrid",
        "region": "Madrid",
        "country": "ES",
        "postal_code": "28822",
        "address_type": "Avda",
        "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
        "document_location": { "latitude": 40.4168, "longitude": -3.7038 },
        "raw_results": {
          "geometry": {
            "location": { "lat": 40.4168, "lng": -3.7038 },
            "location_type": "ROOFTOP"
          }
        },
        "is_best_match": true
      },
      "extra_files": [],
      "warnings": [],
      "node_id": "id_primary",
      "matches": []
    }
  ]
}

In Review — QR-код не обнаружен на документе, где он должен быть

Сокращено — реальный ответ всегда содержит полный набор полей, показанный выше.

{
  "id_verifications": [
    {
      "status": "In Review",
      "node_id": "id_primary",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "warnings": [
        {
          "feature": "ID_VERIFICATION",
          "risk": "QR_NOT_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "QR not detected",
          "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
          "node_id": "id_primary"
        }
      ]
    }
  ]
}

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

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

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

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

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

Верификация

Мониторинг

Платформа

Отчёт о верификации личности: поля и оценки качества

Обзор

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

Схема

Поля верхнего уровня

Оценки качества изображения

Оценки проверки живости документа

Совпадения между сессиями

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

Документы с несколькими системами письма (латиница / нелатиница)

Когда появляются поля с альтернативной системой письма

Примеры

Approved — испанское удостоверение личности без замечаний (все поля)

In Review — QR-код не обнаружен на документе, где он должен быть

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

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

​Обзор

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

​Схема

​Поля верхнего уровня

​Оценки качества изображения

​Оценки проверки живости документа

​Совпадения между сессиями

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

​Документы с несколькими системами письма (латиница / нелатиница)

​Когда появляются поля с альтернативной системой письма

​Примеры

​Approved — испанское удостоверение личности без замечаний (все поля)

​In Review — QR-код не обнаружен на документе, где он должен быть

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

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

Обзор

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

Схема

Поля верхнего уровня

Оценки качества изображения

Оценки проверки живости документа

Совпадения между сессиями

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

Документы с несколькими системами письма (латиница / нелатиница)

Когда появляются поля с альтернативной системой письма

Примеры

Approved — испанское удостоверение личности без замечаний (все поля)

In Review — QR-код не обнаружен на документе, где он должен быть

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

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