Интеграция с ГБД ФЛ через ШЭП: как получать сведения о физлицах по ИИН

Краткое определение. ГБД ФЛ — Государственная база данных «Физические лица» — один из базовых государственных реестров РК. Хранит достоверные сведения о физлицах, привязанные к ИИН: ФИО, дату рождения, статус документов, актуальность данных. Реестр формируется на основе данных регистрации актов гражданского состояния и документирования; сведения из него предоставляются интеграторам через ШЭП / Smart Bridge по защищённому каналу с ЭЦП на запрос. SmartConnect подключает такие сервисы ШЭП «под ключ» — по той же схеме, что и другие интеграции нашего каталога, — отдавая интегратору чистый JSON вместо конвертов ШЭП.

Для кого: интеграционным и бэкенд-разработчикам банков, МФО, страховых, финтех- и B2C-продуктов, которым нужны онлайн-KYC, проверка клиента при регистрации, скоринг или подтверждение личности по ИИН.

Поисковый интент: «ГБД ФЛ API», «проверка ИИН через ШЭП», «сверка ИИН и ФИО интеграция», «получить данные физлица по ИИН sb.egov.kz».

Статус сервиса в SmartConnect. ГБД ФЛ — перспективный сервис нашего каталога ШЭП: он подключается по запросу под конкретный сценарий интегратора по той же архитектуре, что уже действующие адаптеры (например, Адресный регистр, сервисы КГД и Правовой кадастр). Точный состав методов, формат запроса и лимиты фиксируются при подключении по паспорту сервиса в Smart Bridge и условиям доступа владельца данных — см. раздел «Доступ» ниже. Мы не публикуем перечень методов «из коробки», пока он не подтверждён паспортом сервиса под ваш сценарий.

---

Зачем подключаться к ГБД ФЛ

ГБД ФЛ — один из самых востребованных источников данных в ШЭП, потому что вокруг ИИН строится почти любая идентификация клиента. Практически любой B2C- или финтех-продукт, которому нужен онлайн-KYC, рано или поздно упирается в проверку физлица по ИИН. Типовые сценарии:

• банкам и МФО — KYC при онлайн-выдаче: подтвердить, что заявитель — реальное лицо, а введённые ИИН и ФИО соответствуют эталону;
• страховым и финтех — проверка данных клиента при оформлении полиса или счёта;
• маркетплейсам и сервисам с договорами — валидация ИИН и ФИО при регистрации или заключении договора;
• скоринговым и антифрод-командам — проверка корректности идентификатора как одного из сигналов.

Именно высокий входящий спрос делает ГБД ФЛ приоритетной темой для интеграторов — и частым первым вопросом при подключении к ШЭП.

Какие сведения можно получить

По каталогу Smart Bridge (sb.egov.kz) сервисы категории «физические лица» опираются на данные ГБД ФЛ. Точный состав атрибутов и доступных операций определяется паспортом конкретного сервиса и правами вашей ИС, но типовые категории выглядят так:

Тип запроса	Что возвращает	Типовой сценарий
Сведения о физлице по ИИН	ФИО, дата рождения, признак актуальности данных	KYC, автозаполнение анкеты
Сверка «ИИН ↔ ФИО»	Признак соответствия введённых данных эталону	Валидация формы, антифрод
Статус документа, удостоверяющего личность	Действителен / недействителен, реквизиты документа	Подтверждение личности

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

Типичный сценарий: сверка «ИИН ↔ ФИО»

Самый частый кейс интеграции — проверка соответствия ИИН и ФИО при регистрации или подаче заявки:

1. Клиент вводит ИИН и ФИО в вашей форме (регистрация, заявка, договор).
2. Ваш бэкенд отправляет запрос к сервису ГБД ФЛ через ШЭП.
3. Сервис возвращает эталонные сведения по этому ИИН.
4. Вы сверяете введённые данные с эталоном и принимаете решение: пропустить, отклонить или отправить на ручную проверку.

Звучит просто — но «прямое» подключение к ШЭП добавляет несколько слоёв сложности, из-за которых интеграция часто буксует.

Почему «прямое» подключение к ШЭП болезненно

ШЭП — это SOAP/XML-ориентированная среда с собственными требованиями к безопасности и форматам. Типичные боли интегратора:

• SOAP вместо REST. Большинство современных продуктов говорят на REST/JSON, а ШЭП ждёт SOAP-конверты с определённой структурой. Нужен переходник XML↔JSON (см. наш разбор «XML↔JSON + XSD-валидация»).
• ЭЦП на каждом запросе. Сообщения в ШЭП подписываются электронной цифровой подписью; неправильная подпись → отказ шлюза (подробнее — «Как работает ЭП в Казахстане»).
• XSD-валидация. Малейшее несоответствие схеме — и запрос отклоняется без внятной причины.
• Асинхронность и коды ответов. Часть сервисов работает по паттерну «запрос → квитанция → результат»; нужно уметь опрашивать статус и корректно разбирать бизнес-коды ошибок.
• Регламент доступа. Порядок получения доступа к ГБД ФЛ (соглашение, роли, ограничения по составу данных и частоте запросов) регулируется владельцем данных и фиксируется при подключении — см. раздел «Доступ».

Как это решает интеграционный шлюз SmartConnect

SmartConnect — интеграционный шлюз, который берёт «шэповскую» сложность на себя и отдаёт вашему приложению чистый REST/JSON. Для сервисов ШЭП это работает так:

• вы вызываете один HTTPS-эндпоинт шлюза с JSON-телом (ИИН + нужные атрибуты);
• шлюз строит SOAP-конверт, накладывает ЭЦП, проходит XSD-валидацию и общается с ШЭП;
• ответ сервиса нормализуется обратно в предсказуемый JSON с человекочитаемыми кодами;
• ретраи с backoff, тайм-ауты, dead-letter для устойчивых сбоев и журнал транзакций с корреляционными ID инкапсулированы в шлюзе.

Итог: интеграция сводится к одному REST-вызову, а не к неделям возни с SOAP, подписью и схемами. Для ГБД ФЛ конкретный контракт (какие атрибуты идут в запрос и что возвращается) собирается по паспорту сервиса на этапе подключения — по той же архитектуре, что уже действующие адаптеры каталога.

Частые ошибки интеграции и как их избежать

Симптом	Вероятная причина	Как помогает шлюз
Запрос отклонён без описания	Несоответствие XSD-схеме	Шлюз валидирует и формирует конверт по актуальной схеме сервиса
Ошибка подписи / отказ безопасности	Неверная/просроченная ЭЦП	Подпись накладывается централизованно на стороне шлюза; ключи ротируются
«Пустой» ответ по валидному ИИН	Ограничение состава данных для вашей роли / нет основания доступа	Разграничение «нет данных» и «нет прав»; конфигурация по паспорту сервиса
Таймаут / SOAP fault	Нет ответа в срок либо ошибка конверта	Retry с backoff, dead-letter, логирование корреляционного ID транзакции
Данные не совпадают, хотя ИИН верный	Регистр/транслитерация ФИО, порядок частей имени	Нормализация на стороне интеграции; правила сверки уточняются под сценарий

Практический принцип: отделяйте «нет данных» от «ошибки», а восстанавливаемые ошибки (транспорт/таймаут) — от невосстанавливаемых (идентификация/права/доступ). Ретраить имеет смысл только первые.

Доступ: что нужно уточнить при подключении

ГБД ФЛ содержит персональные сведения, поэтому доступ строже, чем к справочным сервисам. При подключении фиксируются:

• Основание доступа. Договор/соглашение с владельцем данных и права вашей ИС на конкретный сервис в Smart Bridge. Состав методов и точные коды сервиса берутся из его паспорта в каталоге sb.egov.kz.
• Состав данных по роли. Какие атрибуты возвращаются вашей ИС, определяется матрицей доступа; для части ролей ответ может быть ограничен признаком «соответствует / не соответствует» без выдачи самих сведений.
• Ограничения по частоте и объёму. Лимиты запросов и время ответа регулируются регламентом сервиса и условиями владельца данных; их значения уточняются на этапе подключения по паспорту сервиса.
• Правила нормализации ФИО и актуализации. Требования к формату ФИО (регистр, транслитерация, порядок частей имени) и к периодичности актуализации данных определяются владельцем данных и регламентом сервиса.

SmartConnect помогает пройти этот путь: подбираем нужные методы по паспорту, настраиваем авторизацию и ротацию ключей в шлюзе, закрываем транспорт ШЭП, подпись и обработку ошибок.

Запросить подключение к ГБД ФЛ — обсудим сценарий проверки по ИИН, подберём методы по паспорту сервиса и подключим к шлюзу.

---

FAQ

ГБД ФЛ уже доступна через SmartConnect? Это перспективный сервис нашего каталога: он подключается по запросу под конкретный сценарий по той же архитектуре, что уже действующие адаптеры ШЭП. Состав методов и лимиты фиксируются при подключении по паспорту сервиса.

По какому идентификатору идёт запрос? По ИИН физлица. Обязательные и опциональные атрибуты запроса и состав ответа задаёт схема конкретного сервиса в Smart Bridge.

Можно ли просто сверить ИИН и ФИО, не получая полные данные? Да, сверка «ИИН ↔ ФИО» — типовой сценарий: для части ролей сервис может возвращать только признак соответствия без выдачи самих сведений. Точный режим зависит от паспорта сервиса и прав вашей ИС.

Почему ответ «пустой» при валидном ИИН? Чаще всего это ограничение состава данных для вашей роли или отсутствие основания доступа, а не ошибка запроса. Важно отличать «нет данных» от «нет прав».

Нужна ли ЭЦП? Да, запросы в ШЭП подписываются ЭЦП. При работе через SmartConnect подпись накладывается на стороне шлюза — интегратору не нужно реализовывать её самостоятельно.

---

Источники: каталог sb.egov.kz (Smart Bridge), паспорта сервисов категории «физические лица» на egov.kz, Закон РК «О национальных реестрах идентификационных номеров» (регулирует ИИН/БИН). Технические детали приведены по открытым источникам и общей архитектуре ШЭП; состав методов, форматы запроса, коды ошибок, лимиты и SLA, а также регламент доступа и правила нормализации данных уточняются по паспорту сервиса и условиям доступа владельца данных при подключении.