XML ↔ JSON: автоматическая конвертация с XSD-валидацией на интеграционном шлюзе

Почти любой интеграционный проект с госсистемами Казахстана рано или поздно упирается в один и тот же разрыв форматов. Ваши сервисы говорят на JSON, а на другой стороне — SOAP/XML-контракты ШЭП (Smart Bridge), банковских и налоговых систем со строгими XSD-схемами. Ручная сшивка этих миров — это самописные сериализаторы, ручная сборка конвертов, разбор namespace'ов и бесконечная отладка «поле не прошло валидацию на приёмнике». Именно здесь автоматическая конвертация XML ↔ JSON с валидацией по XSD на уровне интеграционного шлюза убирает целый класс ошибок ещё до того, как сообщение уйдёт в госсистему.

Ниже — как это устроено, какие ошибки исчезают и что это даёт команде интеграции.

Проблема: два мира форматов, одна интеграция

Типичная картина при подключении к сервису ШЭП:

• Наружу (к ШЭП / Smart Bridge, банковским АБИС, КГД) — XML c жёсткой XSD-схемой: обязательные элементы, порядок, типы данных, namespace, вложенные структуры справок.
• Внутрь (ваши микросервисы) — REST/JSON: плоские или слабо-типизированные объекты, к которым привыкли бэкенд-команды.

Когда конвертацию пишут вручную, возникают повторяющиеся боли:

1. Расхождение по типам. JSON-строка "2026-07-20" должна стать XML-элементом типа xs:date; число в JSON — xs:decimal с фиксированной точностью. Ошибка типа всплывает уже на приёмнике.
2. Порядок и обязательность элементов. XSD задаёт sequence и minOccurs; JSON порядок не гарантирует. Пропущенный обязательный элемент = отказ всей транзакции.
3. Namespace и префиксы. Один неверный namespace — и валидатор на стороне госсистемы отклоняет корректное по смыслу сообщение.
4. «Тихие» ошибки. Невалидный XML уходит в ШЭП, ответ приходит через минуты или в отдельном асинхронном канале — отладка растягивается на дни.

Каждая из этих проблем — не бизнес-логика, а рутина формата. Её и должен снимать шлюз.

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

Smartconnect ставится между вашими сервисами и госсистемами и берёт конвертацию форматов на себя. Логика движения сообщения:

Входящий поток (ваш сервис → ШЭП):

1. Микросервис отправляет привычный JSON на endpoint шлюза.
2. Шлюз конвертирует JSON → XML по преднастроенному отображению (mapping) под конкретный сервис ШЭП.
3. Собранный XML валидируется по XSD-схеме этого сервиса — до отправки наружу.
4. Только валидное сообщение уходит в ШЭП (с ЭЦП, см. ниже). Невалидное — отклоняется сразу, с понятной ошибкой, и не засоряет госсистему битым трафиком.

Обратный поток (ШЭП → ваш сервис):

1. XML-ответ госсистемы принимается шлюзом.
2. Шлюз конвертирует XML → JSON и отдаёт вашему сервису чистый объект — без namespace, конвертов и XML-обвязки.

Ключевая идея: валидация происходит на границе, до пересечения контура госсистемы. Ошибка формата ловится там, где её дёшево исправить — в вашем контуре, с полным контекстом запроса, — а не как отложенный отказ на стороне ШЭП.

Валидация по XSD как «предохранитель»

XSD-схема сервиса — это контракт. Шлюз использует её как обязательный проходной фильтр: сообщение проверяется по стандартной XSD-схеме (W3C XML Schema) сервиса, с учётом namespace, и то, что схеме не соответствует, физически не уходит наружу. Что это даёт на практике:

• Обязательные поля и типы проверены заранее — не «упадёт на приёмнике через 30 секунд», а вернётся синхронно с указанием конкретного поля.
• Единый источник правды. Обновилась схема сервиса ШЭП — обновляется XSD на шлюзе, и все интеграции сразу подчиняются новому контракту. Не нужно править сериализацию в каждом микросервисе.
• Понятная диагностика. Вместо «сервис ШЭП вернул ошибку» разработчик видит, какой именно элемент не прошёл и почему.

Пример структуры ошибки валидации, которую получает вызывающий сервис (иллюстрация формата — конкретная схема ответа согласуется при подключении):

{
  "status": "validation_error",
  "service": "gbd-fl",
  "errors": [
    {
      "path": "/Request/Person/iin",
      "rule": "pattern",
      "message": "ИИН должен состоять из 12 цифр"
    },
    {
      "path": "/Request/Person/birthDate",
      "rule": "type",
      "expected": "xs:date",
      "got": "20-07-2026"
    }
  ]
}

Разработчик получает не XML-стектрейс, а адресный список того, что поправить.

Где конвертация встраивается в остальной конвейер шлюза

Конвертация форматов — не отдельный тул, а звено единого потока обработки сообщения. В связке с ней работают:

• ЭЦП и подпись сообщений. После сборки валидного XML шлюз подписывает сообщение (ключи — в защищённом хранилище, например HashiCorp Vault), как того требуют контракты ШЭП. Конвертация и подпись — один конвейер, а не два ручных шага. Подробнее — в статье «Как работает ЭЦП в Казахстане».
• Гарантированная доставка и retry. Валидное сообщение попадает в очередь с гарантированной доставкой: при сбое на стороне госсистемы оно не теряется, а повторяется по политике retry, с сохранением истории транзакции.
• Гранулярный доступ. Какой сервис имеет право слать какие сообщения — определяется моделью доступа шлюза, а не хардкодом в интеграции.

То есть конвертация XML↔JSON — это входная точка в предсказуемый, наблюдаемый и безопасный поток, а не изолированный парсер.

Что это даёт команде

До: ручная конвертация	После: шлюз с XSD-валидацией
Самописные сериализаторы XML в каждом сервисе	Одно преднастроенное отображение на сервис ШЭП
Ошибки типа/порядка всплывают на приёмнике	Ошибки ловятся синхронно, до отправки наружу
Обновление схемы = правки в N сервисах	Обновление XSD на шлюзе — один раз
Отладка «битого» XML — часы и дни	Адресная диагностика по полю сразу
Разработчики учат конверты и namespace ШЭП	Разработчики работают с чистым JSON

Итог для интеграционного проекта: меньше кода на стыке форматов, меньше отказов на стороне госсистем и заметно короче цикл отладки — а именно отладка форматов обычно съедает недели на старте интеграции с ШЭП.

Коротко

• Разрыв «JSON внутри — XML снаружи» — источник целого класса интеграционных ошибок с госсистемами РК.
• Интеграционный шлюз конвертирует XML ↔ JSON автоматически и валидирует по XSD на границе, до пересечения контура ШЭП.
• Ошибки формата ловятся синхронно и адресно, обновление контракта делается в одном месте, а разработчики работают с привычным JSON.
• Конвертация встроена в единый конвейер с ЭЦП, гарантированной доставкой и контролем доступа — не отдельный ручной шаг.

Хотите увидеть конвертацию и XSD-валидацию под ваш сервис ШЭП вживую? Свяжитесь с командой SmartConnect — покажем на вашем сценарии.

Материал носит информационный характер. Технические детали реализации под ваш контур уточняются при подключении.