Вид на жительство

Вид на жительство подтверждает право лица, не являющегося гражданином государства, на долгосрочное проживание на его территории.

Пример изображения документа:

Документы для обработки должны быть закодированы в формат base64.

Отправка документа

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

Заголовки:

Content-Type: application/json

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

{
  "project_id": "U_RATE_2",
  "images": ["<строка base64>"],
  "process_info": [
    {
      "key": "VNG1",
      "type": "VNG",
      "options": {
        "stages": ["verification"]
      }
    }
  ],
  "token": "<token>",
  "machine_uid": "<machine_uid>"
}

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

{
  "document_id": "s-12345"
}

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

Ключ	Описание
`project_id`	Название проекта (`U_RATE_2`)
`token`	Токен доступа (получается в разделе «Начало работы»)
`machine_uid`	Идентификатор устройства (получается в разделе «Начало работы»)
`images`	Список строк в формате base64 (файлов). Для ВНЖ — один элемент массива (изображение документа)
`process_info`	Настройки обработки документа

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

Ключ	Описание
`key`	Свободный ключ для разделения документов при загрузке и получении результатов. Если не указан, вместо него используется ключ `type`
`type`	Тип документа (`VNG` для вида на жительство)
`options`	Опции обработки документа

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

Ключ	Описание
`stages`	Этапы обработки документа. Для ВНЖ: `["verification"]`. Доступны: `verification`, `biometry_match`, `biometry_liveness`
`relation`	Связь с иным документом в одном запросе (доступно: `biometry_match`). Не указывается, если биометрия не требуется

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

Пример запроса (Python) для отправки вида на жительство

import requests
import base64

# Кодируем изображение документа в base64
with open("<путь до файла вида на жительство>", "rb") as image_file:
    b64_vng = base64.b64encode(image_file.read()).decode()

# Отправляем запрос на API
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,
        "images": [b64_vng],
        "process_info": [
            {
                "key": "VNG1",
                "type": "VNG",
                "options": {
                    "stages": ["verification"]  # только верификация данных
                }
            }
        ]
    }
)
print(r.json())  # выводим ответ сервера

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

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

Пример запроса для получения результатов (Python):

import requests

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

Пример ответа по обработанному документу (вид на жительство)

{
  "document_id": "s-39182",
  "documents": [
    {
      "key": "VNG1",
      "type": "VNG",
      "data": {
        "Series": "77 01",
        "Number": "123456",
        "IssueId": "МВД РФ №77001",
        "Gender": "F",
        "LastName": "Иванова",
        "FirstName": "Мария",
        "MiddleName": "Сергеевна",
        "BirthDate": "15.04.1985",
        "BirthPlace": "г. Минск, Республика Беларусь",
        "Citizenship": "Республика Беларусь",
        "SolutionDate": "20.05.2023",
        "SolutionNumber": "ВНЖ-2023-00123",
        "IssuedBy": "ГУ МВД России по г. Москве",
        "IssueDate": "25.05.2023",
        "ExpiryDate": "25.05.2028",
        "Address": "г. Москва, ул. Тверская, д. 15, кв. 42",
        "RegIssueDate": "26.05.2023",
        "RegExpiryDate": "26.05.2028"
      },
      "metadata": {
        "confidences": {
          "Series": 0.9990,
          "Number": 0.9995,
          "IssueId": 0.9980,
          "Gender": 0.9997,
          "LastName": 0.9996,
          "FirstName": 0.9994,
          "MiddleName": 0.9992,
          "BirthDate": 0.9985,
          "BirthPlace": 0.9970,
          "Citizenship": 0.9960,
          "SolutionDate": 0.9950,
          "SolutionNumber": 0.9940,
          "IssuedBy": 0.9930,
          "IssueDate": 0.9920,
          "ExpiryDate": 0.9910,
          "Address": 0.9890,
          "RegIssueDate": 0.9870,
          "RegExpiryDate": 0.9850
        },
        "verifications": {
          "status": 0,
          "status_text": "ок"
        }
      },
      "broken": false,
      "broken_reasons": [],
      "broken_reasons_ru": []
    }
  ]
}

Описание ключей в ответе

Ключ	Тип	Описание
`document_id`	string	Номер документа в формате `s-<номер документа>`
`documents`	list	Список данных по каждому документу
`documents[].key`	string	Ключ, заданный при отправке документа для отслеживания (`VNG1`)
`documents[].type`	string	Тип документа (`VNG`)
`documents[].data`	dictionary	Обработанные данные по каждому полю, содержит ключи полей и их определённые значения
`Series`	string	Серия документа
`Number`	string	Номер документа
`IssueId`	string	Идентификатор выдачи (например, код подразделения МВД)
`Gender`	string	Пол (`M` — мужской, `F` — женский)
`LastName`	string	Фамилия владельца ВНЖ
`FirstName`	string	Имя владельца ВНЖ
`MiddleName`	string	Отчество владельца ВНЖ
`BirthDate`	string	Дата рождения (в формате ДД.ММ.ГГГГ)
`BirthPlace`	string	Место рождения
`Citizenship`	string	Гражданство владельца ВНЖ
`SolutionDate`	string	Дата принятия решения о выдаче ВНЖ (в формате ДД.ММ.ГГГГ)
`SolutionNumber`	string	Номеррешения о выдаче ВНЖ
`IssuedBy`	string	Наименование органа, выдавшего ВНЖ (например, «ГУ МВД России по г. Москве»)
`IssueDate`	string	Дата выдачи ВНЖ (в формате ДД.ММ.ГГГГ)
`ExpiryDate`	string	Дата окончания действия ВНЖ (в формате ДД.ММ.ГГГГ). Может быть `null`, если срок не ограничен
`Address`	string	Адрес регистрации/проживания владельца ВНЖ
`RegIssueDate`	string	Дата постановки на регистрационный учёт (в формате ДД.ММ.ГГГГ). Может быть `null`
`RegExpiryDate`	string	Дата окончания срока регистрации (в формате ДД.ММ.ГГГГ). Может быть `null`
`metadata`	dictionary	Содержит ключи метаданных
`confidences`	dictionary (`{key: float}`)	Метаданные с точностью обработки по каждому полю. Содержит ключи полей и значения уровня уверенности. Значения от `0.0000` до `0.9999`, где чем значение больше, тем уверенность в результате выше. Максимальная уверенность — `0.9999`
`verifications`	dictionary (`{key: boolean, key: integer}`)	Метаданные совершённых проверок. Может содержать: — `status` (integer): 0 — успешно, 1 — ошибка; — `status_text` (string): текстовое описание статуса
`broken`	boolean	Является ли документ бракованным (`true`/`false`)
`broken_reasons`	list	Список причин брака на английском языке
`broken_reasons_ru`	list	Список причин брака на русском языке