Привет!
Вы на странице технической информации по 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 и кодов ошибок можно ознакомиться по ссылке.
С наглядным примером использования на выбранных проектах можно ознакомиться в разделе Проекты или в примерах ниже.
№ | Тип документа | Описание документа | Рекомендации по загружаемым файлам | Мин. срок обработки, сек. (автораспознавание/с верификацией) | Макс. срок обработки, сек. (автораспознавание/с верификацией) | Гарантия качества не ниже 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 | ||
Если загружаемые вами файлы не соотсетствуют указанным требованиям, то распознавание может осуществляться в более длительный срок |
Тариф Биорг.Паспорт Авто включает в себя распознавание первого разворота Паспорта РФ (2 и 3 страницы).
Предусматривает только один сценарий обработки: распознавание Паспорта РФ страниц 2 и 3 (данные о выдаче паспорта и сведения о личности владельца) в автоматическом режиме.
Описание тарифа Биорг.Паспорт: ссылка.
Описание параметров распознавания паспорта гражданина РФ (2 и 3 страницы).
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_PASSPORT_AUTO", "images": ["<строка base64>"], "token": token, "machine_uid": machine_uid }
Ключ | Описание |
---|---|
project_id | название проекта |
token | токен доступа |
machine_uid | идентификатор устройства |
images | список из строк base64 (файлов) |
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Ключ | Описание |
---|---|
document_id | идентификатор документа для отслеживания результата |
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
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": project_id, "token": token, "machine_uid": machine_uid, "images": [b64], }, ) r.json()
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-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 | 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} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
Тариф Биорг.Паспорт Авто включает в себя распознавание следующих документов:
В соответствии с перечнем документов, в запросах должны присутствовать следующие ключи в зависимости от вида документа:
Документ | Ключ |
---|---|
Паспорт РФ (2 и 3 страницы) | PASSPORT |
Паспорт РФ (2 и 3 страницы) + регистрация | PASSPORT_REG |
Проверка селфи на живость | SELFIE |
Водительское удостоверение | DLIC |
Свидетельство о регистрации ТС | STS |
Паспорт иностранного гражданина | PASSPORT_FRGN |
С примерами использования ключей вы можете ознакомиться в примерах ниже
Предусматривает несколько сценариев обработки для различных типов документов.
Включает в себя распознавание документов в автоматическом режиме. В одном запросе могут быть изображения от 1 до 10 документов.
Обратите внимание, что на данный момент проверки наличия фотографии и подписи на документе отключены
Для нераспознанных автоматически документов или их отдельных полей, а также для документов и полей распознанных не уверенно, например, рукописных или фотографий слабого качества – документы проходят дополнительную обработку, в т.ч. в обезличенном формате отдельные поля документа могут передаваться на проверку операторам-Верификаторам.
Более 100 верификаторов работают он-лайн в режиме 24/7. Среднее время проверки одного документа – 60 сек.
В этом сценарии мы гарантируем качество распознавания выше 99% (для документов соответствующих требованиям).
Для обработки документа с использованием данного сценария используйте ключ - verification
Проверка схожести фотографии в документе и фотографии(селфи) человека. Селфи или фотография должны быть загружены в виде отдельного изображения. Фотография в документе находится и выделяется автоматически.
Может работать в 2х режимах:
Через ПО Luna компании Vision Labs – сверка биометрии осуществляется в автоматическом режиме.
Через операторов Верификаторов – сверка биометрии осуществляется визуально.
Для обработки документа с использованием данного сценария используйте ключ - biometry_match
Проверяет живой ли человек на изображении, что лицо не закрыто маской, не замазано в фотошопе и тд. Опция полезна и обычно используется для онлайн регистраций.
Для использования данного сценария необходима загрузка селфи или фотографии в виде отдельного изображения. Также может быть использована, как отдельная опция см.: Биометрия.
Может работать в 2х режимах:
Через ПО Luna компании Vision Labs – сверка биометрии осуществляется в автоматическом режиме.
Через операторов Верификаторов – сверка биометрии осуществляется визуально.
Для обработки документа с использованием данного сценария используйте ключ - biometry_liveness
Описание параметров распознавания типов документов.
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла паспорта>", "rb") as image_file: b64 = 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, 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 указывается, что документ должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
"relation": { "biometry_match": "SELFIE1", },
А фотография(селфи) в свою очередь должно пройти проверку на живость (biometry_liveness)
{ "key": "SELFIE1", "type": "SELFIE", "options": { "stages": [ "biometry_liveness", ], }, },
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-12345", "documents": [ { "key": "PASSPORT", "type": "PASSPORT", "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} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла паспорта>", "rb") as image_file: b64 = 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, b64_selfie], "process_info": [ { "key": "PASSPORT_REG1", "type": "PASSPORT_REG", "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 указывается, что документ должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
"relation": { "biometry_match": "SELFIE1", },
А фотография(селфи) в свою очередь должно пройти проверку на живость (biometry_liveness)
{ "key": "SELFIE1", "type": "SELFIE", "options": { "stages": [ "biometry_liveness", ], }, },
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "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 | место рождения |
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 |
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
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()
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла ВУ>", "rb") as image_file: b64 = 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, b64_selfie], "process_info": [ { "key": "DLIC1", "type": "DLIC", "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 указывается, что документ должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
"relation": { "biometry_match": "SELFIE1", },
А фотография(селфи) в свою очередь должно пройти проверку на живость (biometry_liveness)
{ "key": "SELFIE1", "type": "SELFIE", "options": { "stages": [ "biometry_liveness", ], }, },
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-7137", "documents": [ { "key": "DLIC1", "type": "DLIC", "data": { "Gender": "M", "LastName": "LastName", "FirstName": "FirstName", "MiddleName": "MiddleName", "BirthDate": "BirthDate", "IssueDate": "IssueDate", "EndDate": "EndDate", "IssuedBy": "IssuedBy", "Series": "Series", "Number": "Number", "PlaceOfResidence": "PlaceOfResidence", "Categories": "Categories", "CategoryAStartDate": null, "CategoryAEndDate": null, "CategoryA1StartDate": null, "CategoryA1EndDate": null, "CategoryBStartDate": null, "CategoryBEndDate": null, "CategoryB1StartDate": null, "CategoryB1EndDate": null, "CategoryCStartDate": null, "CategoryCEndDate": null, "CategoryC1StartDate": null, "CategoryC1EndDate": null, "CategoryDStartDate": null, "CategoryDEndDate": null, "CategoryD1StartDate": null, "CategoryD1EndDate": null, "CategoryBEStartDate": null, "CategoryBEEndDate": null, "CategoryCEStartDate": null, "CategoryCEEndDate": null, "CategoryC1EStartDate": null, "CategoryC1EEndDate": null, "CategoryDEStartDate": null, "CategoryDEEndDate": null, "CategoryD1EStartDate": null, "CategoryD1EEndDate": null, "CategoryMStartDate": null, "CategoryMEndDate": null, "CategoryTmStartDate": null, "CategoryTmEndDate": null, "CategoryTbStartDate": null, "CategoryTbEndDate": null, "SpecialMarks": "" }, "metadata": { "confidences": { "Gender": 1, "LastName": 0.998705923557282, "FirstName": 0.987468838691711, "MiddleName": 0.987468838691711, "BirthDate": 0.999436318874359, "IssueDate": 0.996931493282318, "EndDate": 0.996931493282318, "IssuedBy": 0.997896015644074, "PlaceOfResidence": 0.999530375003815, "Categories": 0.997450947761536 }, "verifications": { }, "biometrics": { "match_faces": { "match_faces": 1, "similarity": 1, "error_code": 0, "comment": "Success" } } } }, { "key": "SELFIE", "type": "SELFIE", "data": { }, "metadata": { "confidences": null, "verifications": { }, "biometrics": { "liveness": { "liveness": 0, "probability": 0, "error_code": 0, "comment": "not live [low probability] Success" }, "match_faces": { "match_faces": 1, "similarity": 1, "error_code": 0, "comment": "Success" } } } } ] }
Описание ключей
Ключ | Тип | Описание |
---|---|---|
document_id | string | номер документа в формате s-<номер документа> |
documents | list | список данных по каждому документу |
documents[].key | string | ключ заданный при отправке документа для отслеживания |
documents[].type | string | тип документа |
documents[].data | dictionary | обработанные данные по каждому полю, содержит ключи полей и их определенные значения |
Gender | string | пол |
LastName | string | фамилия |
FirstName | string | имя |
MiddleName | string | отчество |
BirthDate | string | дата рождения |
IssueDate | string | дата выдачи |
EndDate | string | дата окончания |
IssuedBy | string | кем выдан |
PlaceOfResidence | string | место жительства |
Series | string | серия |
Number | string | номер |
Categories | string | категории ТС |
Category<код категории>StartDate | string | дата выдачи прав категории |
Category<код категории>EndDate | string | дата истечения прав категории |
SpecialMarks | string | специальные отметки |
metadata | dictionary | содержит ключи метаданных |
confidences | dictionary {key: float} |
метаданные с точностью обработки по каждому полю - содержит ключи полей и значения уровня уверенности. Значения от 0.0000 до 0.9999, где чем значение больше, тем уверенность в результате выше. Максимальная уверенность - 0.9999. |
verifications | dictionary {key: boolean, key: integer} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла СТС>", "rb") as image_file: b64 = 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], "process_info": [ { "key": "STS1", "type": "STS", } ], }, ) r.json()
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-7138", "documents": [ { "key": "STS1", "type": "STS", "data": { "reg_number": "reg_number", "vin": "vin", "brand_rus": "brand_rus", "model_rus": "model_rus", "brand_eng": "brand_eng", "model_eng": "model_eng", "vehicle_type": "vehicle_type", "vehicle_category": "vehicle_category", "release_year": "release_year", "engine_model": "engine_model", "engine_number": "engine_number", "vehicle_chassis": "vehicle_chassis", "vehicle_body": "vehicle_body", "color": "color", "vehicle_type_approval": "vehicle_type_approval", "engine_power": "engine_power", "engine_volume": "engine_volume", "ecologic_class": "ecologic_class", "passport_series": "passport_series", "passport_number": "passport_number", "max_mass": "max_mass", "mass": "mass", "data_temporary_reg": "data_temporary_reg", "series_bottom_front": "series_bottom_front", "number_bottom_front": "number_bottom_front", "SeriesTopBack": "SeriesTopBack", "NumberTopBack": "NumberTopBack", "LastnameRu": "LastnameRu", "FirstnameRu": "FirstnameRu", "MiddlenameRu": "MiddlenameRu", "LastnameEng": "LastnameEng", "FirstnameEng": "FirstnameEng", "FederationSubject": "FederationSubject", "Area": "Area", "Locality": "Locality", "Street": "Street", "HouseNumber": "HouseNumber", "BuildingNumber": "BuildingNumber", "ApartmentNumber": "ApartmentNumber", "SpecialMarks": "SpecialMarks", "DepartmentCode": "DepartmentCode", "Date": "Date", "SeriesBottomBack": "SeriesBottomBack", "NumberBottomBack": "NumberBottomBack" }, "metadata": { "confidences": { "reg_number": 1, "vin": 0.997328579425812, "brand_rus": 1, "model_rus": 1, "brand_eng": 1, "model_eng": 1, "vehicle_category": 1, "release_year": 1, "vehicle_chassis": 1, "vehicle_body": 1, "color": 1, "engine_power": 0.999571621417999, "ecologic_class": 1, "passport_series": 0.999932527542114, "passport_number": 0.999932527542114, "max_mass": 0.999957740306854, "mass": 0.999994158744812, "series_bottom_front": 0.997173547744751, "number_bottom_front": 0.997173547744751, "SeriesTopBack": 0.997505486011505, "NumberTopBack": 0.997505486011505, "LastnameRu": 0.992222011089325, "FirstnameRu": 0.998002409934998, "MiddlenameRu": 0.998872518539429, "LastnameEng": 0.961436331272125, "FirstnameEng": 0.999751210212708, "FederationSubject": 1, "Locality": 0.997237503528595, "Street": 0.996907293796539, "HouseNumber": 0.999993324279785, "SpecialMarks": 0.930226266384125, "DepartmentCode": 0.999892055988312, "Date": 0.961017608642578, "SeriesBottomBack": 0.997839689254761, "NumberBottomBack": 0.997839689254761 }, "verifications": { } } } ] }
Описание ключей
Ключ | Тип | Описание |
---|---|---|
document_id | string | номер документа в формате s-<номер документа> |
documents | list | список данных по каждому документу |
documents[].key | string | ключ заданный при отправке документа для отслеживания |
documents[].type | string | тип документа |
documents[].data | dictionary | обработанные данные по каждому полю, содержит ключи полей и их определенные значения |
reg_number | string | Регистрационный номер |
vin | string | VIN-номер |
brand_rus | string | марка на русском языке |
model_rus | string | модель на русском языке |
brand_eng | string | марка на английском языке |
model_eng | string | модель на английском языке |
vehicle_type | string | тип ТС |
vehicle_category | string | категория ТС |
release_year | string | год выпуска ТС |
engine_model | string | модель двигателя |
engine_number | string | номер двигателя |
vehicle_chassis | string | шасси (рама) № |
vehicle_body | string | кузов |
color | string | цвет |
vehicle_type_approval | string | одобрение типа ТС |
engine_power | string | мощность двигателя |
engine_volume | string | рабочий объем двигателя |
ecologic_class | string | экологический класс |
passport_series | string | серия паспорта ТС |
passport_number | string | номер паспорта ТС |
max_mass | string | технически допустимая максимальная масса |
mass | string | масса в снаряженном состоянии |
data_temporary_reg | string | срок временной регистрации |
series_bottom_front | string | серия документа(СТС) |
number_bottom_front | string | номер документа(СТС) |
SeriesTopBack | string | серия СТС вверху |
NumberTopBack | string | номер СТС вверху |
LastnameRu | string | фамилия владельца на русском языке |
FirstnameRu | string | имя владельца на русском языке |
MiddlenameRu | string | отчество на русском языке |
LastnameEng | string | фамилия владельца на английском языке |
FirstnameEng | string | имя владельца на английском языке |
FederationSubject | string | республика,край,область |
Area | string | район |
Locality | string | населенный пункт |
Street | string | улица |
HouseNumber | string | дом |
BuildingNumber | string | корпус (строение) |
ApartmentNumber | string | номер квартиры |
SpecialMarks | string | особые отметки |
DepartmentCode | string | код подразделения ГИБДД |
Date | string | дата выдачи |
SeriesBottomBack | string | серия СТС снизу |
NumberBottomBack | string | номер СТС снизу |
metadata | dictionary | содержит ключи метаданных |
confidences | dictionary {key: float} |
метаданные с точностью обработки по каждому полю - содержит ключи полей и значения уровня уверенности. Значения от 0.0000 до 0.9999, где чем значение больше, тем уверенность в результате выше. Максимальная уверенность - 0.9999. |
verifications | dictionary {key: boolean, key: integer} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Обрабатываются только поля напечатанные латиницей, кириллица и национальные алфавиты не поддерживаются
Если необходима обработка кириллицы или других алфавитов, напишите нам – добавим! kyc@beorg.ru
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла Паспорта иностранного гражданина>", "rb") as image_file: b64 = 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, b64_selfie], "process_info": [ { "key": "PASSPORT_FRGN1", "type": "PASSPORT_FRGN", } ], }, ) r.json()
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-7141", "documents": [ { "key": "PASSPORT_FRGN1", "type": "PASSPORT_FRGN", "data": { "Code": "Code", "Number": "Number", "IDNumber": "IDNumber", "IssuedBy": "IssuedBy", "Gender": "Gender", "LastName": "LastName", "FirstName": "FirstName", "MiddleName": "MiddleName", "BirthDate": "BirthDate", "BirthPlace": "BirthPlace", "IssueDate": "IssueDate", "FutureDate": "FutureDate", "Nationality": "Nationality", "MRZ1": "MRZ1", "MRZ2": "MRZ2", "HasPhoto": "", "HasOwnerSignature": "" }, "metadata": { "confidences": null, "verifications": { } } } ] }
Описание ключей
Ключ | Тип | Описание |
---|---|---|
document_id | string | номер документа в формате s-<номер документа> |
documents | list | список данных по каждому документу |
documents[].key | string | ключ заданный при отправке документа для отслеживания |
documents[].type | string | тип документа |
documents[].data | dictionary | обработанные данные по каждому полю, содержит ключи полей и их определенные значения |
Code | string | Код государства |
Number | string | Номер иностранного паспорта |
IDNumber | string | Идентификационный номер (ID карта) |
IssuedBy | string | Кем выдан |
Gender | string | Пол |
LastName | string | Фамилия |
FirstName | string | Имя |
MiddleName | string | Отчество |
BirthDate | string | Дата рождения |
BirthPlace | string | Место рождения |
IssueDate | string | Дата выдачи |
FutureDate | string | Дата, до которой документ действителен |
Nationality | string | Гражданство |
MRZ1 | string | МЧЗ строка 1 |
MRZ2 | string | МЧЗ строка 2 |
HasPhoto | string | Наличие фото |
HasOwnerSignature | string | Наличие подписи владельца |
metadata | dictionary | содержит ключи метаданных |
confidences | dictionary {key: float} |
метаданные с точностью обработки по каждому полю - содержит ключи полей и значения уровня уверенности. Значения от 0.0000 до 0.9999, где чем значение больше, тем уверенность в результате выше. Максимальная уверенность - 0.9999. |
verifications | dictionary {key: boolean, key: integer} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
Примеры изображений документов
Документы для обработки должны быть закодированы в формат base64
Структура запроса:
url: https://api.beorg.ru/api/bescan/add_document method: POST headers: Content-Type: application/json body: { "project_id": "U_RATE_2", "images": ["<строка base64>"], "process_info": [настройки обработки] "token": token, "machine_uid": machine_uid }
Пример ответа об успешной загрузке:
{ "document_id": "s-12345" }
Структура передаваемых данных:
Ключ | Описание |
---|---|
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 обратитесь в подраздел "Начало работы"
import requests import base64 with open("<путь до файла СТС>", "rb") as image_file: b64 = 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], "process_info": [ { "key": "SNILS1", "type": "SNILS", } ], }, ) r.json()
Структура запроса:
url: https://api.beorg.ru/api/document/result/s-12345?token=methods: GET, POST
import requests import base64 r = requests.get("https://api.beorg.ru/api/document/result/s-12345?token=") r.json()
Пример ответа по обработанному документу:
{ "document_id": "s-7580", "documents": [ { "key": "SNILS", "type": "SNILS", "data": { "Number": "Number", "LastName": "LastName", "FirstName": "FirstName", "MiddleName": "MiddleName", "Gender": "Gender", "BirthDate": "BirthDate", "BirthPlace": "BirthPlace", "RegistrationDate": null }, "metadata": { "confidences": { "Number": 0.983924329280853, "Gender": 0.999994397163391, "Lastname": 0.999999761581421, "Firstname": 0.999998807907105, "Middlename": 0.999996542930603, "BirthDate": 0.999987244606018, "BirthPlace": 0.999998807907105 }, "verifications": { } } } ] }
Описание ключей
Ключ | Тип | Описание |
---|---|---|
document_id | string | номер документа в формате s-<номер документа> |
documents | list | список данных по каждому документу |
documents[].key | string | ключ заданный при отправке документа для отслеживания |
documents[].type | string | тип документа |
documents[].data | dictionary | обработанные данные по каждому полю, содержит ключи полей и их определенные значения |
Number | string | Номер документа |
Gender | string | Пол |
Lastname | string | Фамилия |
Firstname | string | Имя |
Middlename | string | Отчество |
BirthDate | string | Дата рождения |
BirthPlace | string | Место рождения |
RegistrationDate | string | Дата регистрации |
metadata | dictionary | содержит ключи метаданных |
confidences | dictionary {key: float} |
метаданные с точностью обработки по каждому полю - содержит ключи полей и значения уровня уверенности. Значения от 0.0000 до 0.9999, где чем значение больше, тем уверенность в результате выше. Максимальная уверенность - 0.9999. |
verifications | dictionary {key: boolean, key: integer} |
метаданные совершенных проверок - содержит ключи и их значения проверок, см. Правила проверок |
В результате обработки входящего паспорта будет доступно поле 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 Мб |
415 | неподдердиваемый формат файла | строка base64 некорректна или файл имеет неподдердживаемое расширение |
500 | ошибка сервера | ошибка на стороне сервера |
503 | ошибка сервера | ваш запрос слишком долго обрабатывается |
Код ошибки | Описание | Комментарий |
---|---|---|
400 | некорректный запрос, не хватает данных | проверьте корректность данных в запросе |
401 | ошибка авторизации | в запросе не указаны или указаны некорректные token |
404 | документ не найден | указан номер документа, который не существует в системе (не был загружен или был удалён) |
425 | документ ещё в обработке | получение результата возможно только после завершения обработки |
500 | ошибка сервера | ошибка на стороне сервера |
Специально для наших клиентов мы подготовили удобные наборы интеграций, которые позволят сократить время на отладку общения Вашей системы с нашим API.
Не хватает интеграции с вашей информационной системой или сервисом? Напишите нам – добавим! kyc@beorg.ru
Наша обработка работает со всеми версиями продуктов 1С семейства 8.х
Вы можете скачать файл с последней версией интеграции тут.
Поддержка осуществляется в рабочее время, с 9.00 до 19.00 по Москве.