Flow Widget

Описание#

Flow Widget - это способ интеграции сервиса биометрии в веб-приложение клиентской стороны с использованием готового решения в виде JavaScript библиотеки.

Использование данного способа интеграции предполагает получение сессии по созданному flow и последующее перенаправление конечного пользователя на наш сервер.

Ниже более подробно описаны все этапы подключения. Также вы можете скачать полный пример.

Примечание

В текущей версии документации рассматривается подключение виджета в HTML страницу.

Этапы:#

1. Создание Flow#

Первым делом необходимо создать Flow в личном кабинете. Для этого перейдите по данной ссылке.

После того, как flow будет создан необходимо воспользоваться его API KEY на втором этапе. Найти API KEY можно на странице со списком созданных флоу.

Упрощенный пример таблицы flows личного кабинета:

Наименование флоу	API KEY	Технологии
Флоу для всех	TTpme201NiUMBA...	LD, F2F
Флоу для физ. лиц	Efy202XKbVAWRu...	LD, ED, F2F
Флоу для юр. лиц	UuuH4V1XC-M9je...	LD, DR, F2F

Примечание

В последующих примерах будет использоваться первый флоу из таблицы выше: "Флоу для всех".

Также, для наглядности используется укороченная длина API KEY. Его фактическая длина состовляет 47 и более символов.

2. Создание Сессии#

Для работы с сервисом нужно создать сессию. Для этого необходимо отправить POST-запрос на создание сессии используя API KEY созданного flow. Подробнее про сессии можно прочитать здесь.

В запросах к нашему сервису используются только данные в формате JSON. Ответные данные от сервиса будут представлены в том же формате.

URL запроса:

https://kyc.biometric.kz/api/v1/flows/session/create/

Формат запроса	Метод запроса
JSON	POST

API KEY необходимо передать в теле запроса:

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY созданного flow в личном кабинете

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

cURLPythonJavaScriptTypeScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
"api_key": "YOUR_FLOW_API_KEY"
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
  "api_key": "YOUR_FLOW_API_KEY",
})
headers = {
  'Content-Type': 'application/json',
}

response = requests.request(
  "POST",
  url=url,
  headers=headers,
  data=payload,
)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY' // flow api key

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    body: JSON.stringify({
        api_key: apiKey
    })
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies } = data
})

const apiKey: string = 'YOUR_FLOW_API_KEY' // flow api key

interface SessionResponseData {
    session_id: string,
    technologies: string[]
}

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    body: JSON.stringify({
        api_key: apiKey
    })
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies }: SessionResponseData = data
})

В качестве ответа придет JSON со следующими полями:

session_id - одноразовый идентификатор сессии для прохождения flow;
technologies - упорядоченный набор технологий flow.

Пример ответа:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "F2F"]
}

3. Метаданные Сессии#

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

API KEY и metadata необходимо передать в теле запроса. Значением для metadata является объект который включает в себя объект c названием технологии (face2face, edocument) состоящий из метаданных для технологии.

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY созданного flow в личном кабинете
metadata		Нет	Метаданные сесии

Метаданные для технологии Face2Face:

Наименование поля	Тип	Обязательно	Описание
face2face		Нет	Метаданные для технологии Face2Face
photo1	String	Нет	Фотография, используемая для сличения в формате base64

Метаданные для технологии E-Document:

Наименование поля	Тип	Обязательно	Описание
edocument		Нет	Метаданные для технологии E-Document
iin		Нет	Поле ИИН
phone		Нет	Поле Телефона субъекта
value	String	Нет	Значение полей
changeable	Boolean	Нет	Возможность изменить данные пользователем
skip_input	Boolean	Нет	Пропустить ввод данных пользователем (Перейти на шаг ввода OTP-кода)

Общие метаданные:

Наименование поля	Тип	Обязательно	Описание
general		Нет	Общие метаданные
interchangeable_tech	Array	Нет	Список взаимозаменяемых технологий

Примечание

Если метаданные отсутствуют, то флоу будет протекать по умолчанию.

3.1. Метаданные для Face2Face#

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

Необходимо учесть

Метаданные технологии Face2Face будут работать только для следующих флоу:

Liveness + Face2Face
E-Docuemnt + Face2Face
Document Recognition + Face2Face

Наименование поля	Тип	Обязательно	Описание
face2face		Нет	Метаданные для технологии Face2Face
photo1	String	Нет	Фотография, используемая для сличения в формате base64

URL запроса:

https://kyc.biometric.kz/api/v1/flows/session/create/

Формат запроса	Метод запроса
JSON	POST

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

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "face2face": {
            "photo1": "base64"
        }
    }
}'

import requests
import json
import base64

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

with open('path/to/your/image.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "face2face": {
            "photo1": encoded_image,
        },
    },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY';
const imageFilePath = 'path/to/your/image.jpg'; // Путь к вашему изображению

const fs = require('fs');
const path = require('path');

const imageBase64 = fs.readFileSync(path.resolve(imageFilePath), { encoding: 'base64' });

const payload = {
    api_key: apiKey,
    metadata: {
        face2face: {
            photo1: imageBase64
        }
    }
};

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
    const { session_id, technologies } = data;
})

В качестве ответа придет JSON со следующими полями:

session_id - одноразовый идентификатор сессии для прохождения flow;
technologies - упорядоченный набор технологий flow.

Пример ответа:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "F2F"]
}

3.2. Метаданные для E-Document#

При наличии таких данных о пользователе, как ИИН, номер телефона, наличие в Базе Мобильных Граждан. Есть возможность передать их на форму ввода при прохождении технологии EDocument. Это позволяет упростить и сократить процесс верификации и предотвратить ошибки, которые могли бы возникнуть при вводе данных пользователем. Необходимо передавать в теле запроса поле metadata.

Примечание

Поле skip_input по умолчанию имеет значение false. (Шаг ввода данных не пропускается) Поле changeable по умолчанию имеет значение true. (Пользователь может изменить значения поля ввода данных)

Наименование поля	Тип	Обязательно	Описание
edocument		Нет	Метаданные для технологии E-Document
iin		Нет	Поле ИИН
phone		Нет	Поле Телефона субъекта
value	String	Нет	Значение полей
changeable	Boolean	Нет	Возможность изменить данные пользователем
skip_input	Boolean	Нет	Пропустить ввод данных пользователем

URL запроса:

https://kyc.biometric.kz/api/v1/flows/session/create/

Формат запроса	Метод запроса
JSON	POST

Case №1:

Примечание

Пропустить шаг ввода данных для пользователя, возможно только если:
1) Был передан value для iin и phone
2) Был передан changeable для iin и phone со значением false
3) Был передан skip_input со значением true

У пользователя будет пропущен шаг ввода данных. Пользователь будет перенаправлен на шаг ввода OTP-кода от 1414.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": false,
            },
            "phone": {
                "value": "<subjects_phone>",
                "changeable": false,
            },
            "skip_input": true
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": False,
            },
            "phone": {
                "value": "<subjects_phone>",
                "changeable": False,
            },
            "skip_input": True
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY'; // Ключ API вашего процесса
const subjectsIIN = '123456789012'; // Пример ИИН пользователя
const subjectsPhone = '+1234567890'; // Пример номера телефона пользователя

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                    changeable: false,
                },
                phone: {
                    value: subjectsPhone,
                    changeable: false,
                },
                skip_input: true
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })

Case №2:

У пользователя на шаге ввода данных в полях ввода будут значения переданные в metadata, без возможности изменить ИИН.

Примечание

У changeable по умолчанию значение true.
У skip_input по умолчанию значение false.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": false,
            },
            "phone": {
                "value": "<subjects_phone>",
            }
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
                "changeable": False,
            },
            "phone": {
                "value": "<subjects_phone>",
            },
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY'; // Ключ API вашего процесса
const subjectsIIN = '123456789012'; // Пример ИИН пользователя
const subjectsPhone = '+1234567890'; // Пример номера телефона пользователя

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                    changeable: false,
                },
                phone: {
                    value: subjectsPhone,
                }
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })

Case №3:

У пользователя на шаге ввода данных в полях ввода будут значения переданные в metadata, есть возможность изменить ИИН и номер телефона.

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/flows/session/create/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
            },
            "phone": {
                "value": "<subjects_phone>",
            }
        }
    }
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/flows/session/create/"

payload = json.dumps({
    "api_key": "YOUR_FLOW_API_KEY",
    "metadata": {
        "edocument": {
            "iin": {
                "value": "<subjects_iin>",
            },
            "phone": {
                "value": "<subjects_phone>",
            },
        },
})

headers = {
    'Content-Type': 'application/json',
}

response = requests.post(url=url, headers=headers, data=payload)

print(response.json())

const apiKey = 'YOUR_FLOW_API_KEY'; // Ключ API вашего процесса
const subjectsIIN = '123456789012'; // Пример ИИН пользователя
const subjectsPhone = '+1234567890'; // Пример номера телефона пользователя

fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        api_key: apiKey,
        metadata: {
            edocument: {
                iin: {
                    value: subjectsIIN,
                },
                phone: {
                    value: subjectsPhone,
                }
            }
        }
    })
})
    .then(response => response.json())
    .then(data => {
        const { session_id, technologies } = data;
    })

В качестве ответа придет JSON со следующими полями:

session_id - одноразовый идентификатор сессии для прохождения flow;
technologies - упорядоченный набор технологий flow.

Пример ответа:

{
  "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "technologies": ["LDHP", "ED", "F2F"]
}

4. Интеграция виджета в веб-приложение#

После успешного создания flow и генерации session_id необходимо интегрировать готовый widget в веб-приложение клиентской стороны. Интеграция виджета состоит из следующих этапов:

4.1 Создание контейнера для виджета в веб-приложении#

Необходимо создать контейнер, внутрь которого будет встраиваться генерируемая HTML структура виджета. У контейнера должен существовать атрибут id с уникальным значением.

Внутри приложения будут использоваться стили, которые отталкиваются от высоты и ширины контейнера. Для корректного отображения создайте дополнительный контейнер, в котором будет помещаться само приложение.

Важно

Для родительского контейнера обязательно нужно задать ширину и высоту (не max-width/max-height, а именно height и width). Для контейнера самого приложения стоит задать стили высоты и ширины 100%, а так же относительное позиционирование (смотреть пример ниже)

Пример:

.flow-widget-container {
    width: 400px;
    height: 600px;
}
#flow-widget {
    width: 100%;
    height: 100%;
    position: relative;
}

<div class="flow-widget-container">
    <div id="flow-widget"></div>
</div>

4.2 Подгрузка виджета в веб-приложении#

Для подгрузки JavaScript файла в веб-приложение необходимо добавить HTML тег script.

Тег script должен содержать в себе атрибут type со значем module и атрибут src, который будет содержать в себе URL из которого будет подгружаться JavaScript файл.

На текущий момент файл необходимо подгружать по следующему URL https://remote.biometric.kz/widget/flow-widget.js

Пример:

<script type="module" src="https://remote.biometric.kz/widget/flow-widget.umd.js"></script>

4.3 Запуск процесса верификации в веб-приложении#

При необходимости запуска процесса верификации необходимо вызвать метод startSession из библиотеки FlowWidget.

Так как в текущем примере рассматривается подключение в HTML страницу, то для запуска процесса верификации нужно будет добавить еще один HTML тег script с указанием атрибута type со значением module.

Метод startSession принимает в себя объект конфигурации, в которым есть следующие обязательные поля:

Наименование поля	Тип принимаего значения	Описание
*session_id*	string	Уникальный идентификатор сессии получаемый с сервера
*selector*	string	Идентификатор HTML конейтнера в котором будет генерироваться виджет
*locale*	string	Язык в котором должен запуститься виджет, на данный момент реализованы языки: ru, en, kz

Пример:

<script type="module">
    FlowWidget.startSession({
      id: '<session_id>', 
      selector: '#flow-widget', 
      locale: 'ru'
    })
</script>

4.4 Отлавливание завершения работы виджета#

По окончанию своей работы виджет триггерит событие с названием finish, в котором так же будут переданы данные собранные forntend частью данного виджета через поле detail объекта data. Для отлавливания данного события стоит добавить следующий код:

<script type="module">
    window.addEventListener('finish', (data) => {
        console.dir(data.detail)
    })
</script>

В качестве примера мы вывели в консоль полученные данные, вы же в своем случае можете отработать данные по полученной сессии отправив запрос на результат.

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

Получить общий результат по сессий можно отправив GET запрос на специальный URL передав в параметрах идентификатор сессии:

URL запроса:

https://kyc.biometric.kz/api/v1/flows/session/result/

Формат запроса	Метод запроса
JSON	GET

session_id необходимо передать в параметрах запроса:

Параметр	Тип	Обязательно	Описание
session_id	String	Да	Идентификатор flow сессии
flow_api_key	String	Да	API KEY созданного flow в личном кабинете который использовался при создании сессии

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

cURLPython

curl --location --request GET 'https://kyc.biometric.kz/api/v1/flows/session/result/?session_id=<session_id>&flow_api_key=<flow_api_key>'

import requests

url = "https://kyc.biometric.kz/api/v1/flows/session/result/"

params = {
  'session_id': '<session_id>',
  'flow_api_key': '<flow_api_key>,
}

response = requests.request(
  "GET",
  url=url,
  params=params,
)

print(response.json())

В качестве ответа придет JSON со следующими полями:

id - идентификатор сессии;
technologies - упорядоченный набор технологий в соответствии с созданным флоу;
liveness_result - результат прохождения Liveness;
document_recognition_result - результат прохождения Document Recognition;
face2face_result - результат прохождения Face2face.
edocument_result - результат прохождения Edocument.

Важно

Поля liveness_result, document_recognition_result, face2face_result, edocument_result отображаются только в том случае, если клиент прошел эти технологии во время Flow.

Пример ответа:

{
  "id": "session_id",
  "technologies": [
    {
      "name": "Document Recognition",
      "description": "Parse document data from image"
    }
  ],
  "document_recognition_result": {
    "first_name": "First",
    "last_name": "Last",
    "patronymic": "Patronymic",
    "personal_number": "pers_number",
    "date_of_birth": "01.01.2000",
    "document_number": "doc_number",
    "authority": "authority"
    ...

Итоговый пример подключения#

<div id="flow-widget"></div>
<script type="module" src="https://remote.biometric.kz/widget/flow-widget.umd.js"></script>
<script type="module">
  FlowWidget.startSession({
    id: '2569aadc-9ff2-4da3-a1c8-44057520e1d6',
    selector: '#flow-widget',
    locale: 'ru'
  })
  window.addEventListener('finish', (data) => {
      console.dir(data.detail)
  })
</script>