Flow Remote

Flow Remote API

Flow Remote API - это способ подключения модулей биометрии с использованием frontend-клиента от Biometric.Vision.

Frontend - это интерфейс, с которым взаимодействует пользователь. В случае с сайтом, его формирует и выводит на экран браузер, который работает на HTML, CSS и JavaScript.

Данный способ интеграции предполагает получение сессии по созданному флоу и последующее перенаправление пользователя на frontend-клиент Biometric.Vision.

Набор инструментов разработки для Android можно найти здесь.

---

Этапы:

1. Создание 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.

Сессия - это период времени, в течение которого пользователь взаимодействует с системой или программным приложением. Во время сессии пользователь может выполнять различные операции, вводить данные, просматривать информацию и использовать функциональность системы. Система сохраняет информацию о действиях пользователя, чтобы обеспечить последовательность и согласованность операций.

Время жизни сессии при прохождении биометрической проверки - не более 10 минут.

В запросах к нашему сервису используются только данные в формате 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"]
}

Также, необходимо указать метод биометрии в качестве URL-пути.

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. Перенаправление конечного пользователя

В результате выполнения предыдущих этапов должен быть получен идентификатор сессии - session_id. Теперь необходимо перенаправить конечного пользователя на наш frontend-клиент. Чтобы это сделать, нужно сформировать следующий URL:

https://remote.biometric.kz/flow/<session_id>

JavaScriptTypeScript

const session_id = '<session_id>'
const url = 'https://remote.biometric.kz/flow/' + session_id
window.open(url, '_blank')

const session_id: string = '<session_id>'
const url: string = 'https://remote.biometric.kz/flow/' + session_id
window.open(url, '_blank')

Также, вы можете объявить следующие параметры адресной строки:

• redirect - адрес на который произойдет редирект после прохождения технологий;
• locale - язык по умолчанию. ['ru', 'en'];

Пример:

https://remote.biometric.kz/flow/<session_id>?redirect=https://example.com/&locale=ru  

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

Код технологии	Описание
LD	Определение живости человека по лицу
F2F	Определение схожести двух лиц по фото

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"
    ...

6. Получение видео прохождения проверки

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

URL запроса:

https://kyc.biometric.kz/api/v1/liveness/video/download/

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

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

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

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

cURLPythonJavaScript

curl --location --request GET 'https://kyc.biometric.kz/api/v1/liveness/video/download/?session_id=<session_id>&flow_api_key=<flow_api_key>'

import requests

url = "https://kyc.biometric.kz/api/v1/liveness/video/download/"
params = {
    'session_id': "<session_id>",
    'flow_api_key': "<flow_api_key>",
}
response = requests.request(
    "GET", 
    url=url, 
    params=params,
)

fetch("https://kyc.biometric.kz/api/v1/liveness/video/download/?session_id=<session_id>&flow_api_key=<flow_api_key>")
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));

Полный пример

Готовый пример по запуску Flow remote может быть скачан здесь.