Про затвердження форматів електронних повідомлень та обміну даними системи електронної взаємодії державних електронних інформаційних ресурсів

Відповідно до пункту 6 Положення про електронну взаємодію державних електронних інформаційних ресурсів, затвердженого постановою Кабінету Міністрів України від 08 вересня 2016 року № 606, підпункту 11 пункту 4 Положення про Державне агентство з питань електронного урядування України, затвердженого постановою Кабінету Міністрів України від 01 жовтня 2014 року № 492, абзацу другого пункту 3 постанови Кабінету Міністрів України від 10 травня 2018 року № 357 «Деякі питання організації електронної взаємодії державних електронних інформаційних ресурсів» НАКАЗУЮ:

1. Затвердити формати електронних повідомлень та обміну даними системи електронної взаємодії державних електронних інформаційних ресурсів, що додаються.

2. Установити, що суб’єкти владних повноважень для здійснення електронної інформаційної взаємодії створюють (використовують) програмні комплекси (інтерфейси прикладного програмування - веб-сервіси та веб-клієнти), що забезпечують формування, передавання та отримання електронних повідомлень відповідно до форматів.

3. Директору генерального департаменту цифрової трансформації Маковському Д.В. забезпечити:

1) подання цього наказу на державну реєстрацію до Міністерства юстиції України в установленому законодавством порядку;

2) оприлюднення цього наказу на офіційному веб-сайті Державного агентства з питань електронного урядування України;

3) розміщення форматів засобами програмного комплексу Національного реєстру електронних інформаційних ресурсів.

4. Цей наказ набирає чинності з дня офіційного опублікування.

5. Контроль за виконанням цього наказу залишаю за собою.

ФОРМАТИ
електронних повідомлень та обміну даними системи електронної взаємодії державних електронних інформаційних ресурсів

I. Загальні положення

1. Ці Формати встановлюють вимоги до електронного повідомлення та обміну даними, що застосовуються під час створення веб-сервісів і веб-клієнтів та їх використання в системі електронної взаємодії державних електронних інформаційних ресурсів (далі - СЕВДЕІР).

Забезпечення цілісності та доступності даних в СЕВДЕІР здійснюється відповідно до вимог законодавства у сфері захисту інформації.

2. Використання цих Форматів є обов'язковим для організації електронної інформаційної взаємодії (далі - е-взаємодія) державних електронних інформаційних ресурсів (далі - е-ресурс) через СЕВДЕІР.

3. У цих Форматах терміни вживаються в таких значеннях:

SOAP - протокол обміну структурованими повідомленнями (англ. Simple Object Access Protocol) в розподілених обчислювальних системах, що базується на форматі XML;

SOAP-повідомлення - структуроване електронне повідомлення версії SOAP 1.1 або SOAP 1.2 з використанням серіалізації XML 1.0;

XML - запропонований консорціумом World Wide Web (W3C) стандарт побудови мов розмітки (англ. Extensible Markup Language) ієрархічно структурованих даних для обміну між різними інформаційними системами: https://www.w3.org/XML/;

XML-документ - текстовий документ, складений у повній відповідності до стандарту XML. Складається з прологу, одного кореневого елемента XML, коментарів, декларації типів даних і символів;

XSD - визначення XML-схеми, де формально описані елементи в документі XML: https://www.w3.org/TR/xmlschema11-1/;

WSDL - мова визначення інтерфейсу веб-сервісу (англ. Web Services Description Language), заснована на XML, що описує функціональність веб-сервісу і спосіб доступу до нього через протокол SOAP;

атрибут XML-документа - іменована уточнювальна характеристика елемента XML, що складається з пари "назва" = "значення". Зазначається під час визначення елемента XML у тезі, що відкриває;

вузол е-взаємодії - програмне або програмно-технічне рішення, задіяне в передаванні електронних повідомлень, що містять інформацію-запит та/або інформацію-відповідь, з метою забезпечення е-взаємодії між отримувачем та постачальником, зокрема веб-клієнт, встановлений в інформаційній системі отримувача шлюз безпечного обміну (далі - шлюз безпечного обміну отримувача), встановлений в інформаційній системі постачальника шлюз безпечного обміну (далі - шлюз безпечного обміну постачальника), веб-сервіс;

е-взаємодія - передання інформації-запиту від отримувача до постачальника та передання інформації-відповіді від постачальника до отримувача - електронна інформаційна взаємодія;

електронне повідомлення - сукупність електронних даних у визначеному форматі, яка може бути передана між вузлами е-взаємодії, що задіяні у процесі обміну даними, та є носієм закодованої інформації (інформації-запиту або інформації-відповіді). СЕВДЕІР-повідомлення та захищене транспортне повідомлення є різновидами електронного повідомлення;

елемент XML-документа - іменована структурна одиниця мови XML, обмежена тегом, що відкриває, і тегом, що закриває. Може повторюватися, включати інші елементи XML, коментарі, текстове значення та атрибути XML;

захищене транспортне повідомлення - електронне повідомлення, яке передається між шлюзами безпечного обміну та містить (інкапсулює) СЕВДЕІР-повідомлення у зашифрованому за ДСТУ ГОСТ 28147:2009 вигляді з накладеною електронною печаткою;

інформація-відповідь - інформація, яка передається у відповідь на запит отримувача;

інформація-запит - інформація, яка формується внутрішньою (відомчою) інформаційною системою отримувача з метою отримання (пошуку) необхідної інформації (інформації-відповіді) від постачальника (його е-ресурсів або інших інформаційних систем) у режимі "запит-відповідь" або з метою передання корисної для постачальника інформації у режимі "сповіщення-підтвердження отримання";

обмін даними - процес обміну електронними повідомленнями між веб-клієнтом та веб-сервісом з метою передання інкапсульованої в них інформації-запиту й інформації-відповіді та забезпечення е-взаємодії;

простір імен - необов'язковий кваліфікатор елементів XML та атрибутів XML, що використовується для забезпечення унікальності ідентифікаторів та запобігання конфлікту назв елементів та атрибутів XML в одному або кількох пов'язаних XML-документах, особливо таких, що мають різне джерело походження.

Інші терміни вживаються у значеннях, наведених у Порядку організації електронної інформаційної взаємодії державних електронних інформаційних ресурсів, затвердженому постановою Кабінету Міністрів України від 10 травня 2018 року № 357, та Положенні про електронну взаємодію державних електронних інформаційних ресурсів, затвердженому постановою Кабінету Міністрів України від 08 вересня 2016 року № 606.

II. Формат обміну даними

1. Формат обміну даними - правила передавання та послідовність відправлених й отриманих електронних повідомлень встановленого формату, дотримання яких забезпечує обмін даними між е-ресурсами та іншими інформаційними системами, які використовують СЕВДЕІР для е-взаємодії.

2. Принципи обміну даними:

1) е-взаємодія через СЕВДЕІР передбачає формування й передавання інформації-запиту від отримувача до постачальника та формування й передавання інформації-відповіді від постачальника до отримувача за допомогою веб-клієнтів, шлюзів безпечного обміну, веб-сервісів та внутрішніх (відомчих) інформаційних систем;

2) інформація передається в таких електронних повідомленнях:

СЕВДЕІР-повідомлення (між веб-клієнтами й шлюзами безпечного обміну та між веб-сервісами й шлюзами безпечного обміну);

захищені транспортні повідомлення (між шлюзами безпечного обміну);

3) розроблені отримувачами веб-клієнти та постачальниками веб-сервіси мають підтримувати формат обміну СЕВДЕІР-повідомлень зі шлюзом безпечного обміну для використання можливостей СЕВДЕІР;

4) обмін електронними повідомленнями здійснюється з використанням протоколів прикладного рівня HTTPS та SOAP у синхронному режимі;

5) СЕВДЕІР-повідомлення, формат яких описано в розділі III цих Форматів, є SOAP-повідомленнями, які мають додаткові обов'язкові SOAP-заголовки, що ідентифікують інформаційну систему отримувача, веб-сервіс постачальника та інші параметри, необхідні для коректної маршрутизації та оброблення переданої через СЕВДЕІР інформації;

6) кожне захищене транспортне повідомлення в момент створення автоматично зашифровується шлюзом безпечного обміну з накладанням електронної печатки перед відправленням до іншого шлюзу безпечного обміну.

3. Послідовність обміну даними:

1) у процесі е-взаємодії можуть виникнути такі варіанти обміну даними між отримувачем та постачальником:

успішна транзакція (звичайний режим роботи; відбувається е-взаємодія між отримувачами та постачальниками через СЕВДЕІР);

неуспішна транзакція (неповне проходження інформації-запиту або інформації-відповіді між усіма вузлами е-взаємодії; е-взаємодія не відбувається, генерується повідомлення з помилкою);

2) успішна транзакція передбачає такі кроки (етапи) передання електронних повідомлень:

СЕВДЕІР-повідомлення з інформацією-запитом від веб-клієнта до шлюзу безпечного обміну отримувача;

захищене транспортне повідомлення з інформацією-запитом від шлюзу безпечного обміну отримувача до шлюзу безпечного обміну постачальника;

СЕВДЕІР-повідомлення з інформацією-запитом від шлюзу безпечного обміну постачальника до веб-сервісу;

СЕВДЕІР-повідомлення з інформацією-відповіддю від веб-сервісу до шлюзу безпечного обміну постачальника;

захищене транспортне повідомлення з інформацією-відповіддю від шлюзу безпечного обміну постачальника до шлюзу безпечного обміну отримувача;

СЕВДЕІР-повідомлення з інформацією-відповіддю від шлюзу безпечного обміну отримувача до веб-клієнта;

3) неуспішна транзакція означає, що на одному з етапів передання електронних повідомлень виникає помилка, звичайний режим обміну повідомленнями переривається й інформація про цю помилку направляється до веб-клієнта у відповідному повідомленні. Повідомлення з помилкою можуть бути створені вузлами е-взаємодії у таких ситуаціях:

шлюзом безпечного обміну отримувача:

під час отримання СЕВДЕІР-повідомлення з інформацією-запитом від веб-клієнта;

під час отримання захищеного транспортного повідомлення з інформацією-відповіддю від шлюзу безпечного обміну постачальника;

у разі відсутності з'єднання зі шлюзом безпечного обміну постачальника;

шлюзом безпечного обміну постачальника:

під час отримання захищеного транспортного повідомлення з інформацією-запитом від шлюзу безпечного обміну отримувача;

під час отримання СЕВДЕІР-повідомлення з інформацією-відповіддю від веб-сервісу;

у разі відсутності з'єднання з веб-сервісом;

веб-сервісом під час отримання СЕВДЕІР-повідомлення з інформацією-запитом від шлюзу безпечного обміну постачальника;

за неможливості створити захищене транспортне повідомлення на шлюзах безпечного обміну отримувача та/або постачальника через проблеми шифрування та/або накладання електронної печатки на таке повідомлення;

4) розроблені веб-клієнти мають вміти обробляти повідомлення типу SOAP Fault від шлюзів безпечного обміну.

4. Ідентифікатори об'єктів у СЕВДЕІР:*

__________
* Тільки для цілей цього пункту ідентифікатори об'єктів подаються у вигляді рядка символів формату T:C1/C2/..., де T - тип об'єкта, C1, C2 тощо - коди компонентів ідентифікатора. Під час обміну повідомленнями та в конфігураційних файлах ідентифікатори мають подаватися у форматі XML (пункт 5 розділу III цих Форматів).

1) усі об'єкти в СЕВДЕІР мають глобально унікальні ідентифікатори, які складаються з типу об'єкта та послідовності ієрархічних кодів. Глобально унікальні ідентифікатори для різних типів об'єктів створюються за єдиними правилами.

Усі ідентифікатори починаються з коду, який ідентифікує середовище СЕВДЕІР:

промислове середовище СЕВДЕІР - SEVDEIR;

тестове середовище СЕВДЕІР - SEVDEIR-TEST;

навчальне середовище СЕВДЕІР - SEVDEIR-TR.

Ці коди - єдині, які мають бути глобально унікальними. Всі інші частини ідентифікаторів перебувають під керуванням конкретного середовища СЕВДЕІР;

2) учасник СЕВДЕІР - об'єкт СЕВДЕІР, що репрезентує зареєстрованого в СЕВДЕІР держателя (розпорядника) або адміністратора е-ресурсу як MEMBER:середовище_СЕВДЕІР/код_класу_учасника/код_учасника.

Ідентифікатор учасника СЕВДЕІР складається з:

коду відповідного середовища СЕВДЕІР;

коду класу учасника (наприклад, для державних організацій - GOV, для приватних підприємств - COM);

коду учасника, який унікально ідентифікує учасника в межах його класу. Використовується код в Єдиному державному реєстрі юридичних осіб, фізичних осіб - підприємців та громадських формувань.

Наприклад: MEMBER:SEVDEIR/GOV/12345678 ідентифікує зареєстровану в промисловому середовищі СЕВДЕІР (SEVDEIR) державну організацію (GOV) за кодом у Єдиному державному реєстрі юридичних осіб, фізичних осіб - підприємців та громадських формувань (12345678);

3) підсистема - об'єкт СЕВДЕІР, що репрезентує е-ресурс або його складову, яка використовується для е-взаємодії (інформаційну систему), як SUBSYSTEM:власник_підсистеми/код_підсистеми.

Ідентифікатор підсистеми складається з:

ідентифікатора учасника СЕВДЕІР, який є держателем (розпорядником) підсистеми;

коду підсистеми, який створюється під час реєстрації е-ресурсу в СЕВДЕІР і формується відповідно до регламенту роботи СЕВДЕІР.

Наприклад: SUBSYSTEM:SEVDEIR/GOV/12345678/highsecurity ідентифікує підсистему з кодом highsecurity, яка належить до учасника СЕВДЕІР з попереднього прикладу (MEMBER:SEVDEIR/GOV/12345678);

4) сервіс - об'єкт СЕВДЕІР, що репрезентує веб-сервіс постачальника як SERVICE:постачальник_сервісу/код_сервісу/версія_сервісу.

Ідентифікатор веб-сервісу складається з:

ідентифікатора постачальника сервісу (учасник СЕВДЕІР або підсистема);

коду сервісу, який учасник СЕВДЕІР обирає самостійно з урахуванням вимог іменування сервісів відповідно до регламенту роботи СЕВДЕІР;

версії сервісу (необов'язково. Настійно рекомендовано зазначати для розрізнення технічно несумісних версій того самого сервісу).

Наприклад: SERVICE:SEVDEIR/GOV/12345678/highsecurity/GetMyFieldFromRegistry1/v1 ідентифікує сервіс GetMyFieldFromRegistry1 (версія v1), який надається підсистемою SUBSYSTEM:SEVDEIR/GOV/12345678/highsecurity.

III. Формат електронного повідомлення

1. Формат електронного повідомлення (СЕВДЕІР-повідомлення) - правила формування визначеного цими Форматами SOAP-повідомлення, що передається між веб-клієнтом (веб-сервісом) та відповідним шлюзом безпечного обміну, підключеним до СЕВДЕІР.

2. Веб-клієнти та веб-сервіси обмінюються зі шлюзами безпечного обміну електронними повідомленнями, які відповідають формату СЕВДЕІР-повідомлення.

СЕВДЕІР-повідомлення має вигляд SOAP-конверта, який складається з блоку опису просторів імен, блоку заголовків СЕВДЕІР-повідомлення (всередині блоку SOAP-ENV:Header), які мають додаткові обов'язкові SOAP-заголовки, та блоку структурованої інформації (всередині блоку SOAP-ENV:Body), тобто містять корисну інформацію у структурованому вигляді.

СЕВДЕІР-повідомлення має такий узагальнений вигляд:

3. Блок опису просторів імен СЕВДЕІР-повідомлення.

Кореневий XML-елемент СЕВДЕІР-повідомлення (SOAP-ENV:Envelope) містить оголошення всіх просторів імен (атрибут XML-документа xmlns), які використовуються в XML-документі СЕВДЕІР-повідомлення.

Обов'язковими є такі простори імен:

__________
** Скорочені префікси постачальники обирають самостійно. Для цілей цих Форматів використано наведені в таблиці префікси.

СЕВДЕІР-повідомлення із заповненим блоком опису просторів імен має такий узагальнений вигляд:

4. Блок заголовків СЕВДЕІР-повідомлення та правила їх заповнення.

SOAP-заголовки СЕВДЕІР-повідомлення є обов'язковими, містять адресну інформацію про учасників, веб-сервіс та інші параметри, необхідні для передання повідомлення через СЕВДЕІР.

Вимоги до блоку заголовків СЕВДЕІР-повідомлення, які мають бути додані до елемента SOAP-ENV:Header як дочірні елементи:

__________
*** Має бути глобальним (унікальний номер запису в Єдиному державному демографічному реєстрі, реєстраційний номер облікової картки платника податків, серія та номер паспорта) або локальним (але зрозумілим постачальнику, який отримує та обробляє запит) ідентифікатором.
Для унікального номера запису в Єдиному державному демографічному реєстрі: IdType має рядкове значення UNZR, а IdCode - значення унікального номера запису (повна форма з дефісом) особи (наприклад, UNZR:19801231-04031).
Для реєстраційного номера облікової картки платника податків: IdType має рядкове значення IPN, а IdCode - значення реєстраційного номера (наприклад, IPN:3081421241).
Для серії та номера паспорта громадянина України: IdType має рядкове значення UAPASS, а IdCode - значення серії та номера документа без пробілу (наприклад, UAPASS:КМ256432).
Інші типи ідентифікаторів та правила їх заповнення визначаються постачальником веб-сервісу та мають бути зазначені у відповідній настанові користувача веб-сервісу.

СЕВДЕІР-повідомлення із заповненим блоком заголовків СЕВДЕІР-повідомлення має такий узагальнений вигляд:

5. Ідентифікатори об'єктів у блоці заголовків СЕВДЕІР-повідомлення ****.

__________
**** У цьому пункті описано формати XML-структурованих даних для ідентифікаторів об'єктів (пункт 4 розділу II цих Форматів).

Структуру даних та елементів розміщено в просторі імен http://x-road.eu/xsd/identifiers.

У загальному випадку заголовок схеми має такий вигляд:

Складний тип XRoadIdentifierType є основою для всіх інших типів ідентифікаторів (успадкованих через restriction). Він містить всі поля, які можуть бути в різних типах ідентифікаторів. Атрибут objectType містить тип ідентифікатора та може бути використаний, наприклад, для розрізнення між ідентифікатором учасника СЕВДЕІР та ідентифікатором підсистеми, не вдаючись до перевірки наявності кожного з полів:

XRoadObjectType перелічує всі можливі значення атрибуту objectType:

Елементи та атрибути, які використовуються в XRoadIdentifierType:

Складний XML-тип XRoadClientIdentifierType використовується клієнтами сервісів для представлення конкретних типів ідентифікаторів, а саме учасників СЕВДЕІР та підсистем у такому вигляді:

XRoadServiceIdentifierType використовується для представлення ідентифікаторів сервісів:

6. Блок структурованої інформації.

Основним завданням СЕВДЕІР-повідомлень є передавання структурованої та закодованої у них корисної інформації (інформації-запиту та/або інформації-відповіді). Для збереження структурованої інформації всередині СЕВДЕІР-повідомлення має використовуватися блок структурованої інформації, який має бути єдиним дочірнім XML-елементом у SOAP-ENV:Body та бути базовим батьківським елементом для всіх інших субелементів, що містять структуровану інформацію.

Блок структурованої інформації має кваліфікований XML-ідентифікатор (визначений постачальником простір імен з урахуванням вимог щодо формування просторів імен відповідно до регламенту роботи СЕВДЕІР).

СЕВДЕІР-повідомлення має такий узагальнений вигляд із заповненим блоком структурованої інформації:

7. Повідомлення про помилку, яке виникає за неуспішної транзакції, є звичайним SOAP Fault повідомленням. Повідомлення про помилку містить інформацію про помилку (код помилки, опис помилки тощо).

8. Шлюзи безпечного обміну можуть приймати та передавати СЕВДЕІР-повідомлення із вкладеними файлами.

З метою організації створення та підвищення семантичної інтероперабельності між постачальниками та отримувачами, які використовують СЕВДЕІР, настійно рекомендується запобігати передаванню неструктурованої інформації у вигляді файлових вкладень будь-яких типів. Будь-яка інформація числового, текстового та векторного характеру має передаватися у структурованому вигляді в блоці структурованої інформації у вигляді впорядкованих та типізованих XML-структур даних.

9. Усім учасникам СЕВДЕІР слід вказувати кодування символів XML-документа, використовуючи параметр charset HTTP-заголовку Content-Type. У разі якщо параметр charset не визначений у HTTP-заголовку Content-Type, шлюз безпечного обміну вважає, що використовується кодування UTF-8.

XML-СХЕМА
для СЕВДЕІР-повідомлень

XML-СХЕМА
ідентифікаторів об'єктів СЕВДЕІР