Перейти к содержанию

API KYC + WEBApp

Основные составляющие системы

  1. API - интерфейс программного взаимодействия. Используется сервером Заказчика для создания запросов на верификацию, получения результатов и управления статусами проверок

  2. WEB-интерфейс пользователя - клиентская часть приложения. Предназначена для загрузки фотографий документов и прохождения проверок непосредственно пользователем

  3. Личный кабинет - панель административного управления. Позволяет сотрудникам Заказчика в режиме реального времени отслеживать ход проверок, просматривать результаты и при необходимости корректировать статусы вручную.

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",
        ],
    },
},


Получение результатов

Структура запроса:

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": результат обработки данных
  "images": изображения по каждому документу, вернется если в параметрах запроса указан return_images со значением true
}

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

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-кода
}

Отображение интерфейса

Интерфейс может быть отображен на стороне клиента несколькими путями:

  1. Отдельной вкладкой в браузере на ПK (прямая ссылка)

Пользователь переходит по сгенерированной ссылке в любом браузере (десктопном или мобильном). Допустимо добавление параметра theme для принудительной установки темы оформления: &theme=light или &theme=dark.

https://webapp.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>
client_key=<уникальный идентификатор заказчика>
  1. Отдельной вкладкой в браузере на смартфоне
https://webapp.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>
client_key=<уникальный идентификатор заказчика>&theme=light/dark

Параметр theme указывает какую цветовую тему отображать - светлую или темную, является необязательным, если не указан - устанавливается тема из настроек браузера

  1. Размещением в качестве 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-код стал неактивным, необходимо создать новый запрос на процедуру идентификации по сценариям, описанным выше.