API KYC + WEBApp
Основные составляющие системы
-
API - интерфейс программного взаимодействия. Используется сервером Заказчика для создания запросов на верификацию, получения результатов и управления статусами проверок
-
WEB-интерфейс пользователя - клиентская часть приложения. Предназначена для загрузки фотографий документов и прохождения проверок непосредственно пользователем
-
Личный кабинет - панель административного управления. Позволяет сотрудникам Заказчика в режиме реального времени отслеживать ход проверок, просматривать результаты и при необходимости корректировать статусы вручную.
API
Схема работы с API
⚠️ Важно: лимит — не более 100 запросов в минуту! В случае нарушения в ответ на запросы будет присылаться статус 503.
Запрос на создание идентификации KYC
Запрос регистрирует ссылку в системе Beorg.
⚠️ Примечание: Ссылка на идентификацию Вашего клиента не имеет "срока годности", она хранится в нашей системе бесконечно
⚠️ Важно: В центральном комплекте пользователя отображаются только корректные документы. Некорректные документы игнорируются и сохраняются в дополнительных комплектах
Структура запроса:
url: https://webapp.beorg.ru/kyc/create
method: POST
headers:
Content-Type: application/json
body:
{
"project_id": "U_RATE_3",
"machine_uid": "<machine_uid>",
"token": "token",
"process_info": [
настройки обработки
],
"client_user_token": "внешний id (идентификатор со стороны заказчика, необязательный)",
"expires": время жизни генерируемой ссылки (необязательный, при отсутствии ссылка бессрочная)
}
Структура ответа:
{
"status": true/false статус выполнения запроса,
"error": описание ошибки (если имеется),
"link": постоянная уникальная ссылка на идентификацию,
"user_token": уникальный идентификатор пользователя,
"client_user_token": идентификатор со стороны заказчика,
"qr_code": строка-изображение QR-кода
}
Для получения token, machine_uid и project_id обратитесь в подраздел "Начало работы"
⚠️ Важно: По умолчанию возможность выбора изображений документов из галереи выключена.
⚠️ Для включения возможности выбора изображений документов из галереи к целевым документам в process_info необходимо добавить ключ file_access со значением true
Пример:
{
"key": "PASSPORT1",
"type": "PASSPORT",
"options": {
"stages": ["verification", "biometry_match"],
"relation": {"biometry_match": "SELFIE1"},
},
"file_access": true
}
⚠️ Важно: По умолчанию кол-во попыток на каждый документ не ограничено.
⚠️ Для ограничения попыток в process_info необходимо добавить ключ "attempts" со значением равным кол-ву попыток (для каждого документа указывается отдельно)
Пример:
{
"key": "PASSPORT1",
"type": "PASSPORT",
"options": {
"stages": ["verification", "biometry_match"],
"relation": {"biometry_match": "SELFIE1"},
},
"attempts": 3
}
Пример запроса
Python
import requests
r = requests.post(
"https://webapp.beorg.ru/kyc/create",
headers={"Content-Type": "application/json"},
json={
"project_id": project_id,
"token": token,
"machine_uid": machine_uid,
"process_info": [
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": [
"biometry_liveness",
],
},
"attempts": 3, # 3 попытки
},
{
"key": "PASSPORT1",
"type": "PASSPORT",
"options": {
"stages": [
"verification",
"biometry_match",
],
"relation": {
"biometry_match": "SELFIE1",
},
},
"attempts": 3, # 3 попытки
},
],
"expires": 3600 # срок действия идентификации (3600 секунд = 1 час)
},
)
r.json()
В примере выше по ключу process_info представлен 2 документа: документ Паспорт РФ (2 и 3 страницы) и фотография(селфи).
Эта структура генерирует идентификацию, в которой у пользователя будет запрошено сначала селфи и в случае успешной обработки селфи будет запрошен Паспорт РФ (2 и 3 страницы)
В process_info.options.relation указывается, что документ должен пройти сверку лиц (biometry_match) с фотографией(селфи) (SELFIE1)
⚠️ Важно: Минимальный допустимый порог успешной сверки лиц - 0.95 (95%)
"relation": {
"biometry_match": "SELFIE1",
},
А фотография(селфи) в свою очередь должно пройти проверку на живость (biometry_liveness)
⚠️ Важно: Минимальный допустимый порог успешной проверки живости - 0.9 (90%)
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": [
"biometry_liveness",
],
},
},
Сценарий идентификации: документы, поля и выбор
Кроме документов, в process_info можно добавлять шаги, на которых пользователь выбирает вариант, устанавливает флаг или вводит значение. Все шаги проходятся строго по порядку, каждый шаг — отдельный экран.
Ответы пользователя возвращаются в методе "Получение результатов" в поле additional_data по ключам шагов.
⚠️ Важно: ключи шагов (key) — латиница, цифры и
_, до 64 символов, без повторов. Шагов в process_info — не больше 50. Если шаги заданы неверно, ссылка не создается: в ответеstatus: falseи текст ошибки
Заголовок документа
У документа можно указать свой заголовок — его увидит пользователь на экране загрузки. Без title показывается стандартное название документа.
{
"key": "PASSPORT1",
"type": "PASSPORT",
"title": "Паспорт"
}
title — обычный текст до 200 символов (HTML не обрабатывается).
Выбор варианта (select)
Шаг select предлагает пользователю выбрать один вариант. Вариант — ключ шага ниже по списку: документа, поля или другого select. Выбранный шаг выполняется, остальные варианты пропускаются вместе со своими ветками. Шаги, которые не являются вариантом ни одного select, выполняются всегда.
"process_info": [
{
"type": "select",
"key": "CITIZENSHIP",
"view_type": "selector",
"title": "Выберите гражданство",
"variants": [
{"key": "RU_DOCS", "title": "Гражданин РФ"},
{"key": "FRGN_DOCS", "title": "Не гражданин РФ"}
]
},
{
"type": "select",
"key": "RU_DOCS",
"view_type": "combobox",
"title": "Выберите тип документа",
"text": "Документы для граждан РФ",
"variants": ["PASSPORT1", "DLIC1"]
},
{
"type": "select",
"key": "FRGN_DOCS",
"view_type": "combobox",
"title": "Выберите тип документа",
"variants": ["PASSPORT_FRGN1"]
},
{
"key": "PASSPORT1",
"type": "PASSPORT"
},
{
"key": "DLIC1",
"type": "DLIC"
},
{
"key": "PASSPORT_FRGN1",
"type": "PASSPORT_FRGN"
},
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": ["biometry_liveness", "biometry_match"],
"relation": {"biometry_match": ["PASSPORT1", "DLIC1", "PASSPORT_FRGN1"]}
}
}
]
- variants — список вариантов: ключ шага строкой или
{"key": ..., "title": ...}. Без title показывается название документа или заголовок вложенного select. Вариант должен стоять ниже своего select и может относиться только к одному select; - view_type —
selector(кнопки, по умолчанию) илиcombobox(выпадающий список); - title — заголовок экрана, text — текст над вариантами (необязательные, HTML — см. "Текст с HTML").
Ответ — ключ выбранного варианта: "CITIZENSHIP": "RU_DOCS", "RU_DOCS": "PASSPORT1".
Пользователь может вернуться назад:
- на экране выбора — кнопка «Вернуться к предыдущему шагу», если предыдущий шаг тоже выбор или поле (к уже загруженному документу вернуться нельзя);
- на экране документа, выбранного в select, — кнопка «Вернуться к выбору». Она доступна до загрузки документа и после того, как документ забракован.
Ответы на шаги, к которым пользователь вернулся, и на все шаги после них стираются.
Флаг (checkbox)
Экран с одним флагом и текстом рядом с ним — например, согласие на обработку персональных данных или с условиями сервиса.
{
"type": "checkbox",
"key": "PD_CONSENT",
"title": "Согласие на обработку данных",
"text": "Я даю согласие на <a href=\"https://client.ru/pd.pdf\" target=\"_blank\">обработку персональных данных</a>",
"required": true
}
- text — обязательный, текст рядом с флагом (HTML, до 1000 символов);
- title — необязательный, текст над флагом (HTML, до 5000 символов);
- required — по умолчанию
true: пока флаг не установлен, пройти дальше нельзя. Приfalseфлаг можно не устанавливать.
Ответ — "PD_CONSENT": true (или false, если флаг необязательный). В событиях идентификации сохраняются текст согласия, время и IP-адрес пользователя.
Поле ввода (value)
Экран с одним полем ввода — номер договора, ИНН, дата рождения и т.д.
{
"type": "value",
"key": "CONTRACT",
"title": "Введите номер договора",
"text": "Номер указан в правом верхнем углу договора",
"masks": ["XX-XXXXXX", "AA-XXXXXX"],
"required": true
}
- masks — необязательный список масок (до 10):
X— цифра,A— буква,*— любой символ кроме пробела, остальные символы (-, пробел, скобки) подставляются автоматически. Значение сохраняется в формате маски. Без масок — любой текст до 256 символов; - title — заголовок поля (по умолчанию «Введите значение»), text — текст над полем (HTML);
- required — по умолчанию
true.
Типовые поля. Для распространенных данных маска и проверка уже заданы — достаточно указать preset (masks в этом случае не указываются):
{"type": "value", "key": "INN", "preset": "inn"}
{"type": "value", "key": "SNILS", "preset": "snils"}
{"type": "value", "key": "PHONE", "preset": "phone", "countries": ["RU", "KZ"]}
{"type": "value", "key": "EMAIL", "preset": "email"}
{"type": "value", "key": "BIRTH_DATE", "preset": "date", "date_format": "DD.MM.YYYY"}
| preset | Что проверяется | Пример ответа |
|---|---|---|
inn |
10 или 12 цифр, контрольные числа | "7707083893" |
snils |
формат XXX-XXX-XXX XX, контрольное число |
"112-233-445 95" |
phone |
номер по маске выбранной страны | "+79123456789" |
email |
адрес электронной почты | "user@client.ru" |
date |
существование даты в формате date_format | "05.03.1990" |
- phone: без ограничений доступны все страны (сначала Россия и СНГ).
countries— только указанные страны (коды ISO, первая выбрана по умолчанию),exclude_countries— все, кроме указанных. Вместе их указывать нельзя; - date:
date_format— формат даты, по умолчаниюDD.MM.YYYY.DD— день,MM— месяц,YYYYилиYY— год, остальное — разделители. Части можно менять местами и пропускать:YYYY-MM-DD,DD.MM,MM/YY.
title у типовых полей необязательный («Введите ИНН», «Введите СНИЛС», «Введите номер телефона»).
Подтверждение телефона кодом
Для поля preset: "phone" можно включить подтверждение: пользователь получает шестизначный код и вводит его на странице. Ответ на поле сохраняется только после ввода верного кода.
{
"type": "value",
"key": "PHONE",
"preset": "phone",
"countries": ["RU"],
"confirmation": "sms",
"attempts": 3,
"sms_text": "Ваш код: {code}"
}
{
"type": "value",
"key": "PHONE",
"preset": "phone",
"confirmation": "telegram",
"attempts": 3
}
- confirmation — способ отправки кода:
sms— СМС,telegram— сообщение в Telegram (пользователю не нужно запускать бота). Без confirmation значение принимается без подтверждения; - attempts — сколько всего раз можно ввести неверный код. Когда попытки исчерпаны, идентификация завершается неуспешно (
done_state: false). Без attempts ограничение действует только на один код; - sms_text — свой текст СМС (только для
sms).{code}указывается ровно один раз и заменяется кодом; вместе с кодом — до 70 символов. По умолчанию: «Код подтверждения: 123456. Никому его не сообщайте».
Код действует 5 минут, на один код — 5 попыток ввода. Повторно отправить код можно через 60 секунд, всего — до 5 отправок на поле. Пользователь может изменить номер и получить новый код.
⚠️ Важно: отправка кода оплачивается с баланса. Перед отправкой проверяется, хватает ли средств, — если нет, код не отправляется, а пользователю показывается «Недостаточно средств. Обратитесь к администратору». Списание — только за отправленные коды
Выбор документа (document_choice)
Упрощенный вариант выбора документа: варианты описываются прямо в шаге. Выбранный документ запрашивается следующим шагом, остальные не запрашиваются.
{
"key": "MAIN_DOC",
"kind": "document_choice",
"label": "Выберите основной документ",
"options": [
{"key": "PASSPORT1", "type": "PASSPORT"},
{"key": "DLIC1", "type": "DLIC"}
]
}
Ответ — ключ выбранного документа: "MAIN_DOC": "DLIC1".
Кнопка на экране завершения
Необязательный параметр запроса создания (рядом с process_info, работает и при создании по пресету). После завершения идентификации — успешного или нет — под результатом показывается кнопка, которая переводит пользователя по указанному адресу, например обратно в личный кабинет.
{
"project_id": "U_RATE_3",
"machine_uid": "<machine_uid>",
"token": "token",
"process_info": [...],
"finish_button": {"text": "Вернуться в личный кабинет", "url": "https://<ваш сайт>"}
}
- text — надпись на кнопке, обычный текст до 64 символов;
- url — адрес перехода, только
http://илиhttps://, до 2048 символов.
Без finish_button на экране завершения показывается текст «Идентификация завершена вернитесь в личный кабинет».
⚠️ Важно: при встраивании через iframe переход по кнопке открывается внутри iframe
Получение результатов
Структура запроса:
url: https://webapp.beorg.ru/kyc/get_result
method: GET
headers:
Content-Type: application/json
query_params: token, user_token, return_images
⚠️ Важно: Если Вам необходимо получить помимо данных о физическом лице еще и изображения - укажите параметр return_images со значением true
Структура ответа:
{
"done_state": статус обработки (true - завершено корректно, false - завершено некорректно, null - не завершена),
"user_token": уникальный идентификатор пользователя,
"client_user_token": идентификатор со стороны заказчика,
"set_id": идентификатор комплекта документов пользователя,
"data": результат обработки данных,
"additional_data": ответы пользователя на шаги сценария (select, checkbox, value) по ключам шагов,
"images": изображения по каждому документу, вернется если в параметрах запроса указан return_images со значением true
}
Пример additional_data:
"additional_data": {
"CITIZENSHIP": "RU_DOCS",
"RU_DOCS": "PASSPORT1",
"PD_CONSENT": true,
"PHONE": "+79123456789",
"BIRTH_DATE": "05.03.1990"
}
Пока ответов нет — {}. Телефон с подтверждением попадает сюда только после ввода верного кода. Если пользователь возвращался назад, здесь — ответы того пути, который он прошел в итоге. Подробнее о шагах — "Сценарий идентификации".
Пример запроса
Python
import requests
r = requests.get("https://webapp.beorg.ru/kyc/get_result?token={token}&user_token={user_token}")
r.json()
Для получения token обратитесь в подраздел "Начало работы"
Получение статистики по идентификации
Структура запроса:
url: https://webapp.beorg.ru/kyc/stats
method: GET
headers:
Content-Type: application/json
query_params: token, user_token
Структура ответа:
{
"done_state": статус обработки (true - завершено корректно, false - завершено некорректно, null - не завершена),
"user_token": уникальный идентификатор пользователя,
"client_user_token": идентификатор со стороны заказчика,
"events": [события по идентификации],
"master_set": центральный комплект пользователя,
"sets": [все комплекты пользователя],
"uploaded_docs": [информация о загруженных документах],
"link": ссылка на идентификацию,
"qr_code": строка-изображение QR-кода
}
Пример запроса
Python
import requests
r = requests.get("https://webapp.beorg.ru/kyc/stats?user_token={user_token}&token={token}")
r.json()
Принудительное изменение статуса идентификации
Структура запроса:
url: https://webapp.beorg.ru/kyc/set_done_status
method: POST
headers:
Content-Type: application/json
body:
{
"token": "token",
"user_token": "уникальный идентификатор пользователя",
"status": true - завершено корректно, false - завершено некорректно, null - не завершена,
"data": {
"initiator": "свободный необязательный ключ, инициатор изменения"
},
"client_user_token": "идентификатор со стороны заказчика, может использоваться вместо user_token",
}
Структура ответа:
{
"status": true/false - статус выполнения запроса,
"done_state": установленный статус обработки (
true - завершено корректно,
false - завершено некорректно,
null - не завершена
),
}
Для получения token обратитесь в подраздел "Начало работы"
Пример запроса
Python
import requests
r = requests.post(f"https://webapp.beorg.ru/kyc/set_done_status", json = {
"token": "token",
"user_token": "уникальный идентификатор пользователя",
"status": True,
"data": {
"initiator": "Иванов Иван Иванович"
},
})
r.json()
Принудительное бракование документа
Для получения типов и ключей загруженных документов воспользуйтесь методом "Получение статистики по идентификации"
Структура запроса:
url: https://webapp.beorg.ru/kyc/set_doc_broken
method: POST
headers:
Content-Type: application/json
body:
{
"token": "token",
"document_type": "тип документа из загруженных",
"document_key": "ключ документа из загруженных",
"user_token": "уникальный идентификатор пользователя",
"comment": "cвободный комментарий, который будет отображен пользователю",
"data": {
"initiator": "свободный необязательный ключ, инициатор изменения"
},
"client_user_token": "идентификатор со стороны заказчика, может использоваться вместо user_token"
}
Структура ответа:
{
"status": true/false - статус выполнения запроса
}
Для получения token обратитесь в подраздел "Начало работы"
Пример запроса
Python
import requests
r = requests.post(f"https://webapp.beorg.ru/kyc/set_doc_broken", json = {
"token": "token",
"user_token": "уникальный идентификатор пользователя",
"document_type": "тип документа из загруженных",
"document_key": "ключ документа из загруженных",
"comment": "В этом документе не видно...",
"data": {
"initiator": "Иванов Иван Иванович"
},
})
r.json()
WebApp
Web-интерфейс предназначен для взаимодействия с конечным пользователем. Он предоставляет интуитивно понятный процесс загрузки документов с пошаговыми инструкциями и обратной связью.
Создание идентификации WebApp:
Первым делом сервер вашего приложения отправляет запрос к API Beorg для создания ссылки. В ответе приходит — уникальная ссылка для пользователя.
Пример запроса
url: https://webapp.beorg.ru/kyc/create
method: POST
headers:
Content-Type: application/json
body:
{
"project_id": "U_RATE_3",
"machine_uid": "<machine_uid>",
"token": "token",
"process_info": [
настройки обработки
],
"client_user_token": "внешний id (идентификатор со стороны заказчика, необязательный)",
"expires": кол-во секунд действия ссылки (необязательный, при отсутствии ссылка бессрочная)
}
Структура ответа:
{
"status": true/false статус выполнения запроса,
"error": описание ошибки (если имеется),
"link": постоянная уникальная ссылка на идентификацию,
"user_token": уникальный идентификатор пользователя,
"client_user_token": идентификатор со стороны заказчика,
"qr_code": строка-изображение QR-кода
}
Отображение интерфейса
Интерфейс может быть отображен на стороне клиента несколькими путями:
- Отдельной вкладкой в браузере на ПK (прямая ссылка)
Пользователь переходит по сгенерированной ссылке в любом браузере (десктопном или мобильном). Допустимо добавление параметра theme для принудительной установки темы оформления: &theme=light или &theme=dark.
https://webapp.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>
client_key=<уникальный идентификатор заказчика>
- Отдельной вкладкой в браузере на смартфоне
https://webapp.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>
client_key=<уникальный идентификатор заказчика>&theme=light/dark
Параметр theme указывает какую цветовую тему отображать - светлую или темную, является необязательным, если не указан - устанавливается тема из настроек браузера
- Размещением в качестве HTML-тега на сайте/приложении (iframe-встраивание)
<iframe width="400px" height="600px" allow="camera" src="https://webapp.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>&
client_key=<уникальный идентификатор заказчика>&theme=light/dark">
</iframe>
Процесс прохождения пользователем
Пользователь последовательно загружает документы в соответствии с конфигурацией process_info. Интерфейс предоставляет наглядные подсказки для корректного кадрирования документа. В случае неудовлетворительного качества загруженного изображения (блики, размытие, неполное попадание в кадр) пользователь получает уведомление с указанием причины и предложением повторить попытку, если лимит попыток не исчерпан.
Интерфейс лаконичен и ведет пользователя "за руку" при использовании. На каждом этапе пользователю отображаются соответствующие интуитивные подсказки позволяющие ему корректно пройти идентификацию.
Ниже представлен процесс прохождения идентификации по стандартному сценарию: Паспорт гражданина РФ (2 и 3 страницы) + селфи.
Сценарий обработки можно выбрать из описания https://docs.beorg.ru/api_docs/kyc/scenarios/. При загрузке документа пользователю отображается куда необходимо нажать, чтобы сделать фото:

Протестировать работу Web-интерфейса можно в разделе "KYC"
Получение результатов верификации
После завершения пользователем всех этапов, либо исчерпания попыток сервер Заказчика может запросить итоговые данные.
При завершении идентификации пользователю отображается соответствующее уведомление

При некорректном документе пользователю отображается обратная связь с причинами брака документа

Получение статистики по идентификации
Структура запроса:
url: https://webapp.beorg.ru/kyc/stats
method: GET
headers:
Content-Type: application/json
query_params: token, user_token
Структура ответа:
{
"done_state": статус обработки (true - завершено корректно, false - завершено некорректно, null - не завершена),
"user_token": уникальный идентификатор пользователя,
"client_user_token": идентификатор со стороны заказчика,
"events": [события по идентификации],
"master_set": центральный комплект пользователя,
"sets": [все комплекты пользователя],
"uploaded_docs": [информация о загруженных документах],
"link": ссылка на идентификацию,
"qr_code": строка-изображение QR-кода
}
Пример запроса
Python
import requests
r = requests.get("https://webapp.beorg.ru/kyc/stats?user_token={user_token}&token={token}")
r.json()
Пример использования другого типа документа в процессе идентификации
Для выбора иного типа документа, участвующего в процессе идентификации, необходимо внести правки в структуру отправляемого запроса. Конфигурация указывает какие изображения связаны между собой, какие опции используются при обработке, а также к какому конкретно типу и сущности относятся изображения при обработке.
Указывается в формате:
"process_info": [
{
"type": "<тип>",
"key": "<свободный ключ>",
"options": {опции при обработке}
},
{
"type": "<тип>",
"key": "<свободный ключ>",
"options": {опции при обработке}
},
...
{
"type": "<тип>",
"key": "<свободный ключ>",
"options": {опции при обработке}
}
]
Обратите внимание, что количество и порядок записей в ключе process_info должно строго соответствовать количеству записей и порядку в ключе images
Рассмотрим ключи для каждого изображения:
- type - ключ типа документа (PASPORT, PASSPORT_REG, DLIC...) Все доступные ключи документов можно уточнить в таблицах в разделах Тариф Биорг.KYC
- key - свободный ключ (можете указать любое строковое значение) для того, чтобы связать 2 и более изображений в одну сущность/документ
- options - опции при обработке документа Все доступные опции описаны в разделах Сценарии обработки (Биорг.KYC)
Пример запроса для ву
import requests
r = requests.post(
"https://webapp.beorg.ru/kyc/create",
headers={"Content-Type": "application/json"},
json={
"project_id": project_id,
"token": token,
"machine_uid": machine_uid,
"process_info": [
{
"key": "SELFIE1",
"type": "SELFIE",
"options": {
"stages": [
"biometry_liveness",
],
},
"attempts": 3, # 3 попытки
},
{
"key": "DLIC1",
"type": "DLIC",
"options": {
"stages": [
"verification",
"biometry_match",
],
"relation": {
"biometry_match": "SELFIE1",
},
}
"attempts": 3, # 3 попытки
},
],
"expires": 3600 # срок действия идентификации (3600 секунд = 1 час)
},
)
QR-код
Для быстрого и удобного переноса процесса идентификации с десктопной версии на мобильное устройство в интерфейс встроен QR-код. Данный функционал поможет пользователю сделать качественные фото документов с помощью камеры смартфона.
При создании новой идентификации в ответе сервера возвращается поле QR-code. Строка в поле QR-code представляет собой сгенерированное QR-изображение, которое вы можете сразу отобразить пользователю.
Действие QR-кода длится столько же сколько обозначено время жизни ссылки для идентификации.
В случае, когда QR-код стал неактивным, необходимо создать новый запрос на процедуру идентификации по сценариям, описанным выше.
