Интеграция с сервисом «Адресный регистр» через ШЭП: РКА, методы, ошибки
· Автор: Команда SmartConnect
Как подключить Адресный регистр (sb.egov.kz) через шлюз: РКА, 9 SOAP-методов, авторизация, коды ошибок. REST/JSON-фасад от SmartConnect.
Краткое определение. «Адресный регистр» — государственный сервис Smart Bridge (ШЭП), который по защищённому каналу отдаёт официальные адресные сведения и уникальный код адреса (РКА). Подключение идёт по SOAP к веб-сервису владельца — АО «Государственное кредитное бюро» (ГКБ). SmartConnect закрывает SOAP-обвязку, авторизацию и обработку ошибок готовым адаптером, чтобы интегратор получал чистый JSON, а не возился с WSDL.
Для кого: разработчики и интеграторы, которым нужно подтянуть нормализованный адрес физлица/объекта недвижимости в свою ИС (банки, страховые, e-commerce доставка, госуслуги, КИП/КУА).
Поисковый интент: «как интегрировать адресный регистр», «что такое РКА», «адресный регистр sb.egov.kz SOAP».
Что такое «Адресный регистр» и зачем он интеграторам
«Адресный регистр» — это эталонная база адресов РК. Любой адрес в ней привязан к РКА (регистрационный код адреса) — уникальному и неизменному коду адресного объекта на весь его жизненный цикл. РКА заменяет «адрес строкой»: вместо хрупкого текстового сопоставления вы храните код, по которому всегда можно получить актуальное и многоязычное (каз/рус) написание.
Через ШЭП сервис решает три задачи:
- Нормализация адреса — привести пользовательский ввод к официальному адресу и его РКА.
- Получение адреса по РКА — текстом или структурой XML, включая историю изменений.
- Навигация по АТЕ — разворачивать административно-территориальные единицы и составные части населённого пункта (СЧНП: улицы, проспекты и т.п.).
| Термин | Значение |
|---|---|
| РКА | Регистрационный код адреса — уникальный неизменный идентификатор адресного объекта |
| АТЕ | Административно-территориальная единица (область, район, город, село) |
| СЧНП | Составные части населённого пункта (улицы, проспекты, парки) |
| ПО/ВО | Первичный/вторичный объект (здание/строение, помещение) |
| КАТО | Классификатор административно-территориальных объектов |
Паспорт сервиса (открытые данные)
| Параметр | Значение |
|---|---|
| Владелец | АО «Государственное кредитное бюро» (ГКБ) |
| Протокол | SOAP/XML поверх HTTPS (WSDL) |
| Каталог | sb.egov.kz → Smart Bridge → каталог сервисов |
| Тест | https://testscbws.mkb.kz/gbdServices/AddressRegisterServiceImpl?wsdl |
| Прод | https://scbws.mkb.kz/gbdServices/AddressRegisterServiceImpl?wsdl |
Авторизация — два уровня (частая точка отказа):
- HTTP Basic — clientId + пароль в HTTP-заголовке (Base64).
- userId в SOAP-заголовке — GUID пользователя:
<userId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</userId>.
Пропуск второго уровня — типовая ошибка новичка: Basic проходит, но сервис отбивает запрос по правам.
Методы сервиса (9 операций)
| Метод | Назначение |
|---|---|
getATUs |
Дочерние АТЕ для родительской единицы |
getATUsForSample |
Поиск АТЕ по части названия |
getCityParts |
Список СЧНП населённого пункта |
getCityPartsForSample |
Поиск СЧНП по части названия |
getObjects |
Получить РКА и идентификаторы объектов недвижимости |
getAddressTextOfRCA |
Текущий адрес по РКА — строкой |
gethAddressTextOfRCA |
История адреса по РКА — форматированным текстом |
getAddressXMLOfRCA |
Адрес по РКА — структурой XML |
getBreadCrumbs |
«Хлебные крошки» населённого пункта в XML |
Типовой поток нормализации: getATUsForSample → выбор АТЕ → getCityPartsForSample → выбор улицы → getObjects (дом/помещение) → получаем РКА → getAddressXMLOfRCA для финальной структуры. Храните РКА у себя; адрес перезапрашивается при необходимости.
Общие входные параметры: requestNumber (уникальный номер запроса), method_name, territory_id, geonim_id, rca.
Структура ответа: messageId, responseDate, status.code / status.message.
Частые ошибки и как их читать
| Код | Что значит | Что делать |
|---|---|---|
VAL-JSR-001 |
Пустые/отсутствующие обязательные поля | Проверьте requestNumber, rca, обязательные параметры метода |
VAL-R-004 |
Требуется подтверждение согласия на доступ к данным | Получить согласие субъекта ПДн до запроса |
SBF-AD-1 |
Недостаточно прав пользователя | Проверьте userId в SOAP-заголовке и роль в ШЭП |
FAULT-015 |
Сервис недоступен / таймаут (≈150 c) | Ретрай с backoff, идемпотентность по requestNumber |
VAL-WAIT-001 |
Ответ ещё формируется | Повторный опрос по messageId |
Самые болезненные на практике: VAL-R-004 (забыли про согласие на ПДн) и FAULT-015 (нет ретраев/таймаут-политики).
Как SmartConnect снимает боль
Сырой сервис — это WSDL, двухуровневая авторизация, ручной разбор status.code и таймауты до 150 секунд. Адаптер SmartConnect к «Адресному регистру» даёт:
- REST/JSON-фасад поверх SOAP — без генерации стабов из WSDL;
- управление авторизацией (Basic +
userId) и ротацией секретов в шлюзе; - нормализованные ошибки: коды ШЭП → понятные доменные ошибки + ретраи с backoff на
FAULT-015; - идемпотентность по
requestNumberи логирование запросов для аудита ПДн; - кеш РКА, чтобы не дёргать прод на каждый показ адреса.
Запросить адаптер к «Адресному регистру» — подключим к шлюзу за дни, а не недели.
FAQ
Что такое РКА? Уникальный неизменный код адресного объекта в Адресном регистре; стабильная альтернатива хранению адреса строкой.
Нужно ли согласие субъекта? Да, для доступа к адресным сведениям физлица сервис может требовать подтверждение согласия (ошибка VAL-R-004 при его отсутствии).
REST есть? Нативно — только SOAP. REST/JSON получаете через адаптер SmartConnect.
Кто владелец сервиса? АО «Государственное кредитное бюро» (ГКБ); каталог и паспорт — на sb.egov.kz.
Источники: каталог sb.egov.kz (Smart Bridge), публичная документация сервиса «Адресный регистр» (АО ГКБ). Технические детали приведены по открытым источникам; нюансы продакшен-доступа уточняйте у владельца сервиса.