> For the complete documentation index, see [llms.txt](https://doc.ob.ukrgasbank.com/lK1gBsaUtPKuTrcrSKw3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ob.ukrgasbank.com/lK1gBsaUtPKuTrcrSKw3/posibnik-dlya-pochatku-roboti/oglyad-api.md). # Огляд API Усі сервіси API, в тому числі спеціалізовані, побудовано на архітектурі Representational State Transfer Service (REST), яка базується на стандартному HTTP та зрозумілому для читання і запису форматі JavaScript Object Notation (JSON). ## HTTP-методи Усі сервіси доступні через API з використанням HTTPS-методів на основі REST: * **GET:** Читає ресурс і повертає його; * **POST:** Створює новий ресурс; * **PUT:** Зберігає надану сутність за вказаним URI; * **DELETE:** Видаляє ресурс, ідентифікований URI. ## Версіонування Номер версії API завжди включається у виклик API. * Версія API повинна починатися з «v», наприклад: /v1.0.0/ * Версія API повинна вказувати щонайменше основну (major) версію API (наприклад, /v1/). Вказівка на мінорні та патч-версії не є обов’язковою. {% hint style="info" %} Якщо ви надсилаєте запит із /v1/, він буде оброблений як найвища доступна версія цього API у межах вашого застосунку. {% endhint %} Нові версії спеціалізованих API залежатимуть від нових затверджених специфікацій Національним банком України та релізів специфікацій Berlin Group. ## Коди HTTP-відповідей та помилок Разом із кодами статусів HTTP також повертаються коди помилок для полегшення обробки виняткових ситуацій сторонніми надавачами платіжних послуг (TPP). {% hint style="success" %} Усі комбінації статусів та кодів помилок відповідають специфікаціям затвердженим Національним банком України та стандартам Berlin Group. {% endhint %} Помилки завжди повертаються у такому форматі: ```json "apiClientMessages": [ { "category": "ERROR", //can be either ERROR or WARNING "code": "FORMAT_ERROR", //error code "text": "Invalid request for some reason" //explanation or error code } ``` Наведено перелік неспецифічних кодів помилок сервісу, що повертаються в сервісах API. | Сценарiй | Статус — Код помилки | | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | | Токен пісочниці (sandbox) використано для робочого (live) API | 401 — TOKEN\_INVALID | | Відсутній токен | 401 — AUTHENTICATION\_MISSING | | Операція (з конкретною версією) виходить за межі дозволів (scopes) застосунку | 403 — OPERATION\_NOT\_ALLOWED | | Операція (з конкретною версією) не надається провайдером або провайдер більше не активний | 403 — OPERATION\_NOT\_ALLOWED | | Сервіс недоступний для зазначеного PSU через незалежне від каналу блокування з боку ASPSP | 403 — SERVICE\_BLOCKED | | TPP досяг ліміту, встановленого банком для продукту | 429 — OPERATION\_NOT\_ALLOWED | | Помилка з'єднання | 503 — SERVICE\_UNAVAILABLE | | Перевищено час очікування з'єднання | 504 — GATEWAY\_TIMEOUT | | Перевищено час очікування відповіді | 504 — RESPONSE\_TIMEOUT | | Зазначений ASPSP не може зіставити PSU-ID | 401 — PSU\_CREDENTIALS\_INVALID | | Неіснуючий URL (зокрема відсутній або неочікуваний параметр шляху) | 404 — RESOURCE\_UNKNOWN | | Неочікуваний або неіснуючий HTTP-метод | 405 — SERVICE\_INVALID | | Неочікуваний заголовок Content-Type (не `application/json`) | 415 — SERVICE\_INVALID | | Неочікуваний заголовок Accept (не `application/json`) | 406 — REQUESTED\_FORMATS\_INVALID | | Значення параметра запиту не відповідає типу даних в OAS | 400 — PARAMETER\_NOT\_CONSISTENT | | Відсутній параметр запиту | 400 — PARAMETER\_NOT\_CONSISTENT | | Неочікуваний параметр запиту | 400 — PARAMETER\_NOT\_SUPPORTED | | TPP намагається створити згоду (consent) з validTo надто далеко в майбутньому або запитує інформацію про рахунок за період, неприйнятний для ASPSP | 400 — PERIOD\_INVALID | | Значення заголовка (крім Accept і Content-Type) АБО поля в тілі запиту не відповідає типу чи довжині даних в OAS або відсутнє | 400 — FORMAT\_ERROR | | Відсутній заголовок (крім Accept і Content-Type) АБО поле в тілі запиту | 400 — FORMAT\_ERROR | | Відсутнє тіло запиту або JSON має некоректний формат | 400 — FORMAT\_ERROR | | TLS- або підписний сертифікат недійсний (пов'язаний з іншим TPP чи застосунком) | 401 — CERTIFICATE\_INVALID | | Сертифікат відкликано | 401 — CERTIFICATE\_REVOKED | | Термін дії сертифіката минув | 401 — CERTIFICATE\_EXPIRED | | Відсутній підпис | 401 — SIGNATURE\_MISSING | | Недійсний підпис | 401 — SIGNATURE\_INVALID | | Термін дії токена минув | 401 — TOKEN\_EXPIRED | | Система не може ідентифікувати TPP за токеном АБО тип токена не Bearer Token | 401 — TOKEN\_UNKNOWN | ## Безпека API ### Токени API захищені за допомогою механізму OAuth 2.0 Client Credentials Grant, що забезпечує надійний спосіб автентифікації.: `POST` `/auth/realms/participants/protocol/openid-connect/token` Запит API повинен отримати access token зі спеціального endpoint. {% code overflow="wrap" %} ``` curl --location 'https://portal.ob.ukrgasbank.com/auth/realms/participants/protocol/openid-connect/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=openid' \ --data-urlencode 'client_id=6f2be15d-a073-4652-8d9b-f7167c607bcf' \ --data-urlencode 'client_secret=I1OXRIkVwSSvEbd8HQh5aDCYCCLqtYqr' ``` {% endcode %} У наступних викликах API отриманий токен необхідно розміщувати в заголовку ('Authorization' header). TPP може отримати Client secret та Client ID у меню: Applications > Live Environment/Sandbox > {назва застосунку TPP}:
### Безпека транспортного рівня (TLS) Зв’язок між TPP та OBP завжди захищено за допомогою протоколу TLS версії 1.2 або вище. TLS (Transport Layer Security) - це криптографічний протокол, який використовується для захисту передавання даних у мережі. Він забезпечує безпечне та зашифроване з’єднання між вами та нашими API. ### Перевірка сертифікатів Окрім TLS та автентифікації на основі токенів, Платформа авторизує кожен виклик API, перевіряючи, що TLS сертифікат та сертифікат підпису, які використовує клієнт: * підписані довіреним ЦС (mTLS); * належать ідентифікованому TPP та ідентифікованому клієнтському додатку. Це гарантує, що TPP використовують лише власні сертифікати та що вони не прострочені; * не прострочені. Платформа також періодично перевіряє статус відкликання сертифікатів, завантажених TPP через Developer Portal. Якщо сертифікат відкликано, виклик API завершиться з кодом помилки CERTIFICATE\_REVOKED. Коли TPP завантажує свої регуляторні сертифікати на Developer Portal, система також перевіряє їхню автентичність шляхом криптографічної верифікації підпису довіреним QTSP. ### Перевірка ролі PSD2 Для кожного виклику API Gateway також перевіряє, чи дозволяє Реєстр НБУ викликаному TPP виконувати запитувану операцію. ## Лiмiти ### Account Information Service ліміти Продукт Compliance AIS має власні специфічні обмеження, встановлені регулятором. Частота GET-запитів без присутності PSU (тобто запитів, ініційованих вашим сервером, поки PSU офлайн) не може перевищувати 4 рази на день. {% hint style="danger" %} Якщо PSU офлайн, ви не повинні включати заголовок PSU-IP-Address у ваші GET-запити. Запит без заголовка PSU-IP-Address збільшить лічильник запитів без присутності PSU на 1. Коли лічильник досягне 5, ви отримаєте специфічну помилку зі статус-кодом 429 і кодом помилки ACCESS\_EXCEEDED. {% endhint %} Ви також не зможете створити AIS-згоду з `frequencyPerDay`, більшою ніж 4. Якщо ви спробуєте створити таку згоду, отримаєте спеціальну помилку 400: ```json { "apiClientMessages": [ { "category": "ERROR", "code": "FORMAT_ERROR", "text": "Frequency per day can’t be larger than 4!" } ] } ``` Цим обмеженням регулятор прагне мінімізувати непотрібне використання персональних даних TPP та таким чином знизити ризик зловживання особистою інформацією та шахрайства, що повністю відповідає принципам GDPR. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://doc.ob.ukrgasbank.com/lK1gBsaUtPKuTrcrSKw3/posibnik-dlya-pochatku-roboti/oglyad-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.