3. Символи та позначення

Редакція OpenBanking Ukraine

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

3.1. Набори символів і типи даних

HTTP body параметри

Набір символів у межах відкритого банкінгу для параметрів, які передаються в body HTTP, закодований у UTF-8. Ця специфікація використовує лише базові елементи даних String, Boolean, ISODateTime, ISODate, UUID і Integer (з довжиною байта 32 біти) та кодові списки на основі ISO. Для кодів, визначених ISO, посилання на відповідний ISO стандарт надається на рівні відповідної специфікації.

Max35Text, Max70Text, Max140Text, Max500Text, Max1000Text, Max2000Text визначають рядки з максимальною довжиною 35, 70, 140, 500, 1000 і 2000 символів відповідно. ASPSP мають приймати наступний набір символів для рядків:

a b c d e f g h i j k l m n o p q r s t u v w x y z
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
а б в г ґ д е є ж з и і ї й к л м н о п р с т у ф х ц ч ш щ ь ю я
А Б В Г Ґ Д Е Є Ж З И І Ї Й К Л М Н О П Р С Т У Ф Х Ц Ч Ш Щ Ь Ю Я
0 1 2 3 4 5 6 7 8 9
/ - ? : ( ) . , ' + Пробіл

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

Комплексні типи даних та списки кодів визначені у відповідних специфікаціях.

Кодування даних або інформації відповідає стандартам, визначеним у специфікації протоколу HTTP. Специфічні доповнення можуть бути надані для параметрів HTTP, введених спеціально цим документом або окремими специфікаціями.

3.2. Нотації

3.2.1. Нотації для Requests

Для викликів API query-параметри, HTTP header-параметри і body-параметри визначаються в межах специфікації відкритого банкінгу наступним чином:

Атрибут	Тип	Умова	Опис
позначка атрибута	тип атрибута	умова	опис атрибута та подальші умови

«Тип» відноситься до базових або комплексних типів даних, представлених у розділі 3.1. У колонці «Умова» можуть використовуватися наступні значення при описі даних, які має надати API client:

Optional – атрибут підтримується сервером, використання є опціональним для API client. Сервер може ігнорувати параметр, якщо це зазначено в колонці «Опис».
Conditional – атрибут підтримується сервером і може бути обов’язковим згідно з:
- документацією постачальника сервера щодо підтримки відповідного API або
- певними правилами, які визначені у колонці «Опис».
Mandatory – атрибут підтримується сервером і повинен використовуватися API client.
Optional, якщо підтримується постачальником API – сервер може підтримувати цей атрибут опціонально. Якщо сервер підтримує атрибут, як зазначено у власній документації щодо відповідної послуги, клієнт може використовувати його опціонально. Якщо сервер не підтримує атрибут, запит буде відхилено, якщо він міститься.

3.2.2. Нотації для Responses

Для responses на виклики API параметри, HTTP header-параметри та body-параметри визначаються в межах відкритого банкінгу наступним чином:

Атрибут	Тип	Умова	Опис
позначка атрибута	тип атрибута	умова	опис семантики атрибута та подальші умови

«Тип» відноситься до базових або комплексних типів даних, представлених у розділі 3.1.

Наступні умови можуть бути встановлені для даних, які надаються сервером:

Optional – атрибут підтримується сервером опціонально.
Conditional – атрибут підтримується сервером за певних умов, як зазначено в колонці «Опис».
Mandatory – атрибут завжди підтримується сервером.

3.2.3. Нотації, що використовуються як для Requests, так і для Responses

Наступні додаткові умови застосовуються як до requests від API client до сервера, так і до responses від сервера до API client:

Атрибут	Тип	Умова	Опис
		`{Or`
		`Or`
		`Or}`
		`{Or – Optional`
		`Or – Optional`
		`Or – Optional}`

{Or: Перший елемент у послідовності елементів, з яких має бути включений точно один.
Or: елемент у послідовності елементів, з яких має бути включений точно один. Елемент не є ні першим, ні останнім у цій послідовності.
Or}: Останній елемент у послідовності елементів, з яких має бути включений точно один.
{Or – Optional: Перший елемент у послідовності елементів, з яких може бути включений максимум один.
Or – Optional: елемент у послідовності елементів, з яких може бути включений максимум один. Елемент не є ні першим, ні останнім у цій послідовності.
Or – Optional}: Останній елемент у послідовності елементів, з яких може бути включений максимум один.

Примітка: специфікації для відкритого банкінгу супроводжуються описом інтерфейсу API (у форматі yaml-файлу). У цих описах елементи з умовами {Or, Or, Or}, {Or – Optional, Or – Optional, Or – Optional} наразі будуть розглядатися як (суто) опціональні елементи.

3.2.4. Нотації Base64

Кодування Base64: кодування Base64 відповідно до RFC 4648.

Кодування Base64url: відповідно до RFC7515, кодування Base64 з використанням набору символів, безпечних для URL і імен файлів, визначеного в Розділі 5 RFC4648, без усіх кінцевих символів =, як дозволено в Розділі 4.2, і без включення будь-яких розривів рядків, пробілів або інших додаткових символів. Зверніть увагу, що кодування base64url для порожньої послідовності октетів є порожнім рядком (див. Додаток C RFC7515 для приміток щодо реалізації кодування base64url без додавання).

3.2.5. Поняття Транзакції

Транзакція використовується у цьому документі, а саме у фреймворку відкритого банкінгу, у наступних значеннях:

«Транзакція» як метаопис взаємодії з API для спрощення визначень у цьому документі:
- поняття транзакції охоплює взаємодії, такі як ініціаціювання платіжної операції, надання згоди користувача на надання відомостей з рахунків на взаємодію з API;
- такі транзакції ініціюються API client за допомогою відповідного запиту на ініціацію, який у цьому документі називається Transaction Initiation Request, наприклад:
  - Payment Initiation Request;
  - Establish Consent Request;
- відповідь на ці ініціації з боку ASPSP у цьому документі називається Transaction Initiation Response;
- зазвичай транзакції потребують авторизації з боку PSU шляхом застосування SCA;
- коли дані транзакції відправляються до API — створюється відповідний ресурс.
Транзакція як банківська операція на рахунку:
- запис або дія по рахунку також називаються транзакціями.

3.2.6. Поняття сервісного ресурсу

Більшість технічних POST-запитів, підтримуваних у цьому API-фреймворку, призводять до створення ресурсу з відповідним ідентифікатором ресурсу, що дозволяє API client звертатися до пов’язаного об’єкта пізніше. Одним із прикладів є Transaction Initiation Request, визначений вище, де об’єкт, збережений у адресованому ресурсі, є частиною комплексної взаємодії через API.

3.2.7. Позначення методів доступу

Усі визначення сервісів у фреймворку відкритого банкінгу супроводжуються оглядом підтримуваних методів доступу через HTTP. Ці методи доступу позначаються наступними таблицями:

Endpoints	Метод	Умова	Опис
service-endpoint	POST або GET або PUT або DELETE	Mandatory або Optional або Conditional	Опис та посилання на розділ, де знаходиться відповідний endpoint

Наступні визначення застосовуються для таких таблиць у всій документації фреймворку відкритого банкінгу:

Endpoints: назва endpoint.
Метод: HTTP-метод, який потрібно застосувати. Підтримуються HTTP-методи POST, GET, PUT і DELETE.
Умова: умова для ASPSP.
- Mandatory (обов’язково): метод доступу повинен бути наданий ASPSP.
- Optional (опціонально): метод доступу може бути наданий ASPSP.
- Conditional (умовно): метод доступу повинен бути наданий за певних умов, визначених у колонці «Опис».
  - Зверніть увагу, що умова задається відносно parent node path, тобто умова, наприклад, для методу на /service-endpoint/{resourceId} застосовується лише якщо endpoint /service-endpoint підтримується взагалі.
Опис: огляд методу та потенційно умов для методу, а також посилання на розділ документа, де метод описаний детально.