E-Document

Описание#

E-Document - это сервис-интеграция с Egov для получения личных электронных документов с государственной базы. Электронные документы могут быть получены в формате JSON, PDF или фотографии.

Для комфортной интеграции через Backend API воспользуйтесь Swagger (OpenAPI)

Термины#

Субъект - это человек, который является объектом запроса на получение документов в электронном формате в сервисе E-Document.
OTP-код - это временный код, который приходит на телефон субъекта от 1414 и используется для подтверждения получения электронных документов.
База мобильных граждан(БМГ) - это единая база номеров мобильных телефонов пользователей, необходимых для оказания государственных услуг, отправки SMS-паролей при авторизации или подписании услуг, с помощью одноразового пароля. Найти инструкцию по регистрации в базе можно здесь.
ИИН - индивидуальный идентификационный номер гражданина Республики Казахстан.
Unix timestamp - система описания моментов во времени, принятая в Unix и других POSIX-совместимых операционных системах. Определяется как количество секунд, прошедших с полуночи 1 января 1970 года.

Этапы:#

1. Получение API-KEY организации#

Первый этап для использования технологии - получение API-KEY организации. Чтобы получить API-KEY организации, необходимо зайти в Личный Кабинет по данной ссылке. API-KEY находится в поле Backend Api Key

backend_api_key

Пример API-KEY организации:

API-KEY: Efy202XKbVAWRu...

Примечание

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

2. Отправка запроса на получение электронного документа#

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

Чтобы запросить электронный документ субъекта необходимо, чтобы его персональные данные были зарегистрированы в Базе мобильных граждан Республики Казахстан.

При отправке запроса на получение электронного документа используются данные в формате JSON.

Важно

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

URL запроса:

https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/

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

document_type необходимо передать как параметр пути:

Значение	Описание
identity_card	Удостоверение личности
driver_license	Водительское удостоверение
birth_certificate	Свидетельство о рождении
marriage_certificate	Свидетельство о заключении брака
change_fio_certificate	Свидетельство о перемене фамилии, имени, отчества
divorce_certificate	Свидетельство о расторжении брака
diploma	Диплом
srts	Свидетельство о регистрации транспортного средства
vaccination	Паспорт вакцинации
social_id	Социальный ID
disability_certificate	Удостоверение лица с инвалидностью
large_family_certificate	Удостоверение о многодетной семье
asp_certificate	Удостоверение получателя адресной социальной помощи
tech_passport	Технический паспорт
pension	Удостоверение пенсионера
passport	Паспорт гражданина РК
student_card	Студенческий билет
vnzh	Вид на жительство
pcr_certificate	Результат ПЦР тестирования на COVID-19
lbg_card	Лицо без гражданства
insurance_policy	Страховые полисы
hunter	Удостоверение охотника
oralman	Удостоверение кандаса
attorney	Доверенность

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

Чтобы запросить необходимый тип документа, он должен быть в государственной базе данных Республики Казахстан. При отсутствии документа в базе данных, субъекту не придет сообщение с OTP-кодом для дальнейшего подтверждения и получения электронного документа.

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

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

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
iin	String	Да	ИИН субъекта
phone	String	Да	Телефонный номер субъекта

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

cURLPythonJavaScript

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "api_key": "<organization_api_key>",
    "iin": "<subjects_iin>",
    "phone": "<subjects_phone>"
    }'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/'

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

data = {
    'api_key': '<organization_api_key>',
    'iin': '<subjects_iin>',
    'phone': '<subjects_phone>',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/request/{document_type}/';

const apiKey = '<organization_api_key>';

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

const data = {
    api_key: apiKey,
    iin: '<subjects_iin>',
    phone: '<subjects_phone>'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

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

backend_session_id - идентификатор сессии для получения электронного документа;

После отправки запроса, на указанный в запросе телефонный номер субъекта приходит сообщение с OTP-кодом для дальнейшего подтверждения и получения электронного документа.

3. Отправка запроса на подтверждение получения электронного документа#

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

Необходимо обязательно отправить запрос на получение электронного документа

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

URL запроса:

https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/

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

Наименование поля	Тип	Обязательно	Описание
backend_session_id	String	Да	Идентификатор сессии, из ответа отправки запроса на получение
code	String	Да	Полученный OTP-код
file	Boolean	Да	Включить в ответ файл документа
file_type	String	Да	Тип файла документа. Доступные значения: *pdf, image*

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

cURLPythonJavaScript

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "backend_session_id": "<backend_session_id>",
    "code": "<otp_code>",
    "file": true,
    "file_type": "pdf"
  }'

import requests

url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/'

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

data = {
    'backend_session_id': '<backend_session_id>',
    'code': '<otp_code>',
    'file': True,
    'file_type': 'pdf',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/';

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

const data = {
    'backend_session_id': '<backend_session_id>',
    'code': '<otp_code>',
    'file': true,
    'file_type': 'pdf',
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Важно

Все изображения и файлы приходят в формате base64.
В зависимости от выбора типа файла в запросе на подтверждение электронный документ может придти в виде pdf или изображения в формате base64.
Полученные файлы необходимо сохранять с расширением .pdf или .jpg .

В качестве ответа придет запрошенный документ в формате JSON со следующими полями:

document_type - тип документа.
result_json - данные документа субъекта в формате json.
face_photo - фотография лица субъекта в формате base64.
qrcode - qr-код документа в формате base64.
barcode - штрих-код документа в формате base64.
document_image - изображение документа в формате base64.
document_pdf - документ в формате PDF в кодировке base64.
failure_reason - причина провала цифрогого документа.

Ошибки#

Код состояния	Ответ	Описание
404	Subject not found in CMDB	Пользователь не зарегистрирован в БМГ(база мобильных граждан). Найти инструкцию по регистрации в базе можно здесь
503	Can`t connect to e-document service	Не получается подключиться к государственному сервису Egov
503	EDocument service is not available now	Государственный сервис Egov на данный момент не доступен
504	Could not send request to e-document service	Таймаут запроса к государственному сервису Egov
424	Government service error	Получен необрабатываемый ответ от государственного сервиса Egov
404	Profile is not found	Профиль запрашиваемого гражданина не найден
400	Invalid IIN	Неверный ИИН
400	EDocument for this session has already been received	Документ для этой сессии уже получен. Возникает если пользователь с одной и той же сессией проходит несколько раз
400	Client does not have access to E-Document technology	У клиента нет доступа к технологии. Причины: подписка отсутствует, либо она истекла, или технология не активна
400	You have already requested a document for this session	Нельзя делать несколько запросов с одной сессией
400	You have not sent a request for access to an e-document	Пользователь не запросил доступ к электронному документу, отправьте запрос на получение документа
400	Subscription has not started	Подписка еще не активировалась
400	No active or future subscription for technology	Нет активной или будущей подписки на технологию
400	Client does not have subscription	У клиента отсутствует подписка, подробнее о подписках можно прочитать здесь