Address Service

Описание#

Address Service - это сервис-интеграция с Egov для получения адреса прописки пользователя.

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

Термины#

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

Этапы:#

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/address/approve/

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

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

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

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

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/backend/address/approve/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "<ORGANIZATION_API_KEY>",
    "iin": "<SUBJECTS_IIN>"
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/backend/address/approve/"

payload = json.dumps({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>"
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>"
});

let requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://kyc.biometric.kz/api/v1/backend/address/approve/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Далее мобильное устройство субъекта, на телефонный номер которого привязан ИИН придет уведомление с запросом на подтверждение.

После подтверждения субъектом в качестве ответа придет JSON со следующими полями:

backend_session_id - идентификатор сессии для получения электронного документ;
status - статус запроса, на получение адреса прописки субъекта:

PENDING (Ожидание): Запрос находится в ожидании подтверждения субъектом - отраправка кода подтверждения в ответ на сообщение от 1414.

VALID (Действительный): Запрос был успешно обработан и подтвержден субъектом.

INVALID (Недействительный): Запрос был отклонен субъектом.

NOT_FOUND (Не найден): Запрошенные данные по субъекту не были найдены.

TIMEOUT (Тайм-аут): Запрос завершился из-за превышения времени ожидания.
expire_date - дата истечение запроса на адрес субъекта;

Пример ответа со статусом PENDING:

{
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "status": "PENDING",
  "expire_date": null
}

Пример ответа со статусом VALID:

Примечание

После получения ответа со статусом VALID, для получения адреса прописки субъекта, необходимо отправить запрос на https://kyc.biometric.kz/api/v1/backend/address/, передавая получаемый идентификатор сессии (backend_session_id) в теле запроса.

{
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "status": "VALID",
  "expire_date": "2023-01-01T12:59:15Z"
}

Пример ответа со статусом INVALID:

{
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "status": "INVALID",
  "expire_date": null
}

Пример ответа со статусом TIMEOUT:

{
  "backend_session_id": "f1b5887b-5f91-417a-bf04-bb45fe28cc4e",
  "status": "TIMEOUT",
  "expire_date": null
}

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

После подтверждения ответом на сообщение от 1414, на получение адреса прописки субъектом, необходимо отправить запрос, на получение адреса прописки передавая в теле запроса полученный идентификатор сессии (backend_session_id).

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

URL запроса:

https://kyc.biometric.kz/api/v1/backend/address/

Request format	Request method
JSON	POST

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

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

cURLPythonJavaScript

curl --location --request POST 'https://kyc.biometric.kz/api/v1/backend/address/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "api_key": "<ORGANIZATION_API_KEY>",
    "iin": "<SUBJECTS_IIN>"
    "backend_session_id": "<backend_session_id>",
}'

import requests
import json

url = "https://kyc.biometric.kz/api/v1/backend/address/'

payload = json.dumps({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>",
  "backend_session_id": "<BACKEND_SESSION_ID>"
})
headers = {
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.json())

let myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");

let raw = JSON.stringify({
  "api_key": "<ORGANIZATION_API_KEY>",
  "iin": "<SUBJECTS_IIN>",
  "backend_session_id": "<BACKEND_SESSION_ID>"

});

let requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://kyc.biometric.kz/api/v1/backend/address/", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

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

iin - иин субъекта.
address - JSON-объект с адресом субъекта.

Пример ответа:

{
  "iin": "012345678901",
  "address": {
    "country": {
      "code": "398",
      "nameRu": "КАЗАХСТАН",
      "nameKz": "ҚАЗАҚСТАН",
      "changeDate": "2008-03-01T13:21:44+06:00"
    },
    "region": {
      "code": "1910267",
      "nameRu": "ЖЕТЫСУСКИЙ",
      "nameKz": "ЖЕТІСУ",
      "changeDate": "2008-03-01T13:21:45+06:00"
    },
    "city": "ҚАЛА IШIНДЕГI АУДАНЫ Жетысуский",
    "street": "УЛИЦА Пушкина",
    "building": "13",
    "flat": "1"
  }
}

Ошибки#

Код состояния	Ответ	Описание
409	Could not send request to address service	Не удалось установить соединение с сервисом address
400	Subscription has not started	Подписка еще не активировалась
400	No active or future subscription for technology	Нет активной или будущей подписки на технологию
400	Client does not have subscription	У клиента отсутствует подписка, подробнее о подписках можно прочитать здесь
400	Address data is empty or data already recieved	Данные адреса пусты или данные уже получены
400	Token Expired	Время действия для получения адреса истекло