Привет!
Вы на странице технической информации по API-сервису компании «Биорг».
Мы подготовили этот документ для разработчиков, чтобы в несколько простых шагов
подключить сервис распознавания документов Биорг к сайту, ПО,
мобильному приложению, CRM, продуктам «1С» и др.
При регистрации на Ваш счет будет начислено 100 бонусных рублей,
эквивалент 25 бесплатных распознаваний первого разворота Паспорта РФ, для тестирования нашего API.
Перед началом работы с API нужно:
token и machine_uid) и идентификатор сценария обработки документа (project_id)Для получения ключей доступа:
Перейдите в раздел Проекты и нажмите на кнопку :
В открывшемся окне вам доступны token, machine_uid и project_id. Также доступны примеры по загрузке документов на обработку и получения результатов обработки:
Для организации взаимодействия с системой и настройки обработки документов нужно реализовать два метода API.
/api/bescan/add_document отправляется файл, файл в формате строки base64 для обработки и параметры token, machine_uid, project_id. При успешной отправке в теле ответа будет номер созданного документа в ключе document_id, его нужно использовать для получения результата./api/bescan/result можно запросить результат обработки. В качестве ответа возвращается:
С обобщенным техническим описанием API и кодов ошибок можно ознакомиться по ссылке.
С наглядным примером использования на выбранных проектах можно ознакомиться в разделе Проекты или в примерах ниже.
Предусматривает только один сценарий обработки: распознавание Паспорта РФ страниц 2 и 3 (данные о выдаче паспорта и сведения о личности владельца) в автоматическом режиме.
Описание тарифа Биорг.Паспорт: ссылка.
Описание параметров распознавания паспорта гражданина РФ (2 и 3 страницы).
Предусматривает несколько сценариев обработки для различных типов документов.
Включает в себя распознавание документов в автоматическом режиме. В одном запросе могут быть изображения от 1 до 10 документов.
Описание параметров распознавания паспорта гражданина РФ (2 и 3 страницы).
Обратите внимание, что на данный момент проверки наличия фотографии и подписи на документе отключены
Для нераспознанных автоматически документов или их отдельных полей, а также для документов и полей распознанных не уверенно, например, рукописных или фотографий слабого качества – документы в обезличенном формате передаются на проверку операторам-Верификаторам.
Более 100 верификаторов работают он-лайн в режиме 24/7. Среднее время проверки одного документа – 60 сек.
Работа Верификаторов тщательно проверяется и контролируется, в этом сценарии мы гарантируем качество распознавания выше 99% (для документов соответствующих требованиям).
Информация каждого документа обезличивается – ни один верификатор не получает доступа к полному документу.
Проверка схожести фотографии в документе и фотографии(селфи) человека. Селфи или фотография должны быть загружены в виде отдельного изображения. Фотография в документе находится и выделяется автоматически.
Может работать в 2х режимах. * Через ПО Luna компании Vision Labs – сверка биометрии осуществляется в автоматическом режиме. * Через операторов Верификаторов – сверка биометрии осуществляется визуально.
Описание параметров распознавания типов документов.
Проверяет живой ли человек на изображении, что лицо не закрыто маской, не замазано в фотошопе и тд. Опция полезна и обычно используется для онлайн регистраций.
Для использования данного сценария необходима загрузка селфи или фотографии в виде отдельного изображения. Также может быть использована, как отдельная опция см.: Биометрия.
Может работать в 2х режимах. * Через ПО Luna компании Vision Labs – сверка биометрии осуществляется в автоматическом режиме. * Через операторов Верификаторов – сверка биометрии осуществляется визуально.
Описание параметров распознавания типов документов – вставить ссылку на соответствующий раздел в Типах документов Описание тарифа Биорг.Универсальный: ссылка.
Описание параметров распознавания типов документов.
| № | Тип документа | Описание документа | Рекомендации по загружаемым файлам | Мин. срок обработки, сек. (автораспознавание/с верификацией) | Макс. срок обработки, сек. (автораспознавание/с верификацией) | Гарантия качества не ниже 99% (1 ошибка на 100 полей) | |||
| Форматы файлов | Размер одной страницы | Кол-во страниц | Кол-во файлов в минуту | ||||||
| 1 | Паспорт гражданина РФ (стр 2-3) | изображение лицевого разворота паспорта РФ, стр 2-3 | JPEG, TIFF, | 3 Мб | 1 | 10 | 3/30 | 10/120 | применимо для опции с проверкой верификаторами |
| 2 | Паспорт гражданина РФ (стр 2-3 + регистрация) | изображение лицевого разворота паспорта РФ, стр 2-3 и регистрации | 3 Мб | 2 | 10 | 6/30 | 15/120 | ||
| 3 | Проверка Фото на лайфнес | Проверяем что на фотографии живой человек, без маски. Также на базе этой опции может работать идентификация пользователей по Фото | 5 Мб | 1 | 10 | 2/30 | 5/120 | ||
| 4. | Ошибочно загруженный документ/документ не из списка | обработка ошибочно загруженных изображений, не содержащих необходимых для распознавания документов | 3 Мб | 1 | 10 | 1/20 | 5/20 | ||
| Если загружаемые вами файлы не соотсетствуют указанным требованиям, то распознавание может осуществляться в более длительный срок | |||||||||
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура передаваемых данных:
| Ключ | Описание |
|---|---|
| project_id | название проекта |
| token | токен доступа |
| machine_uid | идентификатор устройства |
| images | список из строк base64 (файлов) |
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
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": project_id, "token": token, "machine_uid": machine_uid, "images": [b64], }, ) r.json()
Структура передаваемых данных:
| Ключ | Описание |
|---|---|
| project_id | название проекта |
| token | токен доступа |
| machine_uid | идентификатор устройства |
| images | список из строк base64 (файлов) |
| process_info | настройки обработки |
Структура prosess_info:
| Ключ | Описание |
|---|---|
| key | свободный ключ для разделения документов при загрузке и получении результатов если не указан вместо него используется улюч type |
| type | тип документа |
| options | опции обработки документа |
Структура process_info.options:
| Ключ | Описание |
|---|---|
| stages | этапы обработки документа (Доступны: verification, biometry_match, biometry_liveness) |
| relation | связь с иным документом в одном запросе (Доступны: biometry_match) |
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
Python
import requests import base64with open("<путь до файла паспорта>", "rb") as image_file: b64_passport = base64.b64encode(image_file.read()).decode()
with open("<путь до файла фотографии(селфи)>", "rb") as image_file: b64_selfie = base64.b64encode(image_file.read()).decode()
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_passport, b64_selfie], "process_info": [ { "key": "PASSPORT1", "type": "PASSPORT", "options": { "stages": [ "verification", "biometry_match", ], "relation": { "biometry_match": "SELFIE1", }, } }, { "key": "SELFIE1", "type": "SELFIE", "options": { "stages": [ "biometry_liveness", ], }, }, ], }, ) r.json()
В примере выше по ключам images и process_info представлены 2 файла: паспорт и фотография(селфи).
В images первым указан файл паспорта, а вторым указан файл фотографии(селфи). В process_info в том же порядке указаны настройки обработки документов.
Обратите внимание, что порядок и длина images и process_info должны быть одинаковыми
В process_info.options.relation указывается, что паспорт (PASSPORT) должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
"relation": {
"biometry_match": "SELFIE1",
},
А фотография(селфи) в свою очередь должно пройти проверку на живость (biometry_liveness)
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": [
"biometry_liveness",
],
},
},
Структура передаваемых данных:
| Ключ | Описание |
|---|---|
| project_id | название проекта |
| token | токен доступа |
| machine_uid | идентификатор устройства |
| images | список из строк base64 (файлов) |
| process_info | настройки обработки |
Структура prosess_info:
| Ключ | Описание |
|---|---|
| key | свободный ключ для разделения документов при загрузке и получении результатов если не указан вместо него используется улюч type |
| type | тип документа |
| options | опции обработки документа |
Структура process_info.options:
| Ключ | Описание |
|---|---|
| stages | этапы обработки документа (Доступны: verification, biometry_match, biometry_liveness) |
| relation | связь с иным документом в одном запросе (Доступны: biometry_match) |
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
Python
import requests import base64with open("<путь до файла паспорта>", "rb") as image_file: b64_passport1 = base64.b64encode(image_file.read()).decode() image_file.close()
with open("<путь до файла фотографии(селфи)>", "rb") as image_file: b64_selfie = base64.b64encode(image_file.read()).decode() image_file.close()
r = requests.post( "https://cdp.stage.beorg.ru/api/bescan/add_document", headers={"Content-Type": "application/json", "Accept-Language": "ru"}, json={ "project_id": project_id, "token": token, "machine_uid": machine_uid, "images": [b64_passport1, b64_selfie], "process_info": [ { "key": "PASSPORT_REG1", "type": "PASSPORT_REG", "options":{ "relation": { "biometry_match": "SELFIE1" }, "stages": [ "biometry_match" ] } }, { "key": "SELFIE1", "type": "SELFIE" } ], }, )
r.json()
В примере выше по ключам images и process_info представлены 2 файла: паспорт (стр 2-5) и фотография(селфи).
В images первым указан файл паспорта, а вторым указан файл фотографии(селфи). В process_info в том же порядке указаны настройки обработки документов.
Обратите внимание, что порядок и длина images и process_info должны быть одинаковыми
В process_info.options.relation указывается, что паспорт (PASSPORT) должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
"relation": {
"biometry_match": "SELFIE1",
},
Структура передаваемых данных:
| Ключ | Описание |
|---|---|
| project_id | название проекта |
| token | токен доступа |
| machine_uid | идентификатор устройства |
| images | список из строк base64 (файлов) |
| process_info | настройки обработки |
Структура process_info.options:
| Ключ | Описание |
|---|---|
| stages | этапы обработки документа (Доступны: verification, biometry_match, biometry_liveness) |
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
import requests
import base64
with open("<путь до файла фотографии(селфи)>", "rb") as image_file:
b64_selfie = base64.b64encode(image_file.read()).decode()
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_selfie],
"process_info": [
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": [
"biometry_liveness"
]
}
}
]
},
)
r.json()
{
"document_id": "<номер документа>"
}
| Ключ | Описание |
|---|---|
| document_id | номер документа для дальнейшего отслеживания |
Python
import requestsrequests.get("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",
"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",
"MRZ1": "0.9999",
"MRZ2": "0.9999",
"HasPhoto": "0.9999",
"HasOwnerSignature": "0.9999"
}
},
"verifications": {
"status": 0,
"status_text": "ок",
"bad_fields": []
}
}
{
"document_id": "s-12345",
"documents": [
{
"key": "PASSPORT_REG1",
"type": "PASSPORT_REG",
"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": []
}
}
]
}
| Ключ | Тип | Описание |
|---|---|---|
| document_id | string | номер документа в формате s-<номер документа> |
| documents | list | список данных по каждому документу |
| documents[].key | string | ключ заданный при отправке документа для отслеживания |
| documents[].type | string | тип документа |
| documents[].data | dictionary | обработанные данные по каждому полю, содержит ключи полей и их определенные значения |
| IssuedBy | string | кем выдан паспорт |
| IssueDate | string | дата выдачи паспорта |
| IssueId | string | код подразделения |
| Series | string | серия паспорта с первого разворота |
| Number | string | номер паспорта с первого разворота |
| Gender | string | пол |
| LastName | string | фамилия |
| FirstName | string | имя |
| MiddleName | string | отчество |
| BirthDate | string | дата рождения |
| BirthPlace | 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 |
| Ключ | Тип | Описание |
|---|---|---|
| document_id | string | номер документа в формате s-<номер документа> |
| documents | list | список данных по каждому документу |
| documents[].key | string | ключ заданный при отправке документа для отслеживания |
| documents[].type | string | тип документа |
| documents[].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 | адрес регистрации(отличие от от сценария обработки Паспорт гражданина РФ (2 и 3 страницы)) |
| 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 |
| Ключ | Тип | Описание |
|---|---|---|
| liveness | integer | живой/не живой |
| probability | float | вероятность живости |
| error_code | integer | код ошибки |
| comment | string | краткий комментарий о проверке |
Подробнее ознакомиться с биометрическими проверками вы можете в разделе Биометрия
В результате обработки входящего паспорта будет доступно поле verifications,
в котором находятся следующие данные:
| Название | Описание | Тип данных |
|---|---|---|
| status | статус проверки | integer |
| status_text | текстовое описание статуса | string |
| bad_fields | список полей полей имеющих несоответствия | list |
Поле status может отражать следующие варианты кодов проверки:
| Код | Описание |
|---|---|
| 0 | ок |
| 1 | одно или несколько обязательных полей отсутствует или имеет неверный формат |
| 2 | МЧЗ не согласуется со значением полей |
| 3 | серия паспорта не согласуется с кодом подразделения |
| 4 | место выдачи не согласуется с кодом подразделения |
| 5 | паспорт выдан до 14-ти лет |
| 6 | паспорт выдан до 1 октября 1997 года |
| 7 | паспорт просрочен |
Вы можете использовать биометрические проверки, чтобы сравнить, соответствует ли фотография на документе сделанной фотографии(селфи).
Сценарий актуален при регистрации на сайте или в приложении, когда требуется, например, паспорт и фотогарфия(селфи)
Удобно при регистрации в финансовых , шеринговых сервисах (аренда авто и т.д.), при посуточной аренде жилья и других сценариях регистрации.
Биометрическую идентификацию можно применять и отдельно: чтобы убедиться, что изображение на фотографии(селфи) человека соответствует изображению в документе и не является маской
Проверки биометрии доступны в тарифах Биорг.Универсальный и Биорг.KYC
Проверки биометрии осуществляются средствами компании-партнера VisionLabs
Они могут быть использованы как отдельный вид обработки и как дополнительная опция при обработке документов
Обратите внимание что комментарий ответа "Sucsess" свидетельствует о корректной работе биометрической проверки и в то же время не говорит о не совпадает/совпадает или не живой/живой
Проверяет живой ли человек на изображении
Доступна при обработке документов с фотографией личности, а также при обработке только фотография(селфи) (без документов)
Расшифровка результата проверки 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-файл тут.
| Код ошибки | Описание | Комментарий |
|---|---|---|
| 400 | некорректный запрос, не хватает данных | проверьте корректность данных в запросе |
| 401 | ошибка авторизации | в запросе не указаны или указаны некорректные token и machine_uid |
| 402 | недостаточно средств | необходимо пополнить баланс |
| 409 | документ уже существует | не посылайте один и тот же файл несколько раз |
| 413 | слишком большой размер файла | не посылайте файлы сумма размеров, которых более 800 Мб |
| 500 | ошибка сервера | ошибка на стороне сервера |
| 503 | ошибка сервера | ваш запрос слишком долго обрабатывается |
| Код ошибки | Описание | Комментарий |
|---|---|---|
| 400 | некорректный запрос, не хватает данных | проверьте корректность данных в запросе |
| 401 | ошибка авторизации | в запросе не указаны или указаны некорректные token |
| 404 | документ не найден | указан номер документа, который не существует в системе (не был загружен или был удалён) |
| 425 | документ ещё в обработке | получение результата возможно только после завершения обработки |
| 500 | ошибка сервера | ошибка на стороне сервера |
Поддержка осуществляется в рабочее время, с 9.00 до 19.00 по Москве.