Визначення

UAPI - це WEB API-сервіс.

UAPI-метод - це програмний ресурс UAPI, доступ до якого виконується по протоколу HTTP. UAPI-метод призначений для обробки UAPI-запитів від UAPI-клієнтів. Кожний UAPI-метод має універсальний локатор ресурсу (URL), який для UAPI-клієнтів відомий як "URL-адреса кінцевої точки (endpoint)".

UAPI-сервер - це спеціалізований вебсервер. Він забезпечує доступ до UAPI-методів та їх функціональність.

UAPI-клієнт - це програмний інструмент (застосунок,додаток, сайт), який використовується його користувачем для взаємодії з UAPI-сервером. Він значною мірою усуває складність написання коду для підключення до UAPI-сервера, дозволяючи користувачу визначати та виконувати UAPI-запити й перевіряти UAPI-відповіді у зручному інтерфейсі

Ресурс - це дані, з якими працюють UAPI-методи. Ресурсом для UAPI-методу, якщо це не оговорено детально, є:

Об'єкт: Унікальний ідентифікатор об'єкта та набір його власних параметрів

Група об'єктів: Набір унікальних ідентифікаторів об'єктів з наборами їх власних параметрів

Файл: Файл певного формату та вмісту

Об'єкти UAPI:

карта (card),

рахунок (account),

ліміт карти (card limit),

власник рахунку (customer),

власник карти (cardholder),

файл (file),

та т.і.

UAPI-запит - структуроване HTTP-повідомлення UAPI-клієнта UAPI-серверу на адресу певного UAPI-методу. UAPI-запит зазвичай містить кілька ключових компонентів, що забезпечує його правильну інтерпретацію та виконання UAPI-сервером та UAPI-методом:

URL-адреса кінцевої точки: Конкретний універсальний локатор ресурсу (URL), який ідентифікує UAPI-сервер, UAPI-метод, з якими UAPI-клієнт хоче взаємодіяти.
В окремих випадках URL-адреса кінцевої точки може містити унікальний ідентифікатор ресурсу, з яким має працювати UAPI-метод. Наприклад, [http://nsuapi2.ukrcard.com.ua/uapi-2.0/v1/cards/1101000000101665912/baseparam/status/]. Тут ідентифікатором ресурсу є унікальний ідентифікатор платіжної карти у платіжній структурі УКРКАРТ 1101000000101665912, так званий Panid.

Метод HTTP: Вказує на тип дії, яку UAPI-метод має виконати для UAPI-клієнта:

Метод HTTP	Призначення методу HTTP
GET	Надати дані ресурсу.
POST	Створити новий ресурс.
PATCH	Частково оновити дані існуючого ресурсу.
PUT	Створити новий ресурс або оновити існуючий.
DELETE	Видалити ресурс.

Заголовки: Вони надають додатковий контекст щодо UAPI-запиту, такий як облікові дані автентифікації (ідентифікатор UAPI-клієнта,ключі API, токени), формат даних, що надсилаються (як правило, JSON), та формат, який клієнт прийме у відповіді (як правило, JSON) та таке інше.

Тіло запиту: Для таких методів HTTP, як POST та PUT, цей розділ містить самі дані, як правило у форматі JSON, які потрібно надіслати на UAPI-сервер.

Параметри: Це необов'язкові елементи (наприклад, параметри запиту в URL), що використовуються для фільтрації, сортування або обмеження даних у відповіді.

У таблиці нижче надається деталізований опис застосування методів HTTP в UAPI:

Метод HTTP	Застосування методу HTTP в UAPI
GET	Надати дані ресурсу. Передача даних: У GET-запитах тіло запиту не передбачається. Дані UAPI-клієнтом UAPI-методу передаються безпосередньо в URL або як параметри запиту - в URL після знаку питання "?". Якщо у GET-запиті тіло запиту присутнє, то воно UAPI-методом не приймається (ігнорується) і не оброблюється. Безпека даних: Дані UAPI-клієнтом UAPI-методу передаються в URL, що для конфіденційної інформації НЕ ПІДХОДИТЬ. [Ідемпотентність]: GET-метод* є ідемпотентним. Стан UAPI-сервера після повторної обробки GET-запиту не змінюється. Якщо UAPI-клієнт один і той ж GET_-запит_ відправить декілька разів, то UAPI-метод не буде вважати це помилкою і усі ці запити обробить так, як і перший. Асоціація з SQL: GET-запит відповідає SQL-операції SELECT - вибірка даних вказаного у запиті ресурсу чи ресурсів. REST API: GET-запит в UAPI-методах повністю відповідають REST Full специфікації.
POST	Створити новий ресурс. Передача даних: У POST-запитах, як правило, передбачається тіло запиту. Дані UAPI-клієнтом UAPI-методу передаються у тілі запиту. Якщо у POST-запиті тіло запиту передбачається, то воно UAPI-методом приймається і оброблюється. Безпека даних: Конфіденційні дані UAPI-клієнтом UAPI-методу обов'язково передаються у тілі запиту, а не конфіденційні дані можуть передаватися або у тілі запиту або безпосередньо в URL, як і в GET-запитах. [Ідемпотентність]: Зазвичай POST-метод* вважається неідемпотентним, але в UAPI-методі може бути реалізований як ідемпотентний. Стан UAPI-сервера після успішної обробки POST-запиту змінюється. Якщо UAPI-клієнт декілька разів відправить один і той ж POST-запит або інший POST-запит з тими ж самими даними, то UAPI-метод або буде вважати це помилкою або обробка таких POST-запитів закінчиться помилкою або вони будуть успішно оброблені, що призведе до створення декількох екземплірів одного і того ж ресурсу. Як правило, UAPI-методи передбачають можливість повторення POST-запитів, вважають це помилкою і в UAPI-відповіді про це повідомляють. Асоціація з SQL: POST-запит відповідає SQL-операції INSERT - створення нового ресурсу. REST API: Хоча POST UAPI-методи, як правило, асоціюються з створенням ресурсу чи ресурсів, але деякі з них можуть працювати, як методи PATCH, PUT чи DELETE. Така поведінка UAPI-методів у їх описі обумовлюється окремо.
PATCH	Частково оновити дані існуючого ресурсу. Передача даних: У PATCH-запитах, як правило, передбачається тіло запиту. Дані UAPI-клієнтом UAPI-методу передаються у тілі запиту. Якщо у PATCH-запиті тіло запиту передбачається, то воно UAPI-методом приймається і оброблюється. Безпека даних: Конфіденційні дані UAPI-клієнтом UAPI-методу обов'язково передаються у тілі запиту, а не конфіденційні дані можуть передаватися або у тілі запиту або безпосередньо в URL, як і в GET-запитах. [Ідемпотентність]: Зазвичай PATCH-метод вважається неідемпотентним, але в UAPI-методі може бути реалізований як ідемпотентний. Стан UAPI-сервера після успішної обробки PATCH-запиту змінюється. Якщо UAPI-клієнт декілька разів відправить один і той ж PATCH-запит або інший PATCH-запит з тими ж самими даними, то UAPI-метод або буде вважати це помилкою або обробка таких PATCH-запитів закінчиться помилкою або вони будуть успішно оброблені, що призведе до повторної зміни даних ресурсу. Як правило, UAPI-методи передбачають можливість повторення PATCH-запитів але не вважають це помилкою, повторно успішно оновлюють дані ресурсів і в UAPI-відповіді про повторне їх оновлення НЕ повідомляють. Але є виключення, коли UAPI-метод не може повторно оновити ресурс, бо на момент оновлення він іншим UAPI-методом, наприклад, видалений обо змінений так, що його повторна зміна є неможливою. У такому разі UAPI-метод відправляє UAPI-відповідь з помилкою_._ Асоціація з SQL: PATCH-запит відповідає SQL-операції UPDATE - зміна даних існуючого ресурсу. REST API: Хоча PATCH UAPI-методи, як правило, асоціюються з зміною даних існуючого ресурсу чи ресурсів, але деякі з них можуть працювати, як методи POST чи PUT. Така поведінка UAPI-методів у їх описі обумовлюється окремо.
PUT	Створити новий ресурс або оновити існуючий. Передача даних: У PUT-запитах, як правило, передбачається тіло запиту. Дані UAPI-клієнтом UAPI-методу передаються у тілі запиту. Якщо у PUT-запиті тіло запиту передбачається, то воно UAPI-методом приймається і оброблюється. Безпека даних: Конфіденційні дані UAPI-клієнтом UAPI-методу обов'язково передаються у тілі запиту, а не конфіденційні дані можуть передаватися або у тілі запиту або безпосередньо в URL, як і в GET-запитах. [Ідемпотентність]: Зазвичай PUT-метод вважається ідемпотентним, але в UAPI-методі може бути реалізований як неідемпотентний. Стан UAPI-сервера після успішної обробки PUT-запиту змінюється. Якщо UAPI-клієнт декілька разів відправить один і той ж PUT-запит або інший PUT-запит з тими ж самими даними, то UAPI-метод або буде вважати це помилкою або обробка таких PUT-запитів закінчиться помилкою або вони будуть успішно оброблені, що призведе до створення декількох екземплірів одного і того ж ресурсу або до повторної зміни даних ресурсу. Як правило, UAPI-методи передбачають можливість повторення PUT-запитів але не вважають це помилкою, повторно успішно створюють нові ресурси чи оновлюють дані ресурсів і в UAPI-відповіді про повторне їх створення оновлення НЕ повідомляють. Але є виключення, коли UAPI-метод не може повторно створити ресурс, бо такий ресурс є унікальним і вже створений; або коли на момент оновлення цей ресурс іншим UAPI-методом, наприклад, видалений обо змінений так, що його повторна зміна є неможливою. У такому разі UAPI-метод відправляє UAPI-відповідь з помилкою_._ Асоціація з SQL: PUT-запит відповідає SQL-операції MERGE - зміна даних існуючого ресурсу. REST API: Хоча PUT UAPI-методи, як правило, асоціюються з створенням нового ресурсу або зміною даних існуючого ресурсу, але деякі з них можуть працювати, як методи GET, POST,PATCH чи DELETE. Така поведінка UAPI-методів у їх описі обумовлюється окремо.
DELETE	Видалити ресурс. Передача даних: У DELETE-запитах тіло запиту не передбачається. Дані UAPI-клієнтом UAPI-методу передаються безпосередньо в URL або як параметри запиту - в URL після знаку питання "?". Якщо у DELETE-запиті тіло запиту присутнє, то воно UAPI-методом не приймається (ігнорується) і не оброблюється. Безпека даних: Дані UAPI-клієнтом UAPI-методу передаються в URL, що для конфіденційної інформації НЕ ПІДХОДИТЬ. Метод DELETE є небезпечним, т.я. змінює стан сервера, видаляючи дані. [Ідемпотентність]: Зазвичай DELETE-метод вважається ідемпотентним, але в UAPI-методі може бути реалізований як неідемпотентний. Стан UAPI-сервера після успішної обробки DELETE-запиту змінюється. Якщо UAPI-клієнт декілька разів відправить один і той ж DELETE-запит або інший DELETE-запит з тими ж самими даними, то UAPI-метод або буде вважати це помилкою або обробка таких DELETE-запитів закінчиться помилкою або вони будуть успішно оброблені, що призведе до фіктивного видалення одного і того ж ресурсу декілька разів. Як правило, UAPI-методи передбачають можливість повторення DELETE-запитів але не вважають це помилкою і в UAPI-відповіді про їх повторення НЕ повідомляють. Але є виключення, коли UAPI-метод не може повторно видалити ресурс бо такий ресурс вже був видалений раніше. У такому разі UAPI-метод відправляє UAPI-відповідь з помилкою_._ Асоціація з SQL: DELETE-запит відповідає SQL-операції DELETE - зміна даних існуючого ресурсу. REST API: DELETE-запити в UAPI-методах повністю відповідають REST Full специфікації.

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

UAPI-відповідь - структуроване HTTP-повідомлення UAPI-методу UAPI-клієнту. UAPI-відповідь може містити запитувані UAPI-клієнтом дані, дані підтвердження успіху обробки даних або повідомлення про помилку у даних UAPI-запиту або повідомлення про помилку, що виникла при виконанні UAPI-запиту. UAPI-відповідь містить такі компоненти:

Код відповіді: Є ідентифікатором стану обробки UAPI-запиту UAPI-методом. Розміщується у першому рядку HTTP-повідомлення. Наприклад: HTTP/1.1 200 OK або HTTP/1.1 404 Not Found

Заголовки: Вони надають додатковий контекст щодо UAPI-відповіді, такий як облікові дані автентифікації (ключі API, токени), формат даних, що надсилаються (наприклад, JSON), та формат, який клієнт прийме у відповіді та таке інше.

Тіло відповіді: цей розділ містить самі дані відповіді, які має отримати UAPI-клієнт, як правило у форматі JSON.

UAPI-операція — кожний успішно виконаний UAPI-запит реєструється процесинговим центром, як окрема успішна UAPI-операція. Успішні UAPI-операції разом з усіма іншими зареєстрованими процесинговим центром операціями включаються до чергового файлу "Виписка операцій процесингового центру (Extract)", що відправляється фінансовій установі емітента та\чи еквайра.

Картковий бек-офіс (Card back office,CBO) - це комплекс програмних засобів, який автоматизує повний цикл емісії та обслуговування карткових продуктів:

Емісія фізичних/віртуальних карт

Ведення карткових рахунків,

Встановлення лімітів,

Тарифікація,

Формування звітів,

Обслуговування еквайрингу,

Взаємодія з процесинговим центром:

Rest API(онлайн): авторизація фінансових транзакцій, що надходять до процесингового центру,

UAPI(онлайн): відправка до процесингового центру оновлених даних карт та рахунків, зарахування коштів на карткові рахунки та списання коштів з карткових рахунків, отримання від процесингового центру поточних даних карт та рахунків,

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

Extract(оффлайн): отримання від процесингового центру файлів з даними для обліку зареєстрованих транзакцій та даними для розрахунків з платіжними системими.

Можливі конфігурації карткового бек-офісу фінансового інституту (установи):

№ п/п	Конфігурація карткового бек-офісу	Характеристика карткового бек-офісу у його взаємодії з процесинговим центром
1	Completely own back office (СBO1)	- Власником карткового бек-офісу є фінансовий інститут - Функціонує на власних потужностях фінансового інституту. - Взаємодія з процесинговим центром: - Rest API(онлайн), - UAPI(онлайн), - Extract(оффлайн) - Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента
2	Own back office BCZCard (СBO2)	- Власником карткового бек-офісу BCZCard є УКРКАРТ - Функціонує на власних потужностях фінансового інституту. - Взаємодія з процесинговим центром: - UAPI(онлайн), - Refresh(оффлайн), - Extract(оффлайн) - Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента
3	Own back office in combi with BCZConn (СBO3). Наприклад: "АБС Б2"+BCZConn	- Власником бек-офісу (наприклад, "АБС Б2") є сам фінансовий інститут. Цей бек-офіс функціонує на власних потужностях фінансового інституту. - Власником застосунку BCZConn є УКРКАРТ. Він функціонує на власних потужностях УКРКАРТ. - Взаємодія бек-офісу фінансового інституту з процесинговим центром: - UAPI(онлайн), - Refresh(оффлайн): через BCZConn, - Extract(оффлайн): через BCZConn - Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента

№ п/п

Конфігурація карткового бек-офісу

Характеристика карткового бек-офісу у його взаємодії з процесинговим центром

Completely own back office (СBO1)

- Власником карткового бек-офісу є фінансовий інститут

- Функціонує на власних потужностях фінансового інституту.

- Взаємодія з процесинговим центром:

- Rest API(онлайн),

- UAPI(онлайн),

- Extract(оффлайн)

- Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента

Own back office BCZCard (СBO2)

- Власником карткового бек-офісу BCZCard є УКРКАРТ

- Функціонує на власних потужностях фінансового інституту.

- Взаємодія з процесинговим центром:

- UAPI(онлайн),

- Refresh(оффлайн),

- Extract(оффлайн)

- Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента

Own back office in combi with BCZConn (СBO3). Наприклад: "АБС Б2"+BCZConn

- Власником бек-офісу (наприклад, "АБС Б2") є сам фінансовий інститут. Цей бек-офіс функціонує на власних потужностях фінансового інституту.

- Власником застосунку BCZConn є УКРКАРТ. Він функціонує на власних потужностях УКРКАРТ.

- Взаємодія бек-офісу фінансового інституту з процесинговим центром:

- UAPI(онлайн),

- Refresh(оффлайн): через BCZConn,

- Extract(оффлайн): через BCZConn

- Взаємодія з клієнтами через WEB\Mobile APP застосунок емітента