Облачное электронное подписание документов (ОЭЦП) в УЦ#
Описание#
Облачная ЭЦП — это электронно-цифровая подпись, которая хранится и используется на удалённом сервере, позволяя подписывать документы онлайн без установки дополнительных программ и без физического носителя ( токена). Подробнее тут
Термины#
- Субъект - Человек, который является объектом запроса на получение документов в электронном формате в сервисе E-Document
- OTP-код - Временный код, который приходит на телефон субъекта от 1414 и используется для подтверждения получения электронных документов
- База мобильных граждан(БМГ) - Единая база номеров мобильных телефонов пользователей, необходимых для оказания государственных услуг, отправки SMS-паролей при авторизации или подписании услуг, с помощью одноразового пароля. Найти инструкцию по регистрации в базе можно здесь
- ИИН - Индивидуальный идентификационный номер гражданина Республики Казахстан
- Unix timestamp - Система описания моментов во времени, принятая в Unix и других POSIX-совместимых операционных системах. Определяется как количество секунд, прошедших с полуночи 1 января 1970 года
- 6-значный одноразовый код - Код, полученный через Egov mobile или мобильное банковское приложение
- CMS - (Cryptograghic Message Syntax) это стандарт IETF для защищенных крипто-сообщений. Подробнее тут
- Скан копия - это копия подписанного документа, не наделённая юридической силой.
1. Создание Flow#
Первым делом необходимо создать Flow в личном кабинете. Для этого перейдите по данной ссылке. Перетащите одну из доступных технологий (DS identifier technology или DS signer technology). После добавления выбранной технологии система автоматически сформирует стандартный flow для прохождения процедуры ОЭЦП. Далее нажмите кнопку «Создать флоу» и задайте ему наименование.
После того, как вы создали свой Flow, вам необходимо воспользоваться вашим уникальным
API KEY на втором этапе. Найти API KEY можно на странице со
списком созданных Flow.
Упрощенный пример таблицы flows личного кабинета:
| Наименование Flow | API KEY | Технологии |
|---|---|---|
| Flow для ОЭЦП | TTpme201NiUMBA... | LD, F2F |
| Flow для физ. лиц | Efy202XKbVAWRu... | LD, ED, F2F |
| Flow для юр. лиц | UuuH4V1XC-M9je... | LD, DR, F2F |
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 в личном кабинете |
Примеры запроса:
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": [
"DSI",
"LDD",
"F2F",
"DSS"
]
}
Важно
Для использования функционала расширения сессии необходимо сохранить созданный session_id любым удобным способом (опционально с пометкой parent_session_id), поскольку он потребуется в дальнейшем для корректного установления связи между родительской и дочерней сессиями.
3. Метаданные Сессии#
При создании Flow можно включить определенные метаданные, которые способствуют созданию более гибкого и динамичного процесса, а также упрощают процедуру верификации.
API KEY и metadata необходимо передать в теле запроса. Значением для metadata
является объект который включает в себя объект c названием технологии (face2face, edocument)
состоящий из метаданных для технологии.
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| api_key | String | Да | API KEY созданного flow в личном кабинете |
| metadata | Нет | Метаданные сесии |
Метаданные для технологии DSI (Digital Signature Identifier):
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| iin | Нет | Поле ИИН | |
| phone | Нет | Поле Телефона субъекта, формат: 77********* |
Примечание
Если метаданные отсутствуют, то Flow будет протекать по умолчанию.
3.1. Метаданные для DSI (Digital Signature Identifier)#
При создании сессии для прохождения процессов Digital Signature, существует возможность отправки ИИН и номера телефона подписанта.
Это позволяет упростить и сократить процесс прохождения подписания документов.
Необходимо передавать в теле запроса поле metadata.
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| iin | String | Да | ИИН (Индивидуальный идентификационный номер) клиента |
| phone | String | Да | Поле Телефона субъекта, формат: 77********* |
URL запроса:
https://kyc.biometric.kz/api/v1/flows/session/create/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
Примеры запроса:
import requests
import json
import base64
url = "https://kyc.biometric.kz/api/v1/flows/session/create/"
payload = json.dumps({
"api_key": "YOUR_FLOW_API_KEY",
"metadata": {
"ds_identifier": {
"iin": "0123456789012",
"phone": "77005353535"
}
},
})
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload)
print(response.json())
const apiKey = 'YOUR_FLOW_API_KEY';
const payload = {
api_key: apiKey,
metadata: {
ds_identifier: {
iin: "0123456789012",
phone: "77005353535"
}
}
};
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": ["DSI", "LDD", "F2F", "DSS"]
}
Мультиподписание документа#
При прохождении Flow-сессии с технологией Digital Signature, возможно подписание документов несколькими пользователями. Для этого, после первого подписания необходимо выгрузить CMS-подпись документа, создать новую Flow-сессию, а затем загрузить CMS-подпись (см. этап Загрузка документов для подписания). Далее, подписание другими пользователями происходит как при обычном подписании.
4. Загрузка документов для подписания#
Важно
При использовании технологии DSS необходима загрузка файлов для подписания через api для загрузки документов."
Это должно произойти до запуска процессов DSS Technology, т.е. до этапа ввода пароля.
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| session_id | String | Да | ID Flow-сессии |
| document_type | String | Да | pdf-тип документа, установленный по умолчанию |
| document_names | String | Да | Список имен документов, загруженных для подписания |
| files | form-data file | Да | Список файлов документов, загруженных для подписания |
URL запроса:
https://kyc.biometric.kz/api/v1/digital-signature-signer/document/upload/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
Примеры запроса:
curl --location --request POST 'https://kyc.biometric.kz/api/v1/digital-signature-signer/document/upload/' \
--header 'Content-Type: multipart/form-data' \
--header 'accept: application/json' \
-F 'session_id=ad129fb1-da95-4fa5-993d-79185fe524c7' \
-F 'document_type=pdf' \
-F 'document_names=document_1' \
-F 'files=@doc_1.pdf;type=application\pdf'
import requests
url = "https://kyc.biometric.kz/api/v1/digital-signature-signer/document/upload/"
payload = {
'session_id': 'ad129fb1-da95-4fa5-993d-79185fe524c7',
'document_type': 'pdf',
'document_names': 'document_1'
}
files=[
('files',('file',open('/path/to/file','rb'),'application/octet-stream'))
]
headers = {
'Content-Type': 'application/json',
}
response = requests.post(url=url, headers=headers, data=payload, files=files)
print(response.json())
const formdata = new FormData();
formdata.append("session_id", "ad129fb1-da95-4fa5-993d-79185fe524c7");
formdata.append("document_type", "pdf");
formdata.append("document_names", "document_1");
formdata.append("files", fileInput.files[0], "file");
fetch('https://kyc.biometric.kz/api/v1/flows/session/create/', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: formdata
})
.then(response => response.json())
)
В качестве ответа придет JSON со следующими полями:
- document_name - название загруженного документа;
- document_id - id загруженного документа.
Пример ответа:
5. Перенаправление конечного пользователя#
В результате выполнения предыдущих этапов должен быть получен идентификатор
сессии - session_id. Теперь необходимо перенаправить конечного пользователя
на наш frontend-клиент. Чтобы это сделать, нужно сформировать следующий
URL:
https://remote.biometric.kz/flow/<session_id>
Также, вы можете объявить следующие параметры адресной строки:
- redirect - адрес на который произойдет редирект после прохождения технологий;
- locale - язык по умолчанию.
['ru', 'en', 'kz'];
Пример:
Далее конечный пользователь перейдет на вкладку с биометрической верификацией. В соответствии с примером, последовательно будут запускаться следующие технологии:
| Код технологии | Описание |
|---|---|
| DSI | Digital Signature Identifier |
| LDD | Определение живости человека по лицу |
| F2F | Определение схожести двух лиц по фото |
| DSS | Digital Signature Service |
6. Получение результата#
Получить общий результат по сессии можно отправив 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 в личном кабинете который использовался при создании сессии |
Примеры запроса:
Сжатие больших ответов
Для сокращения размера больших ответов рекомендуется использовать сжатие gzip.
Добавьте заголовок Accept-Encoding: gzip к вашему запросу, и сервер автоматически сожмет ответ, если его размер
превышает 200 байт.
Это особенно полезно при получении результатов с большим количеством данных или изображениями.
В качестве ответа придет JSON со следующими полями:
- id - идентификатор сессии;
- technologies - упорядоченный набор технологий в соответствии с созданным Flow;
- liveness_result - результат прохождения Liveness;
- face2face_result - результат прохождения Face2face.
- edocument_result - результат прохождения Edocument.
- ds_identifier_result - результат прохождения DS Identifier.
- ds_signer_result - результат прохождения DS Signer.
Важно
Поля liveness_result, face2face_result, edocument_result, ds_identifier_result,
ds_signer_result отображаются только в том случае,
если клиент прошел эти технологии во время Flow.
Пример ответа:
{
"id": "session_id",
"technologies": [
{
"name": "Edocument result",
"description": "Digital document"
}
],
"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",
...
6.1. Получение результата (POST)#
Получить общий результат по сессии можно отправив POST запрос на специальный URL передав в параметрах идентификатор сессии:
URL запроса:
https://kyc.biometric.kz/api/v1/flows/session/result/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
session_id необходимо передать в параметрах запроса:
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| session_id | String | Да | Идентификатор flow сессии |
| flow_api_key | String | Да | API KEY созданного flow в личном кабинете который использовался при создании сессии |
Примеры запроса:
import requests
url = "https://kyc.biometric.kz/api/v1/flows/session/result/"
payload = {
'session_id': '<session_id>',
'flow_api_key': '<flow_api_key>,
}
headers = {
'Content-Type': 'application/json',
}
response = requests.request(
"POST",
url=url,
headers=headers,
data=payload,
)
print(response.json())
Сжатие больших ответов
Для сокращения размера больших ответов рекомендуется использовать сжатие gzip.
Добавьте заголовок Accept-Encoding: gzip к вашему запросу, и сервер автоматически сожмет ответ, если его размер
превышает 200 байт.
Это особенно полезно при получении результатов с большим количеством данных или изображениями.
В качестве ответа придет JSON со следующими полями:
- id - идентификатор сессии;
- technologies - упорядоченный набор технологий в соответствии с созданным Flow;
- liveness_result - результат прохождения Liveness;
- document_recognition_result - результат прохождения Document Recognition;
- face2face_result - результат прохождения Face2face.
- edocument_result - результат прохождения Edocument.
- ds_identifier_result - результат прохождения DS Identifier.
- ds_signer_result - результат прохождения DS Signer.
Важно
Поля liveness_result, document_recognition_result, face2face_result, edocument_result, ds_identifier_result,
ds_signer_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.2. Получение результата (LIGHT)#
Получить общий результат по сессии можно отправив GET запрос на специальный URL передав в параметрах идентификатор сессии:
URL запроса:
https://kyc.biometric.kz/api/v1/flows/session/result/light/
| Формат запроса | Метод запроса |
|---|---|
| JSON | GET |
session_id необходимо передать в параметрах запроса:
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| session_id | String | Да | Идентификатор flow сессии |
| flow_api_key | String | Да | API KEY созданного flow в личном кабинете который использовался при создании сессии |
Примеры запроса:
Сжатие больших ответов
Для сокращения размера больших ответов рекомендуется использовать сжатие gzip.
Добавьте заголовок Accept-Encoding: gzip к вашему запросу, и сервер автоматически сожмет ответ, если его размер
превышает 200 байт.
Это особенно полезно при получении результатов с большим количеством данных или изображениями.
В качестве ответа придет JSON со следующими полями:
- id - идентификатор сессии;
- technologies - упорядоченный набор технологий в соответствии с созданным Flow;
- liveness_result - результат прохождения Liveness;
- document_recognition_result - результат прохождения Document Recognition;
- face2face_result - результат прохождения Face2face.
- edocument_result - результат прохождения Edocument.
- ds_identifier_result - результат прохождения DS Identifier.
- ds_signer_result - результат прохождения DS Signer.
Важно
Поля liveness_result, document_recognition_result, face2face_result, edocument_result, ds_identifier_result,
ds_signer_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.3 Получение результата подписанных документов Digital Signature#
Чтобы получить результат подписанных документов в виде CMS необходимо отправить POST запрос на специальный URL передав в параметрах идентификатор сессии:
URL запроса:
https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
session_id необходимо передать в параметрах запроса:
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| session_id | String | Да | Идентификатор flow сессии |
Примеры запроса:
В качестве ответа придет JSON со следующими полями:
- document_name - наименование документа;
- document_id - ID документа в системе Digital Signature.
- document_signature - подпись документа в формате CMS.
Пример ответа:
[
{
"document_id": "08561b9d-1f16-4a14-a7c3-78c50d4090f3",
"document_name": "signed_document.cms",
"document_signature": "MIAGCSqGSIb3DQEHAqCAMIACAQExDjAMBggqgwCiXi48/TDQoxIDAgb2JqDQ..."
}
]
6.4. Скачивание архива с копиями документов#
Сервис УЦ предоставляет возможность для скачивания загруженных для подписи копий документов в архиве, который создан для удобства проверки пользователем, но не имеет юридической силы. Архив будет содержать копию каждого загруженного документа с QR-кодом и информацией о клиенте на самой последней странице.
QR-код перенаправляет клиента на страницу проверки подлинности документа.
Проверка подлинности документов происходит посредством сравнения хэш-сумм загруженного на сервер документа и документа, который отправил пользователь.
Каждый скачанный файл внутри архива имеет внутри себя метаданные с тэгом DocumentId, который соответствует
Id загруженного и подписанного документа на сервере.
Для скачивания архива со копиями документов существует два способа:
- Скачивание результата через frontend-клиент
Скачивание происходит через нажатие на ссылку скачать подписанные документы в zip файле .

- Скачивание через отправку запроса на сервис
Для скачивания архива с копиями документов через запрос необходимо выполнить GET-запрос с передачей session_id в параметрах запроса.
URL запроса:
https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/download/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
Параметры запроса:
| Параметр | Тип | Обязательно | Описание |
|---|---|---|---|
| session_id | String | Да | Идентификатор сессии УЦ |
Приведенные ниже примеры содержат тестовые данные. В реальных запросах значения полей будут соответствовать информации конкретного субъекта.
Примеры запроса:
import requests
import json
url = "https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/download/"
params = {
"session_id": "<session_id>"
}
response = requests.get(url, params=params)
if response.status_code == 200:
with open("documents.zip", "wb") as file:
file.write(response.content)
print("Archive downloaded successfully.")
else:
print("Error:", response.status_code, response.text)
const url = "https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/download/";
const params = new URLSearchParams({
session_id: "<session_id>"
});
fetch(`${url}?${params.toString()}`, {
method: "POST"
})
.then(response => response.blob())
.then(blob => {
const link = document.createElement("a");
link.href = URL.createObjectURL(blob);
link.download = "documents.zip";
link.click();
})
.catch(error => console.error("Error:", error));
const url: string = "https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/download/";
const params: URLSearchParams = new URLSearchParams({
session_id: "<session_id>"
});
fetch(`${url}?${params.toString()}`, {
method: "POST",
headers: headers
})
.then(response => response.blob())
.then(blob => {
const link = document.createElement("a");
link.href = URL.createObjectURL(blob);
link.download = "documents.zip";
link.click();
})
.catch(error => console.error("Error:", error));
Пример:
https://kyc.biometric.kz/api/v1/digital-signature-signer/document/result/download/?session_id=session_id
В ответе на запрос придет файл в binary-формате.
7. Расширенная сессия#
Важно
Активация данного функционала осуществляется исключительно при условии предварительного согласования и последующего одобрения со стороны вашего закреплённого аккаунт-менеджера.
Расширенная сессия — это механизм раздельной аутентификации и авторизации пользователя в Удостоверяющем Центре (УЦ) позволяющий вернутся в процесс подписания после переключения пользователя на другие окна интерфейса и продолжить ряд операций после.
Для возвращения пользователя к процедуре прохождения сессии и исключения ряда повторных проверок, при условии, что предыдущая сессия была завершена в течение последних 24 часов, необходимо повторно создать сессию, используя ранее применяемый флоу API_KEY, после чего загрузить дополнительный документ и перенаправить клиента по предоставленному URL.
7.1 Повторное перенаправление конечного пользователя#
Так же как и в пункте 5, клиент должен быть перенаправлен с использованием актуального session_id. В завершении URL необходимо указать параметр ?from_session_id={parent_session_id}, что позволит корректно связать новую сессию с предыдущей.
https://remote.biometric.kz/flow/<session_id>?from_session_id=<parent_session_id>
Также, вы можете объявить следующие параметры адресной строки:
- redirect - адрес на который произойдет редирект после прохождения технологий;
- locale - язык по умолчанию.
['ru', 'en', 'kz'];
Пример:
https://remote.biometric.kz/flow/<session_id>?from_session_id=<parent_session_id>&redirect=https://example.com/&locale=ru
Далее конечный пользователь перейдет на вкладку с биометрической верификацией.
После прохождения сессии, вы можете так же получить результат прохождения сессии и результат подписанных документов