Перейти к содержанию

Document Recognition v2

Общие правила чтения полей, причины отказа и форматы файлов full/light описаны в обзоре.

Родитель: document_recognition_v2_result. Отдельный формат с текстом, изображениями и структурированными проверками.

Поля document_recognition_v2_result.

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Поле Тип в JSON Назначение и условия
status string, enum Обязателен: NOT_PARSED — ещё не распознан; PENDING — обработка; SUCCESS — успешно; FAILED — ошибка; NOT_FOUND — не найден; COPIED — повторно использован результат.
source_session string, UUID Исходная сессия при копировании результата; иначе отсутствует.
optical_checks object Сводные проверки документа, если сформированы; таблица ниже.
quality_checks object[] Проверки качества по страницам. Массив возвращается и при отсутствии элементов ([]).
authenticity_checks object[] Проверки подлинности. Массив возвращается и при отсутствии элементов ([]).
document_types object[] Распознанные типы / варианты документа. Может быть [].
visual_text_json object Динамический словарь значений из визуальной зоны документа; при наличии данных.
mrz_text_json object Динамический словарь значений из машиночитаемой зоны; при наличии данных.
images object[] Сохранённые исходные и извлечённые изображения; может быть [].
result boolean Сохранённый результат технологии: true — принята, false — отрицательный результат. До расчёта может отсутствовать; учитывайте статус и особенности ниже.
failure_reason object Причина отказа, если записана; структура.

В visual_text_json и mrz_text_json для записи с ключом confidence возвращается только её value; остальные значения сохраняются как есть. Поэтому нельзя ожидать обязательную обёртку {value, confidence} для каждого поля. Имена, типы значений и полнота словарей зависят от распознавателя и документа; вложенный null возможен. Отдельное объединённое поле confident_text_json этот API не возвращает.

Родитель: document_recognition_v2_result.optical_checks.

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Поле Тип в JSON Назначение и условия
overall_status boolean Общий результат оптических проверок.
doc_type boolean Проверка типа документа.
expiry boolean Проверка срока действия.
image_qa boolean Сводная проверка качества изображения.
mrz boolean Проверка машиночитаемой зоны.
pages_count integer Количество страниц в массиве проверок.
security boolean Проверка защитных признаков.
text boolean Проверка текстовых данных.

Родитель: document_recognition_v2_result.quality_checks[].

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Поле Тип в JSON Назначение и условия
image_glares boolean Пройдена проверка бликов.
image_focus boolean Пройдена проверка фокусировки.
image_resolution boolean Пройдена проверка разрешения изображения.
image_colorness boolean Пройдена проверка цветности.
perspective boolean Пройдена проверка перспективных искажений.
bounds boolean Пройдена проверка границ документа.
portrait boolean Пройдена проверка портрета.
brightness boolean Пройдена проверка яркости.
page integer Индекс страницы в массиве проверок, начиная с 0.

Родитель: document_recognition_v2_result.authenticity_checks[].

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Поле Тип в JSON Назначение и условия
liveness_electronic_device boolean Пройдена проверка предъявления документа с экрана электронного устройства.
liveness_black_and_white_copy boolean Пройдена проверка чёрно-белой копии.
image_patterns boolean Пройдена проверка графических шаблонов.
barcode_format boolean Пройдена проверка формата штрихкода.
portrait_comparison boolean Пройдена проверка сопоставления портретов.
photo_embedding boolean Пройдена проверка вклейки / встраивания фотографии.
page integer Идентификатор страницы проверки от обработчика; универсальный диапазон не закреплён.

Для булевых проверок true означает положительный результат проверки, false — отрицательный; отсутствие поля означает отсутствие значения, а не успешную проверку.

Родитель: document_recognition_v2_result.document_types[].

Поля с пометкой «Обязателен» присутствуют всегда внутри этого объекта. Остальные поля — при наличии значения; null исключается из ответа.

Поле Тип в JSON Назначение и условия
document_id integer Идентификатор документа в классификаторе распознавателя. Публичное имя — document_id.
name string Название распознанного документа / образца.
type string Название типа документа.
type_id integer Числовой код типа от распознавателя; локального enum нет.
issue_year string Год или период выпуска образца; именно строка, не integer.
issuing_country string Наименование страны выдачи.
has_rfid boolean Признак наличия RFID-чипа у типа документа.
has_mrz boolean Признак наличия машиночитаемой зоны у типа документа.
format integer Код формата от распознавателя; расшифровка чисел локально не закреплена.
country_code string Код страны, до 3 символов.
prediction number Оценка уверенности определения типа; шкала и диапазон не закреплены.
required_light_schemes integer Код требуемых схем освещения от распознавателя; расшифровка числовых значений не закреплена.
authenticity_light_schemes integer Код схем освещения для проверки подлинности; расшифровка числовых значений не закреплена.
page integer Номер / индекс страницы от распознавателя, неотрицательное число.

Родитель: document_recognition_v2_result.images[].

Условия указаны в строках. Порядок элементов не заменяет значение page.

Поле Тип в JSON Назначение и условия
type string, enum Обязателен. Тип изображения, перечень ниже.
content string При наличии файла: Base64 в полном ответе, URL в light.
page integer При наличии номера страницы. Для исходных файлов и массивов изображений нумерация с 0; одиночный document_front получает 0, у остальных одиночных изображений номер может отсутствовать.

Значения document_recognition_v2_result.images[].type.

Перечень допустимых типов; наличие каждого из них зависит от документа и распознавания.

Поле Тип в JSON Назначение и условия
unknown string неизвестный тип
source string исходное изображение
portrait string портрет
fingerprint string отпечаток пальца
eye string изображение глаза
signature string подпись
bar_code string штрихкод
proof_of_citizenship string подтверждение гражданства
document_front string лицевая сторона
document_back string оборотная сторона
document_rear string изображение типа rear от распознавателя; отличие от back локально не определено
color_dynamic string цветодинамический элемент
ghost_portrait string дополнительный защитный портрет
stamp string печать / штамп
contact_chip string контактный чип
finger_left_thumb string отпечаток большого пальца левой руки
finger_left_index string отпечаток указательного пальца левой руки
finger_left_middle string отпечаток среднего пальца левой руки
finger_left_ring string отпечаток безымянного пальца левой руки
finger_left_little string отпечаток мизинца левой руки
finger_right_thumb string отпечаток большого пальца правой руки
finger_right_index string отпечаток указательного пальца правой руки
finger_right_middle string отпечаток среднего пальца правой руки
finger_right_ring string отпечаток безымянного пальца правой руки
finger_right_little string отпечаток мизинца правой руки
finger_right_four string четыре пальца правой руки
finger_left_four string четыре пальца левой руки
finger_two_thumbs string два больших пальца

JSON-примеры

Фрагменты корневого объекта ответа, а не целостные ответы. Все значения и ссылки условные. Формат файлов соответствует пояснениям на этой странице.

{
  "document_recognition_v2_result": {
    "status": "COPIED",
    "result": true,
    "source_session": "44444444-4444-4444-8444-444444444444",
    "optical_checks": {
      "doc_type": true,
      "expiry": true
    },
    "quality_checks": [
      {
        "image_focus": true,
        "page": 0
      }
    ],
    "authenticity_checks": [],
    "document_types": [
      {
        "name": "Условный документ",
        "document_id": 100,
        "page": 0
      }
    ],
    "visual_text_json": {
      "surname": "ПРИМЕРОВ",
      "given_names": "ПРИМЕР",
      "fathers_name": null
    },
    "images": [
      {
        "type": "document_front",
        "page": 0,
        "content": "https://files.example.invalid/document/front.png"
      }
    ]
  }
}