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

Описание API KYC + WEBApp

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

  1. API

    Система управления идентификациями и получения информации об идентификациях c Вашей стороны

  2. WEB-интерфейс пользователя

    Используется для загрузки изображений документов Вашими клиентами

  3. Личный кабинет

    Используется для отображения и управления в реальном времени процессов идентификации, поиска персональных данных

API

Схема работы с API

Запрос на создание идентификации 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": "идентификатор со стороны заказчика (необязательный)"
}

Структура ответа:

{
    "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
}

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

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",
                    ],
                },
            },
            {
                "key": "PASSPORT1",
                "type": "PASSPORT",
                "options": {
                    "stages": [
                        "verification",
                        "biometry_match",
                    ],
                    "relation": {
                        "biometry_match": "SELFIE1",
                    },
                }
            },

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

Структура ответа:

{
  "done_state": статус обработки (true - завершено корректно, false - завершено некорректно, null - не завершена),
  "user_token": уникальный идентификатор пользователя,
  "client_user_token": идентификатор со стороны заказчика,
  "set_id": идентификатор комплекта документов пользователя,
  "data": результат обработки данных
}

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

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_done_status", json = {
    "token": "token",
    "user_token": "уникальный идентификатор пользователя",
    "document_type": "тип документа из загруженых",
    "document_key": "ключ документа из загруженых",
    "comment": "В этом документе не видно...",
    "data": {
        "initiator": "Иванов Иван Иванович"
    },
})

r.json()

WEB-интерфейс пользователя

Интерфейс предназначен для загрузки изображений документов со стороны Вашего клиента.

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

  1. Отдельной вкладкой в браузере на ПК

    по прямой ссылке: 

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

  1. Отдельной вкладкой в браузере на смартфоне

    по прямой ссылке: 

https://webapp.kyc.beorg.ru/kyc?
token=<уникальный идентификатор пользователя>&
client_key=<уникальный идентификатор заказчика>
  1. Размещением в качестве HTML-тега на сайте/приложении
<iframe width="400px" height="600px" allow="camera" src="<ссылка>">
</iframe>

Протестировать работу Web-интерфейса можно в разделе "KYC"

Интерфейс лаконичен и ведет пользователя "за руку" при использовании. На каждом этапе пользователю отображаются соотвествующие интуитивные подсказки позволяющие ему корректно пройти идентификацию.


При загрузке документа пользователю отображается куда необходимо нажать, чтобы сделать фото:


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


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

Также для упрощения перехода между ПК и мобильным устройством интерфейс встроен QR-код.