Зарегистрироваться+7 495 739-92-37kyc@beorg.ru
Подождите, идет загрузка данных

Привет!

Вы на странице технической информации по API-сервису компании «Биорг».

Мы подготовили этот документ для разработчиков, чтобы в несколько простых шагов
подключить сервис распознавания документов Биорг к сайту, ПО,
мобильному приложению, CRM, продуктам «1С» и др.

При регистрации на Ваш счет будет начислено 100 бонусных рублей для тестирования нашего API

По умолчанию API-сервис настроен на распознавание Паспортов РФ.
Если Вам необходимо подключить другие документы – свяжитесь с нами.


Техническое описание сервиса API

Оглавление:




Описание интеграции и API:

Начало работы

Перед началом работы с API нужно:

  1. Зарегистрироваться в системе
  2. Получить ключи доступа (token и machine_uid) и идентификатор сценария обработки документа (project_id)

Для получения ключей доступа:

  1. Перейдите в раздел Проекты и нажмите на кнопку :

  2. В открывшемся окне вам доступны token, machine_uid и project_id. Также доступны примеры по загрузке документов на обработку и получения результатов обработки:

Описание работы

Для организации взаимодействия с системой и настройки обработки документов нужно реализовать два метода API.

  1. Запрос на загрузку документа в систему. По пути /api/bescan/add_document отправляется файл, файл в формате строки base64 для распознавания и параметры token, machine_uid, project_id. При успешной отправке в теле ответа будет номер созданного документа в ключе document_id, его нужно использовать для получения результата.
    • 200 – Успешная загрузка, возвращается ключ document_id номера документа; 2.Запрос на получение результата обработки. В случае успешной загрузки, по ключу document_id с помощью эндпоинта /api/bescan/result можно запросить результат обработки. В качестве ответа возвращается:
    • 200 - Успешный результат обработки, возвращается результат обработки; При возвращении результата обработки с кодом «200», возвращаются в блоке «data» наборы полей в форме {ключ: значение} и в блоке metadata-confidences метаданные об оценках уровня уверенности для каждого поля распознанного поля; При возвращении ответа с кодом НЕ 200, см. раздел Коды ошибок;


Схема работы с API



С обобщенным техническим описанием API и кодов ошибок можно ознакомиться по ссылке

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




Требования к загружаемым документам

Рекомендуемые:

  • Изображение документа должно быть полным или необрезанным, края документа не должны визуально совпадать с краями изображения;
  • Изображение должно содержать не более одного документа;
  • Документ не должен иметь геометрических и цветовых искажений, затрудняющих его прочтение;
  • Угол наклона проекции изображения документа не должно превышать 5 градусов, поворот документа в кадре не должен превышать 5 градусов (ориентируясь на строки текста и поля документа);
  • Изображение документа должно быть четким, контрастным и сфокусированным, с хорошей детализацией значимых для документа элементов – строки, символы, знаки препинания, границы и т.п.;
  • На изображении документа не должны присутствовать дефекты в виде дымки, бликов, теней, засветов, ореолов, а также изображений объектов, не относящихся к сути документа, которые препятствуют выполнению процедуры дешифровки (распознавания);
  • Фон изображения должен быть контрастным по отношению к документу, монотонным или желательно без явных водяных знаков;
  • Коэффициент качества при сжатии с потерей качества должно быть не менее 75%;
  • Изображение не должно иметь явных признаков пережатия (артефактов сжатия);
  • Качество скана не ниже 200 dpi и не более 500 dpi, рекомендуемое – 300 dpi;
  • Разрешение фотоизображения документа не ниже 1920x1080 пикселей, желательным ориентиром – на изображении символы документа должны быть не менее 15х15 пикселей;
  • Для минимизации дисторсии на фотоизображениях, фотографируемый объект должен располагаться по центру снимка.

Обязательные:

  • Поддерживаемые форматы входных изображений: JPEG, TIFF, PNG, AVIF, WEBP, PDF, рекомендуемый JPEG/TIFF.
  • Интенсивность запросов – не более 1 запроса в секунду;
  • В одном запросе – не более 1 файла;
  • Количество страниц – не более 20;
  • Размер файла – не менее 50 Кб и не более 5 Мб;
  • Допустимая ширина/высота изображения – не менее 1000 и не более 5000 пикселей.




Описание полей

Описание полей при успешной загрузке документов

Ключ Тип Описание
document_id string номер документа для дальнейшего отслеживания


Описание полей при получении результатов

Ключ Тип Описание
document_id integer номер документа
data dictionary обработанные данные по каждому полю,
содержит ключи полей и их определенные значения
IssuedBy string кем выдан паспорт
IssueDate string дата выдачи паспорта
IssueId string код подразделения
Series string серия паспорта
Number string номер паспорта
Gender string пол
LastName string фамилия
FirstName string имя
MiddleName string отчество
BirthDate string дата рождения
BirthPlace string место рождения
Address string адрес
HasPhoto boolean или string попала ли в кадр фотография владельца
HasOwnerSignature boolean или string попала ли в кадр подпись владельца
MRZ1 string первая строка машиночитаемой записи
MRZ2 string вторая строка машиночитаемой записи
metadata dictionary содержит ключи метаданных
confidences dictionary
{key: float}
метаданные с точностью обработки по каждому полю -
содержит ключи полей и значения уровня уверенности.
Значения от 0.0000 до 0.9999, где чем значение больше,
тем уверенность в результате выше.
Максимальная уверенность - 0.9999.
verifications dictionary
{key: boolean, key: integer}
метаданные совершенных проверок -
содержит ключи и их значения проверок,
см. Правила проверок
biometrics dictionary Результаты проверок биометрии
(доступны в тарифах Биорг.Паспорт Верификация и Биорг.KYC)
liveness dictionary
{key: integer, key: integer}
результаты проверки живости человека на селфи
Значения 0 или 1 для ключа liveness,
значения от 0 до 1 для ключа probability
match_faces dictionary
{key: integer, key: integer}
результаты проверки схожести человека на
изображении в паспорте и селфи
Значения 0 или 1 для ключа match_faces,
значения от 0 до 1 для ключа similarity




Правила проверок

Проверка паспорта

В результате обработки входящего паспорта будет доступно поле verifications,
в котором находятся следующие данные:

Название Описание Тип данных
status статус проверки integer
status_text текстовое описание статуса string
bad_fields список полей полей имеющих несоответствия list


Поле status может отражать следующие варианты кодов проверки:

Код Описание
0 ок
1 одно или несколько обязательных полей отсутствует или имеет неверный формат
2 МЧЗ не согласуется со значением полей
3 серия паспорта не согласуется с кодом подразделения
4 место выдачи не согласуется с кодом подразделения
5 паспорт выдан до 14-ти лет
6 паспорт выдан до 1 октября 1997 года
7 паспорт просрочен




Биометрия

Проверка биометрии доступна в тарифах Биорг.Паспорт Верификация и Биорг.KYC

liveness - проверка живости

Проверяет живой ли человек на изображении

Расшифровка результата проверки liveness:

Результат Описание Значения
liveness не живой/живой 0 или 1
probability вероятность живости 0...1

match_faces - проверка схожести

Проверяет совпадает ли изображение человека в паспорте и изображение человека на селфи

Расшифровка результата проверки match_faces :

Результат Описание Значения
match_faces не совпадает/совпадает 0 или 1
similarity на сколько изображения лиц схожи 0...1




Примеры запросов

Отправка документов /api/bescan/add_document


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

  • Пример документа

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

  • Python

    import requests
    import base64

    with open("<путь до файла>", "rb") as image_file: b64 = base64.b64encode(image_file.read()).decode() image_file.close()

    r = requests.post( "https://api.beorg.ru/api/bescan/add_document", headers={"Content-Type": "application/json"}, json={ "project_id": "", "token": "", "machine_uid": "", "images": [], }, ) r.json()

  • Curl

    curl -X POST https://api.beorg.ru/api/bescan/add_document -H 'Content-Type: application/json' -d  {"project_id": "", "images": [""], "token": "", "machine_uid": ""}' 
    



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

{
    "document_id": "<номер документа>"
}


Описание данных

Ключ Описание
document_id номер документа для дальнейшего отслеживания


Получение результатов /api/document/result/


Пример запроса

  • Python
import requests

requests.get("https://api.beorg.ru/api/document/result/<номер документа>?token=<токен>")

  • Curl
curl https://api.beorg.ru/api/document/result/<номер документа>?token=<токен>


Пример ответа по обработанному документу:

{
    "document_id": "12345",
    "data": {
        "IssuedBy": "IssuedBy",
        "IssueDate": "",
        "IssueId": "IssueId",
        "Series": "Series",
        "Number": "Number",
        "Gender": "Gender",
        "LastName": "LastName",
        "FirstName": "FirstName",
        "MiddleName": "MiddleName",
        "BirthDate": "",
        "BirthPlace": "BirthPlace",
        "Address": "Address",
        "HasPhoto": true,
        "HasOwnerSignature": true,
        "HasStamp": ""
    },
    "metadata": {
        "confidences": {
            "IssuedBy": "0.9999",
            "IssueDate": "0.9999",
            "IssueId": "0.9999",
            "Series": "0.9999",
            "Number": "0.9999",
            "Gender": "0.9999",
            "LastName": "0.9999",
            "FirstName": "0.9999",
            "MiddleName": "0.9999",
            "BirthDate": "0.9999",
            "BirthPlace": "0.9999",
            "Address": "0.9999",
            "MRZ1": "0.9999",
            "MRZ2": "0.9999",
            "HasPhoto": "0.9999",
            "HasOwnerSignature": "0.9999"
        }
    },
    "verifications": {
      "status": 0,
      "status_text": "ок",
      "bad_fields": []
    }
}




Коды ошибок

Отправка документов /api/bescan/add_document/

Код ошибки Описание Комментарий
400 некорректный запрос, не хватает данных проверьте корректность данных в запросе
401 ошибка авторизации в запросе не указаны или указаны некорректные token и machine_uid
402 недостаточно средств необходимо пополнить баланс
409 документ уже существует не посылайте один и тот же файл несколько раз
413 слишком большой размер файла не посылайте файлы сумма размеров, которых более 800 Мб
500 ошибка сервера ошибка на стороне сервера
503 ошибка сервера ваш запрос слишком долго обрабатывается


Получение результатов /api/document/result/

Код ошибки Описание Комментарий
400 некорректный запрос, не хватает данных проверьте корректность данных в запросе
401 ошибка авторизации в запросе не указаны или указаны некорректные token и machine_uid
404 документ не найден или в обработке получение результата возможно только после завершения обработки
500 ошибка сервера ошибка на стороне сервера


Контактная информация

Поддержка осуществляется в рабочее время, с 9.00 до 19.00 по Москве.

  • По вопросам стоимости и условий продажи лицензий: kyc@beorg.ru
  • По вопросам технической поддержки: tech.support@beorg.ru