Привет!
Вы на странице технической информации по API-сервису компании «Биорг».
Мы подготовили этот документ для разработчиков, чтобы в несколько простых шагов
подключить сервис распознавания документов Биорг к сайту, ПО,
мобильному приложению, CRM, продуктам «1С» и др.
При регистрации на Ваш счет будет начислено 100 бонусных рублей для тестирования нашего API,
эквивалент 25 бесплатных распознаваний, для тестирования нашего API.
По умолчанию API-сервис настроен на распознавание Паспортов РФ.
Если Вам необходимо подключить другие документы – свяжитесь с нами.
Перед началом работы с API нужно:
Для получения ключей доступа:
Перейдите в раздел Проекты и нажмите на кнопку :
В открывшемся окне вам доступны token, machine_uid и project_id. Также доступны примеры по загрузке документов на обработку и получения результатов обработки:
Для организации взаимодействия с системой и настройки обработки документов нужно реализовать два метода API.
С обобщенным техническим описанием API и кодов ошибок можно ознакомиться по ссылке
С наглядным примером использования на выбранных проектах можно ознакомиться в разделе Проекты или в примерах ниже.
| Ключ | Тип | Описание |
|---|---|---|
| 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 | не живой/живой | 0 или 1 |
| probability | вероятность живости | 0...1 |
| error_code | код ошибки | 0...1100010 |
| comment | краткий комментарий о проверке | текст |
Проверяет совпадает ли изображение человека в паспорте и изображение человека на селфи
Расшифровка результата проверки match_faces :
| Результат | Описание | Значения |
|---|---|---|
| match_faces | не совпадает/совпадает | 0 или 1 |
| similarity | на сколько изображения лиц схожи | 0...1 |
| error_code | код ошибки | 0...1100010 |
| comment | краткий комментарий о проверке | текст |
Для ознакомления со всеми возможными кодами ошибок,
а также для перевода на русский язык ошибок скачайте json-файл тут.
Пример документа
Документ для обработки должен быть закодирован в формат base64
Python
import requests import base64with 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 | номер документа для дальнейшего отслеживания |
import requests
requests.get("https://api.beorg.ru/api/document/result/<номер документа>?token=<токен>")
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": []
}
}
| Код ошибки | Описание | Комментарий |
|---|---|---|
| 400 | некорректный запрос, не хватает данных | проверьте корректность данных в запросе |
| 401 | ошибка авторизации | в запросе не указаны или указаны некорректные token и machine_uid |
| 402 | недостаточно средств | необходимо пополнить баланс |
| 409 | документ уже существует | не посылайте один и тот же файл несколько раз |
| 413 | слишком большой размер файла | не посылайте файлы сумма размеров, которых более 800 Мб |
| 500 | ошибка сервера | ошибка на стороне сервера |
| 503 | ошибка сервера | ваш запрос слишком долго обрабатывается |
| Код ошибки | Описание | Комментарий |
|---|---|---|
| 400 | некорректный запрос, не хватает данных | проверьте корректность данных в запросе |
| 401 | ошибка авторизации | в запросе не указаны или указаны некорректные token и machine_uid |
| 404 | документ не найден или в обработке | получение результата возможно только после завершения обработки |
| 500 | ошибка сервера | ошибка на стороне сервера |
Поддержка осуществляется в рабочее время, с 9.00 до 19.00 по Москве.