GBDFL

Описание#

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

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

Термины#

Субъект - Человек, который является объектом запроса на получение информации из ГБДФЛ
OTP-код - Временный код, который приходит на телефон субъекта от 1414 и используется для подтверждения получения электронных документов
Государственная База Данных Физических Лиц (ГБДФЛ) - Единая база физических лиц Республики Казахстан
ИИН - Индивидуальный идентификационный номер гражданина Республики Казахстан

Этапы:#

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

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

backend_api_key

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

API-KEY: Efy202XKbVAWRu...

Примечание

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

2. Отправка запроса на получение информации из ГБДФЛ #

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

Чтобы запросить данные из ГБДФЛ необходимо пройти следующие технологии, используя Backend интеграцию:

Liveness (Лицо Субъекта)
E-Document (Удостоверение личности Субъекта)
Face2Face (Используя сессии полученые в результате прохождения предыдущих двух технологий)

После прохождения вышеперечисленных технологий информацию о субъекте из ГБДФЛ можно получить в течении 3-х часов

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

Важно

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

URL запроса:

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

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

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

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

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

cURLPythonJavaScript

    curl -X 'POST' \
    'https://kyc.biometric.kz/api/v1/backend/gbdfl/' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
    "api_key": "<organization_api_key>",
    "iin": "<subjects_iin>",
    "face2face_backend_session_id": "<backend_session_id>"
    }'

import requests

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

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

data = {
    'api_key': '<organization_api_key>',
    'iin': '<subjects_iin>',
    'face2face_backend_session_id': '<backend_session_id>',
}

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

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/gbdfl/';

const apiKey = '<organization_api_key>';

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

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

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 - Идентификатор сессии
failure_reason - Причина неуспешного прохождения
- type - Тип ошибки
- detail - Детальное описание ошибки
face2face_result - Результат сравнения лиц Face2Face
- prediction - Прогноз результата сравнения
- prediction_percent - Процент совпадения лиц
- backend_session_id - Идентификатор сессии Face2Face
- result - Булевый результат успешности сравнения (true/false)
- source_session_1 - Данные первой исходной сессии для сравнения
  - id - Уникальный идентификатор сессии
  - technology - Информация о технологии
    - name - Название технологии
    - code - Код технологии
  - status - Статус сессии (CREATED, FAILED и т.д.)
  - created_at - Дата и время создания сессии
  - updated_at - Дата и время последнего обновления сессии
- source_session_2 - Данные второй исходной сессии для сравнения
  - id - Уникальный идентификатор сессии
  - technology - Информация о технологии
    - name - Название технологии
    - code - Код технологии
  - status - Статус сессии (CREATED, FAILED и т.д.)
  - created_at - Дата и время создания сессии
  - updated_at - Дата и время последнего обновления сессии
iin - ИИН Субъекта
result_json - Данные результата в формате JSON
- iin - Индивидуальный идентификационный номер субъекта
- surname - Фамилия субъекта
- name - Имя субъекта
- patronymic - Отчество субъекта
- birth_date - Дата рождения субъекта (формат: YYYY-MM-DD)
- gender - Пол субъекта (Мужской/Женский)
- nationality - Национальность субъекта
- citizenship - Гражданство субъекта
- life_status - Статус жизнедеятельности субъекта
- birth_place - Информация о месте рождения
  - country - Страна рождения
  - region - Регион рождения
  - district - Район рождения
  - city - Город рождения
- documents - Массив документов субъекта
  - type - Тип документа (например, УДОСТОВЕРЕНИЕ РК, ПАСПОРТ)
  - number - Номер документа
  - issue_date - Дата выдачи документа (формат: YYYY-MM-DD)
  - expiry_date - Дата окончания срока действия документа (формат: YYYY-MM-DD)
  - issuer - Орган, выдавший документ
  - status - Статус действительности документа (например, ДОКУМЕНТ ДЕЙСТВИТЕЛЕН)
- registration_address - Адрес регистрации субъекта
  - country - Страна регистрации
  - region - Регион регистрации
  - district - Район регистрации
  - city - Город регистрации
  - street - Улица регистрации
  - building - Номер дома
  - flat - Номер квартиры
  - begin_date - Дата начала регистрации по адресу (формат: YYYY-MM-DD)
status - Статус получения информации из ГБДФЛ
result - Результат успешности прохождения (true/false)

Примечание

Возможны следующие статусы для получения информации из ГБДФЛ:

UNAPPROVED
PENDING
VALID
INVALID
TIMEOUT
NOT_FOUND
FAILED
ERROR_ACCEPTED

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

{
  "backend_session_id": "a7f3c891-4b2e-4d5a-9c7f-1e8d6b9a3f2c",
  "failure_reason": null,
  "face2face_result": {
    "prediction": "0.987214",
    "prediction_percent": "98.7",
    "backend_session_id": "3e9b7d42-6c1a-4f8e-a2d5-9b4c8e1f7a3d",
    "result": true,
    "source_session_1": {
      "id": "5f8a2c3d-9e4b-4a1c-b7d6-2f3e8a9c1b4d",
      "technology": {
        "name": "Liveness Short",
        "code": "LDSH"
      },
      "status": "COMPLETED",
      "created_at": "2025-10-15T10:23:45.123Z",
      "updated_at": "2025-10-15T10:24:12.456Z"
    },
    "source_session_2": {
      "id": "8b4d3a2c-1e9f-4c7a-a5b8-6d2e9f3c1a7b",
      "technology": {
        "name": "E-Document",
        "code": "ED"
      },
      "status": "COMPLETED",
      "created_at": "2025-10-15T10:24:30.789Z",
      "updated_at": "2025-10-15T10:25:18.234Z"
    }
  },
  "iin": "950215301234",
  "result_json": {
    "iin": "950215301234",
    "surname": "Нурланов",
    "name": "Асхат",
    "patronymic": "Ерланович",
    "birth_date": "1995-02-15",
    "gender": "Мужской",
    "nationality": "КАЗАХ",
    "citizenship": "КАЗАХСТАН",
    "life_status": "Нормальный",
    "birth_place": {
      "country": "КАЗАХСТАН",
      "region": "Алматинская область",
      "district": "Талгарский",
      "city": "Талгар"
    },
    "documents": [
      {
        "type": "УДОСТОВЕРЕНИЕ РК",
        "number": "N23456789",
        "issue_date": "2015-03-10",
        "expiry_date": "2035-03-10",
        "issuer": "МВД РК",
        "status": "ДОКУМЕНТ ДЕЙСТВИТЕЛЕН"
      },
      {
        "type": "ПАСПОРТ",
        "number": "N98765432",
        "issue_date": "2020-08-15",
        "expiry_date": "2030-08-15",
        "issuer": "МВД РК",
        "status": "ДОКУМЕНТ ДЕЙСТВИТЕЛЕН"
      }
    ],
    "registration_address": {
      "country": "КАЗАХСТАН",
      "region": "Алматы",
      "district": "Медеуский",
      "city": "Алматы",
      "street": "Абая",
      "building": "52",
      "flat": "45",
      "begin_date": "2018-06-20"
    }
  },
  "status": "VALID",
  "result": true
}

Ошибки#

Код состояния	Ответ	Описание
400	Subscription has not started	Подписка еще не активировалась
400	No active or future subscription for technology	Нет активной или будущей подписки на технологию
400	Client does not have subscription	У клиента отсутствует подписка, подробнее о подписках можно прочитать здесь
400	Client does not have access to GBDFL technology	У клиента нет доступа к технологии. Причины: подписка отсутствует, либо она истекла, или технология не активна
404	Face2Face backend session not found	Не найдена backend сессия с Face2Face результатом
404	Organization not found	Не найдена организация по предоставленному API key

Причины провала#

failure_reason.type	failure_reason.detail	Описание
CLIENT	The required verifications for GBDFL are expired	Срок действия необходимых верификаций (Liveness/EDocument) истек
CLIENT	INVALID	Неправильные токен полученный с государственного сервиса
CLIENT	TIMEOUT	Токен полученный с государственного сервиса истек
CLIENT	NOT_FOUND	Запрошенные данные по субъекту не были найдены
CLIENT	FAILED	Ошибка при получении данных с государственного сервиса
CLIENT	Face2Face failed	Отрицательный Face2Face результат
CLIENT	Liveness failed	Отрицательный Liveness результат
CLIENT	EDocument validation error:	Отрицательный EDocument результат
CLIENT	Required technology in Face2Face result missing: tech_code, tech_code	Face2Face результат не был получен из сессий необходимых технологий (Liveness/EDocument)
CLIENT	Face2Face source sessions are missing	Face2Face результат был получен не из сессий технологий
CLIENT	GBDFL Face2Face result missing	Face2Face сессия не содержит результата
SERVICE_ERROR	Can`t connect to GBDFL service	Не удалось отправить запрос на GBDFL сервис