Flow WebView

Описание#

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

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

Примечание

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

Этапы:#

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. Интеграция в приложение#

Ниже приведен отрывок кода для инициализации Webview на Flutter. В ссылку стоит передавать query param web_view=true

Пример URL: https://remote.biometric.kz/flow/6737a660-208a-401a-a2cf-2b45a326002a?web_view=true

Сессия 6737a660-208a-401a-a2cf-2b45a326002a здесь указана лишь ради примера, в вашем случае передаете свою сессию.

Пример кода

import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: WebViewExample(),
    );
  }
}

class WebViewExample extends StatefulWidget {
  @override
  WebViewExampleState createState() => WebViewExampleState();
}

class WebViewExampleState extends State<WebViewExample> {
  late WebViewController _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('WebView Example'),
      ),
      body: WebView(
        initialUrl: 'https://remote.biometric.kz/flow/session_id',
        javascriptMode: JavascriptMode.unrestricted,
        onWebViewCreated: (WebViewController webViewController) {
          _controller = webViewController;
        },
        onPageStarted: (String url) {
          // Track the page loading start
          if (url == 'https://remote.biometric.kz/finished') {
            _showFinishedMessage();
          }
        },
      ),
    );
  }

  void _showFinishedMessage() {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
        content: Text('Process finished!'),
      ),
    );
  }
}

После выполнения всей своей логики, внутри нашего веб-приложения будет произведен редирект на страницу

https://remote.biometric.kz/finished

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