Обработка текстовых данных

Обработка текстовых данных — режим, в котором вместо изображений документа передаются уже известные значения его полей (например, введённые пользователем в анкете). Изображение не требуется: данные проверяются на корректность и проходят выбранные этапы обработки.

Режим подходит, когда данные документа уже есть в вашей системе и их нужно проверить или обработать без повторного распознавания.

Доступные типы документов:

Тип документа	Ключ `type`
Паспорт гражданина РФ (2-3 стр.)	`PASSPORT`
Паспорт гражданина РФ (2-3 стр.) с регистрацией	`PASSPORT_REG`
Водительское удостоверение	`DLIC`
СНИЛС	`SNILS`
Паспорт иностранного гражданина	`PASSPORT_FRGN`

Отправка данных

Endpoint: POST https://api.beorg.ru/api/bescan/add_document

Заголовки:

Content-Type: application/json

Тело запроса:

{
  "project_id": "U_RATE_3",
  "process_info": [
    {
      "key": "PASSPORT1",
      "type": "PASSPORT",
      "data": {
        "LastName": "Иванов",
        "FirstName": "Иван",
        "MiddleName": "Иванович",
        "BirthDate": "01.01.1990",
        "Series": "4507",
        "Number": "123456"
      }
    }
  ],
  "token": "<token>",
  "machine_uid": "<machine_uid>"
}

Пример ответа об успешной загрузке:

{
  "document_id": "s-12345"
}

Структура передаваемых данных

Ключ	Описание
`project_id`	Название проекта (`U_RATE_3`)
`token`	Токен доступа (получается в разделе «Начало работы»)
`machine_uid`	Идентификатор устройства (получается в разделе «Начало работы»)
`process_info`	Список документов с данными. В одном запросе можно передать несколько документов, они будут объединены в комплект

Ключ images в этом режиме не передаётся.

Структура `process_info`

Ключ	Описание
`key`	Свободный ключ для разделения документов при получении результатов. В режиме обработки текстовых данных должен быть уникальным в пределах запроса
`type`	Тип документа (см. таблицу выше)
`data`	Значения полей документа: `{"<код поля>": "<значение>"}`. Обязателен и не может быть пустым. Коды полей для каждого типа приведены ниже
`options`	Опции обработки документа (необязательно), см. Этапы обработки

Для получения token, machine_uid и project_id обратитесь в подраздел «Начало работы».

Пример запроса (Python)

import requests

r = requests.post(
    "https://api.beorg.ru/api/bescan/add_document",
    headers={"Content-Type": "application/json"},
    json={
        "project_id": project_id,
        "token": token,
        "machine_uid": machine_uid,
        "process_info": [
            {
                "key": "PASSPORT1",
                "type": "PASSPORT",
                "data": {
                    "LastName": "Иванов",
                    "FirstName": "Иван",
                    "MiddleName": "Иванович",
                    "BirthDate": "01.01.1990",
                    "Series": "4507",
                    "Number": "123456",
                },
            },
            {
                "key": "SNILS1",
                "type": "SNILS",
                "data": {
                    "Number": "123-456-789 01",
                    "LastName": "Иванов",
                    "FirstName": "Иван",
                    "MiddleName": "Иванович",
                },
            },
        ],
    },
)
print(r.json())  # {"document_id": "s-12345"}

Этапы обработки

В режиме обработки текстовых данных доступны только этапы, которым не нужно изображение. Этапы указываются в options.stages:

Этап	Описание	Для документов
`transliterate_fields`	Транслитерация полей с латиницы на кириллицу	`PASSPORT_FRGN`
`external_sites_check`	Проверка по базам данных, например действительность паспорта на Госуслугах	`PASSPORT`, `PASSPORT_REG`

Этапы, работающие с изображением (verification, biometry_match, biometry_liveness и др.), в этом режиме недоступны: запрос с ними будет отклонён.

Пример с проверкой паспорта на Госуслугах:

{
  "key": "PASSPORT1",
  "type": "PASSPORT",
  "data": {
    "LastName": "Иванов",
    "FirstName": "Иван",
    "Series": "4507",
    "Number": "123456"
  },
  "options": {
    "stages": ["external_sites_check"],
    "stages_settings": {
      "external_sites_check": {
        "list": ["gosuslugi"]
      }
    }
  }
}

Получение результатов

Результаты запрашиваются так же, как при распознавании изображений.

Endpoint: GET/POST https://api.beorg.ru/api/document/result/s-12345?token=<token>

import requests

r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=<token>")
print(r.json())

Структура ответа совпадает с описанной на странице соответствующего документа (раздел «Документы»): данные полей — по ключу documents[].data, результаты проверок по базам данных — по ключу external_integrations.

Поля документов

Ниже приведены коды полей, которые можно передать в data. Даты передаются в формате ДД.ММ.ГГГГ, пол — M (мужской) или F (женский).

Набор обязательных полей зависит от настроек проекта. Если обязательное поле не передано, запрос будет отклонён с указанием этого поля.

Паспорт гражданина РФ (2-3 стр.) — `PASSPORT`

Поле	Описание
`LastName`	Фамилия
`FirstName`	Имя
`MiddleName`	Отчество
`Gender`	Пол
`BirthDate`	Дата рождения
`BirthPlace`	Место рождения
`Series`	Серия паспорта (4 цифры)
`Number`	Номер паспорта (6 цифр)
`IssueDate`	Дата выдачи
`IssueId`	Код подразделения
`IssuedBy`	Кем выдан

"data": {
  "LastName": "Иванов",
  "FirstName": "Иван",
  "MiddleName": "Иванович",
  "Gender": "M",
  "BirthDate": "01.01.1990",
  "BirthPlace": "г. Москва",
  "Series": "4507",
  "Number": "123456",
  "IssueDate": "15.03.2020",
  "IssueId": "770-001",
  "IssuedBy": "Отдел УФМС России по г. Москве"
}

Подробнее о полях: Паспорт гражданина РФ (2-3 стр.).

Паспорт гражданина РФ (2-3 стр.) с регистрацией — `PASSPORT_REG`

Отдельный тип документа: включает поля лицевого разворота паспорта (стр. 2-3) и поля страницы регистрации. Передаётся одним элементом process_info с type: "PASSPORT_REG", отдельно передавать PASSPORT не нужно.

Поле	Описание
`LastName`	Фамилия
`FirstName`	Имя
`MiddleName`	Отчество
`Gender`	Пол
`BirthDate`	Дата рождения
`BirthPlace`	Место рождения
`Series`	Серия паспорта с лицевого разворота (4 цифры)
`Number`	Номер паспорта с лицевого разворота (6 цифр)
`IssueDate`	Дата выдачи
`IssueId`	Код подразделения
`IssuedBy`	Кем выдан
`Address`	Адрес регистрации
`Series_REG`	Серия со страницы регистрации
`Number_REG`	Номер со страницы регистрации
`RegDate`	Дата регистрации

"data": {
  "LastName": "Иванов",
  "FirstName": "Иван",
  "MiddleName": "Иванович",
  "Gender": "M",
  "BirthDate": "01.01.1990",
  "BirthPlace": "г. Москва",
  "Series": "4507",
  "Number": "123456",
  "IssueDate": "15.03.2020",
  "IssueId": "770-001",
  "IssuedBy": "Отдел УФМС России по г. Москве",
  "Address": "г. Москва, ул. Ленина, д. 1, кв. 1",
  "Series_REG": "4507",
  "Number_REG": "123456",
  "RegDate": "20.03.2020"
}

Подробнее о полях: Паспорт гражданина РФ (2-3 стр.) с регистрацией.

Водительское удостоверение — `DLIC`

Поле	Описание
`LastName`	Фамилия
`FirstName`	Имя
`MiddleName`	Отчество
`BirthDate`	Дата рождения
`BirthPlace`	Место рождения
`Series`	Серия
`Number`	Номер
`IssueDate`	Дата выдачи
`EndDate`	Дата окончания действия
`IssuedBy`	Кем выдано
`PlaceOfResidence`	Место жительства
`Categories`	Категории ТС

"data": {
  "LastName": "Иванов",
  "FirstName": "Иван",
  "MiddleName": "Иванович",
  "BirthDate": "01.01.1990",
  "Series": "9900",
  "Number": "123456",
  "IssueDate": "10.06.2021",
  "EndDate": "10.06.2031",
  "Categories": "B, B1, M"
}

Подробнее о полях: Водительское удостоверение.

СНИЛС — `SNILS`

Поле	Описание
`Number`	Страховой номер (СНИЛС), формат `XXX-XXX-XXX YY`
`LastName`	Фамилия
`FirstName`	Имя
`MiddleName`	Отчество
`Gender`	Пол
`BirthDate`	Дата рождения
`BirthPlace`	Место рождения
`RegistrationDate`	Дата регистрации в системе индивидуального учёта

"data": {
  "Number": "123-456-789 01",
  "LastName": "Иванов",
  "FirstName": "Иван",
  "MiddleName": "Иванович",
  "Gender": "M",
  "BirthDate": "01.01.1990"
}

Подробнее о полях: СНИЛС.

Паспорт иностранного гражданина — `PASSPORT_FRGN`

Значения передаются латиницей.

Поле	Описание
`Code`	Код государства (например, `KAZ`, `UZB`)
`Number`	Номер паспорта
`IDNumber`	Идентификационный номер
`LastName`	Фамилия
`FirstName`	Имя
`MiddleName`	Отчество (если есть)
`Gender`	Пол
`BirthDate`	Дата рождения
`BirthPlace`	Место рождения
`Nationality`	Гражданство
`IssueDate`	Дата выдачи
`FutureDate`	Дата, до которой документ действителен
`IssuedBy`	Кем выдан

"data": {
  "Code": "KAZ",
  "Number": "N12345678",
  "LastName": "IVANOV",
  "FirstName": "IVAN",
  "Gender": "M",
  "BirthDate": "01.01.1990",
  "Nationality": "KAZAKHSTAN",
  "IssueDate": "15.03.2020",
  "FutureDate": "15.03.2030"
}

Чтобы получить ФИО кириллицей, добавьте этап transliterate_fields:

"options": {
  "stages": ["transliterate_fields"]
}

Подробнее о полях: Паспорт иностранного гражданина.

Ограничения и ошибки

В запросе передаются только данные: у каждого элемента process_info должен быть непустой data.
Ключ key должен быть уникальным в пределах запроса.
Передавать можно только поля, существующие для типа документа. Значения проверяются по формату поля (маске).

При ошибке возвращается ответ со статусом 400 и описанием причины:

{
  "error": "Bad Request",
  "message": "Bad format for key `process_info`. <причина>"
}

Причина	Что исправить
`process_info in bad format (if you trying to upload with ready data, all elements must contain non empty data)`	У одного из документов не передан или пуст `data`
`if you processing by data, process info key must be unique (<key>)`	Повторяется ключ `key`
`unknown stage name for selected process_info <stage>`	Указан этап, недоступный без изображения
`error data processing check: data processing is not available for type <type>`	Режим не включён для этого типа документа — обратитесь на `kyc@beorg.ru`
`error fields check: field <поле> is required. Please, include field in your request process_info data`	Не передано обязательное поле
`error fields check: field <поле> is not valid for <type>`	Поля с таким кодом нет у этого типа документа
`error fields check: value <значение> for field <поле> is not valid`	Значение не соответствует формату поля