Интеграция сервисов КГД (налоги и штрафы) через ШЭП: как подключить без боли

Краткое определение. Сервисы КГД в ШЭП — это набор государственных веб-сервисов Комитета госдоходов Минфина РК (категория «Налоги и штрафы» в Smart Bridge, sb.egov.kz), которые по защищённому каналу отдают сведения о налоговой задолженности, административных штрафах и регистрационных данных налогоплательщика. Подключение идёт по SOAP с ЭЦП на каждый запрос. SmartConnect закрывает транспорт ШЭП, подпись, XSD-валидацию и обработку ошибок готовым адаптером, чтобы интегратор получал чистый JSON, а не возился с конвертами ШЭП.

Для кого: интеграционным и бэкенд-разработчикам банков, финтех-команд, кредитных, страховых и лизинговых компаний, которым нужно в реальном времени проверять налоговую благонадёжность клиента или контрагента.

Поисковый интент: «интеграция КГД через ШЭП», «сервис налоговой задолженности API», «сведения о задолженности sb.egov.kz SOAP», «pass316_mf интеграция».

---

Зачем банку и финтеху сервисы КГД через ШЭП

Проверка налоговой задолженности и административных штрафов — один из самых массовых сценариев интеграции с госсистемами РК. Он встроен в кредитный скоринг, KYC/онбординг, тендерную проверку контрагентов, выдачу гарантий и лизинг. Данные предоставляет Комитет государственных доходов (КГД) Минфина РК через ШЭП / Smart Bridge (категория каталога «Налоги и штрафы», sb.egov.kz/smart-bridge/services/by-categories/18).

Боль интегратора типична: сервисы КГД требуют ЭЦП на каждый запрос, строгую XSD-схему сообщения, корректную работу с ШЭП/ВШЭП-конвертами (SOAP), обработку кодов ответа и лимитов. Самописная реализация «с нуля» — это недели-месяцы на один сервис. Готовый адаптер SmartConnect закрывает транспорт, подпись и валидацию, оставляя команде только бизнес-логику.

Какие сервисы КГД доступны через ШЭП

Наиболее востребованные сервисы категории (паспорта — в каталоге sb.egov.kz):

Сервис	Что возвращает	Типовой сценарий
Сведения об отсутствии/наличии налоговой задолженности	Признак задолженности + сумма на дату	Кредитный скоринг, KYC, тендеры
Сведения об административных штрафах	Наличие/сумма непогашенных штрафов	Онбординг, проверка благонадёжности
Регистрационные данные налогоплательщика	Статус, режим н/о, признак плательщика НДС	Проверка контрагента, выставление счётов
Сведения о доходах физлица (декларационные формы)	Данные о доходах по формам КГД — доступ ограничен, см. раздел о доступе	Подтверждение платёжеспособности

Канонический сервис-«якорь»: «Представление сведений об отсутствии (наличии) задолженности, учёт по которым ведётся в органах госдоходов» (на egov — паспорт pass316_mf). Это самый частый запрос интеграторов.

Как это работает через SmartConnect (архитектура запроса)

1. Приём запроса. Ваш сервис вызывает REST/JSON-эндпоинт SmartConnect (ИИН/БИН + тип справки) — без знания SOAP и конвертов ШЭП.
2. Конвертация JSON → XML + XSD-валидация. Шлюз собирает сообщение по схеме сервиса КГД и валидирует его на лету — класс ошибок «неверная структура» отсекается до отправки.
3. ЭЦП. Сообщение подписывается ключом организации (хранение — HashiCorp Vault), формируется корректный ШЭП-конверт.
4. Гарантированная доставка. Запрос уходит в ШЭП с retry, backoff и историей транзакций; ответ КГД конвертируется обратно в JSON.
5. Ответ. Ваш сервис получает нормализованный JSON с признаком задолженности/штрафа и суммой.

Как обрабатывать ошибки сервисов КГД

Единого «универсального» справочника кодов у всех сервисов КГД нет: каждый сервис описывает свой набор результатов в паспорте (WSDL/XSD) — обычно это структура resultCode + message. Но с точки зрения интеграции ошибки укладываются в устойчивые категории, и адаптер должен обрабатывать именно их:

Категория ответа	Что означает	Рекомендуемая обработка
Успех + данные найдены	Субъект/справка найдены, данные возвращены	Нормализовать в JSON, отдать потребителю
Успех + данные отсутствуют	Запрос корректен, но по субъекту нет записи (нет задолженности / не найден)	Это не ошибка — отдать явный «пустой» результат, не ретраить
Ошибка валидации входных данных	Неверный формат ИИН/БИН, отсутствует обязательный реквизит	Не ретраить: вернуть 4xx потребителю, показать причину
Отказ по правам/согласию	Нет прав ИС на сервис или отсутствует согласие субъекта на данные	Не ретраить: эскалация на владельца доступа/сбор согласия
Ошибка источника (КГД)	Внутренняя ошибка сервиса-источника	Ограниченный retry с backoff; при устойчивом сбое — в DLQ + алерт
Транспорт ШЭП недоступен / регламентные работы	ШЭП или сервис на профилактике	Retry с backoff по очереди, идемпотентность по ключу запроса
Таймаут / SOAP fault	Нет ответа в срок либо ошибка конверта	Retry с backoff; логировать корреляционный ID транзакции

Практический принцип: отделяйте «нет данных» от «ошибки», а восстанавливаемые ошибки (источник/транспорт/таймаут) — от невосстанавливаемых (валидация/права/согласие). Ретраить имеет смысл только первые; вторые нужно возвращать вызывающей системе сразу. SmartConnect реализует эту логику из коробки: очередь с retry/backoff, dead-letter для устойчивых сбоев и журнал транзакций с корреляционными ID.

Лимиты частоты и квоты

Публично фиксированных значений RPS или суточных квот КГД по этим сервисам не публикует: лимиты частоты и объёма задаются на стороне ШЭП индивидуально для каждой присоединённой информационной системы в рамках регламента/соглашения о присоединении. На практике это значит, что «потолок» вы согласуете при подключении, а не берёте из открытого прайса.

Правильная инженерная реакция — не полагаться на «безлимит», а заложить управление нагрузкой на стороне интегратора:

• конфигурируемый rate-limiter под согласованный лимит вашей ИС;
• очередь с backpressure, чтобы всплески трафика не били по ШЭП напрямую;
• экспоненциальный backoff и повторы по восстанавливаемым ошибкам;
• кэширование справок с коротким TTL там, где бизнес это допускает (например, справка о задолженности в рамках одной сессии скоринга).

SmartConnect выносит эти механизмы в шлюз: лимит настраивается параметром, а очередь и backoff работают без изменений в вашем коде.

Порядок доступа и согласие субъекта

Доступ к сервисам КГД через ШЭП — регламентная процедура, а не «получить ключ и начать». Базовый порядок:

1. Информационная система заявителя зарегистрирована и присоединена к ШЭП (соглашение/регламент о присоединении к Smart Bridge).
2. Сертификаты и ЭЦП организации (НУЦ РК) — для аутентификации ИС в ШЭП и подписи сообщений.
3. Согласование состава запрашиваемых данных с владельцем сервиса (КГД): вам открывают именно те сервисы, на которые есть правовое основание.
4. Правовое основание обработки персональных данных субъекта.

Отдельно про персональные данные и согласие: сведения о налоговой задолженности, штрафах и особенно о доходах физлица — это персональные (а для доходов — чувствительные) данные. Их получение требует законного основания и, как правило, явного согласия субъекта в соответствии с Законом РК «О персональных данных и их защите». Практический вывод для продукта: собирайте и храните подтверждаемое согласие субъекта до вызова сервиса, фиксируйте его в журнале, и никогда не логируйте сами персональные данные в открытом виде.

Про форму «Сведения о доходах физлица». Доступ к данным о доходах через ШЭП ограничен и жёстко привязан к правовому основанию и согласию субъекта; состав полей и сама доступность зависят от того, какой сервис КГД вам откроют под ваш сценарий (декларационные формы всеобщего декларирования, справочные сервисы). Поэтому в отличие от справки о задолженности этот сценарий стоит проектировать «под конкретный грант доступа», а не рассчитывать на универсальный публичный доступ.

Частые ошибки интеграции (и как их снимает шлюз)

• Невалидная XSD-структура сообщения → XSD-валидация на стороне шлюза до отправки.
• Проблемы с ЭЦП / истёкший сертификат → централизованное управление ключами в Vault, единая точка ротации.
• Потеря запроса при сбое ШЭП → очередь с retry, backoff и журналом транзакций.
• Смешение «нет данных» и «ошибки» → нормализованная модель ответа с явным разделением категорий.
• Игнорирование лимитов частоты → конфигурируемый rate-limiter и backpressure на стороне шлюза.
• Логирование персональных данных → маскирование чувствительных полей, аудит согласий.

Итог

Сервисы КГД — «рабочая лошадка» интеграций для финсектора РК. Через SmartConnect подключение сводится к вызову REST-эндпоинта: транспорт ШЭП, ЭЦП, конвертацию, обработку ошибок и лимитов берёт на себя шлюз, а срок интеграции сокращается с месяцев до недель. Корректная модель ошибок, управление нагрузкой и работа с согласием субъекта — заложены в шлюз по умолчанию.

Запросить готовый адаптер к сервисам КГД (налоги и штрафы) → демо SmartConnect