E-Document
Описание#
E-Document - это сервис-интеграция с Egov для получения личных электронных документов с государственной базы. Электронные документы могут быть получены в формате JSON, PDF или фотографии.
Для комфортной интеграции через Backend API воспользуйтесь Swagger (OpenAPI)
Термины#
- Субъект - Человек, который является объектом запроса на получение документов в электронном формате в сервисе E-Document
- OTP-код - Временный код, который приходит на телефон субъекта от 1414 и используется для подтверждения получения электронных документов
- База мобильных граждан(БМГ) - Единая база номеров мобильных телефонов пользователей, необходимых для оказания государственных услуг, отправки SMS-паролей при авторизации или подписании услуг, с помощью одноразового пароля. Найти инструкцию по регистрации в базе можно здесь
- ИИН - Индивидуальный идентификационный номер гражданина Республики Казахстан
- Unix timestamp - Система описания моментов во времени, принятая в Unix и других POSIX-совместимых операционных системах. Определяется как количество секунд, прошедших с полуночи 1 января 1970 года
- 6-значный одноразовый код - Код, полученный через Egov mobile или мобильное банковское приложение
Этапы:#
1. Получение API-KEY организации#
Первый этап для использования технологии - получение API-KEY организации. Чтобы получить API-KEY организации, необходимо зайти в Личный Кабинет по данной ссылке. 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 | Да | Телефонный номер субъекта, пример: 77********* |
| child_id | String | Нет | Айди несовершеннолетнего (субъекта) по которому запрашивается документ |
| check_mcdb_required | Bool | Нет | Провека субъекта на наличие в БМГ |
Примеры запроса:
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 |
Примеры запроса:
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 со следующими полями:
- backend_session_id - Идентификатор сессии
- document_type - Тип документа
- result_json - Данные документа субъекта в формате json
- face_photo - Фотография лица субъекта в формате base64
- qrcode - QR-код документа в формате base64
- barcode - Штрих-код документа в формате base64
- document_image - Изображение документа в формате base64
- document_pdf - Документ в формате PDF в кодировке base64
- gender - Пол субъекта, вычисленный из ИИНа субъекта
- failure_reason - Причина провала цифрового документа
4. Отправка запроса на получения электронного документа посредством 6 значного кода из egov или из приложений БВУ#
URL запроса:
https://kyc.biometric.kz/api/v1/backend/e-document/online-access/aprove/external/otp/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
Параметры запроса:
Query параметры:
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| document_type | String | Да | Тип документа. |
Тело запроса (JSON):
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| api_key | String | Да | API KEY организации в личном кабинете |
| code | String | Да | Код подтверждения (6 цифр), отображаемый в приложении egov mobile |
| file | Boolean | Да | Включить в ответ файл документа |
| file_type | String | Да | Тип файла документа. Доступные значения: pdf, image |
Примеры запроса:
curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/external/otp/?document_type=document_type' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_key": "Enter your api key here",
"code": "<6-digit-code>",
"file": true,
"file_type": "pdf"
}'
import requests
url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/approve/external/otp/?document_type=document_type' \
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
}
data = {
'api_key': 'Enter your api key here',
'code': '<6-digit-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/external/otp/?document_type=document_type';
const headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
};
const data = {
'api_key': 'Enter your api key here',
'code': '<6-digit-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));
В качестве ответа придет запрошенный документ в формате JSON со следующими полями:
- backend_session_id - Идентификатор сессии
- document_type - Тип документа
- result_json - Данные документа субъекта в формате json
- face_photo - Фотография лица субъекта в формате base64
- qrcode - QR-код документа в формате base64
- barcode - Штрих-код документа в формате base64
- document_image - Изображение документа в формате base64
- document_pdf - Документ в формате PDF в кодировке base64
- gender - Пол субъекта, вычисленный из ИИНа субъекта
- failure_reason - Причина провала цифрового документа
5. Отправка запроса на наличие субъекта в БМГ(база мобильных граждан)#
URL запроса:
https://kyc.biometric.kz/api/v1/backend/e-document/online-access/check-subject-in-mcdb/
| Формат запроса | Метод запроса |
|---|---|
| JSON | POST |
| Наименование поля | Тип | Обязательно | Описание |
|---|---|---|---|
| api_key | String | Да | API KEY организации в личном кабинете |
| iin | String | Да | ИИН субъекта |
| phone | String | Да | Телефонный номер субъекта, пример: 77********* |
| child_id | String | Нет | Айди несовершеннолетнего (субъекта) по которому запрашивается документ |
| check_mcdb_required | Bool | Нет | Провека субъекта на наличие в БМГ |
Примеры запроса:
curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/check-subject-in-mcdb/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"api_key": "Enter your api key here",
"iin": "123456789012",
"phone": "77075553535",
"child_id": "0123456",
"check_mcdb_required": false
}'
import requests
url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/check-subject-in-mcdb/' \
headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
}
data = {
'api_key': 'Enter your api key here',
'iin': '123456789012',
'phone': '77075553535',
'child_id': '0123456',
'check_mcdb_required': false,
}
response = requests.post(url, headers=headers, json=data)
print(response.json())
const url = 'https://kyc.biometric.kz/api/v1/backend/e-document/online-access/check-subject-in-mcdb/';
const headers = {
'accept': 'application/json',
'Content-Type': 'application/json',
};
const data = {
'api_key': 'Enter your api key here',
'iin': '123456789012',
'phone': '77075553535',
'child_id': '0123456',
'check_mcdb_required': false,
};
fetch(url, {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));
Ошибки#
| Код состояния | Ответ | Описание |
|---|---|---|
| 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 | У клиента отсутствует подписка, подробнее о подписках можно прочитать здесь |