1. Вказання версії в API-запитах до ЦБД

Усі запити від майданчика до API ЦБД мають містити HTTP-заголовок Platform-Version, що відображає актуальну версію програмно-апаратного комплексу
Це дозволяє Prozorro.Sale перевіряти, що на продуктивному середовищі працює протестована версія ПЗ
- В процесі тестування буде зафіксовано версію на якій проводиться тестування. Очікується, що після релізу ПРОД почне надсилати запити з номером протестованої версії (або більше)

2. Обробка авторизації та обмежень

2.1. Використання та обробка токену доступу

Майданчик отримує токен доступу, який є сталим протягом усього періоду інтеграції (Токен майданчика не змінюється за виключенням специфічних ситуацій, про які обовʼязково відбувається окрема комунікація).

Права доступу (permissions) для виконання окремих дій визначаються на рівні самого токену та можуть бути змінені у будь-який момент (маючи обгрунтування) зі сторони Prozorro.Sale.

У разі спроби виконання дії, на яку токен не має відповідних прав (наприклад, публікація об’єкта без відповідного permission), API повертає код помилки 403 Forbidden.
Майданчик зобов’язаний реалізувати коректну обробку відповіді 403 Forbidden:
- не робити автоматизовані повторення запиту з тим самим токеном без уточнення прав
- логувати інцидент з вказанням дії, що була заборонена
- за необхідності — ініціювати звернення до служби підтримки для уточнення прав доступу у відповідному каналі Slack

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

2.2. Дотримання обмежень на кількість запитів (Rate Limits)

Майданчик має дотримуватись обмежень на кількість запитів до API, які реалізовано за допомогою механізму rate limiting у NGINX.

У випадку отримання відповіді з кодом 429 Too Many Requests, клієнт має:

реалізувати механізм повторних спроб із застосуванням затримки перед наступним запитом (exponential backoff або фіксоване очікування)
не виконувати негайні повторні запити без очікування
враховувати, що час відновлення можливості надсилати запити не передається сервером явно, і має бути визначений клієнтом відповідно до логіки обмеження частоти (наприклад, очікування 1 секунди або більше).

2.2.1. Поточні налаштування рейт-лімітів

Запити на секунду: 100 запитів на секунду
Запити на хвилину: 2000 запитів на хвилину
Активні з'єднання: 300 з'єднань з однієї IP-адреси

2.2.2. Що це таке і навіщо?

Обмеження частоти запитів (rate limit) — це один з основних інструментів захисту вебресурсів від DDoS-атак.

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

2.2.3. Мета використання рейт-лімітів

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

Щоб запобігти перевантаженню нової системи та мінімізувати можливі наслідки таких помилок, вводиться обмеження на кількість запитів і активних з'єднань з боку однієї IP-адреси.

2.2.4.Поточні налаштування рейт-лімітів

Запити на секунду: 100 запитів на секунду.
Запити на хвилину: 2000 запитів на хвилину.
Активні з'єднання: 300 з'єднань з однієї IP-адреси.

2.2.5. Як працюють рейт-ліміти?

Ліміти обчислюються для кожного середовища (домену) окремо. Наприклад, якщо з однієї IP-адреси взаємодіють з декількома середовищами, то кількість запитів розраховується для кожного з них окремо.
Блокування IP-адреси також виконується окремо для кожного середовища.

2.2.6. Запобігання блокуванню при раптових стрибках активності

Для того, щоб система не блокувала IP-адресу при короткочасних стрибках активності користувачів, дозволяється тимчасове перевищення ліміту запитів у 5 разів. Це дає змогу системі справлятися з піковими навантаженнями. Однак, якщо активність залишається високою у наступній секунді або хвилині, система почне блокувати запити.

2.2.7. Що відбувається у разі блокування IP-адреси?

Якщо кількість запитів перевищує встановлені ліміти, система повертає відповідь з HTTP кодом 429 ("Too Many Requests").

Public > Вимоги до інтеграції з ЦБД > 429.jpg

2.2.8. Як уникати блокування?

Є декілька основних причин чому майданчик може бути заблокованим:

Генерування великої кількості однакових запитів майданчиком через помилку на стороні майданчика або неочікувану відповідь від ЦБД.

Логіка роботи ПЗ майданчика має унеможливлювати надмірну частоту повторів будь яких запитів на нову систему за будь-яких умов.

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

Mirror використовує постійне з'єднання на основі протоколу WebSocket, що дозволяє отримувати зміни в режимі реального часу.

Це означає, що немає необхідності виконувати повторні підключення або надсилати окремі запити для отримання актуальних даних.

Інформація передається автоматично через це постійне з'єднання, що знижує навантаження на систему та спрощує процес синхронізації.

Невикористовувані з'єднання, які залишаються відкритими.

Логіка роботи ПЗ майданчика має унеможливлювати завислі з'єднання які невикористовуються.

Зі свого боку, нова система примусово закриває з'єднання в яких протягом 350 секунд не передавалася інформація.

Дотримання цих рекомендацій допоможе уникнути блокування та забезпечити стабільну роботу з новою системою.

2.3. Обробка помилок клієнтської валідації

Майданчик має забезпечити коректну обробку помилок валідації на стороні API:

У разі відповіді з кодом 400 Bad Request, майданчик повинен припинити автоматичне повторення запиту та логувати помилку з відповідним повідомленням для подальшого аналізу.
Повторна відправка можлива тільки після виправлення помилкових даних.
за необхідності — ініціювати звернення до служби підтримки для уточнення прав доступу у відповідному каналі Slack

2.3.1. Обробка серверних помилок (5xx)

Майданчик зобов’язаний реалізувати механізм повторних запитів із затримкою у разі тимчасових збоїв на стороні ЦБД:

У разі отримання коду 5хх має застосовуватись стратегія exponential backoff з обмеженням кількості повторів, щоб не спіймати 429 помилку. Рекомендовано робити не більше 5-ти повторів.
В разі отримання 500-х помилок потрібно проінформувати підтримку ЦБД Prozoroo.Sale про виникнення такої ситуації.

3. Сумісність з оновленнями API ЦБД

Майданчик має бути сумісним із backward-compatible оновленнями API:

Система повинна коректно працювати у разі додавання нових необов’язкових полів у відповідях або змін, які не порушують існуючу логіку. Якщо після оновлення API ЦБД, наприклад, додано нові необовʼязкові поля, то майданчик не має ламатися
Усі парсери та серіалізатори мають бути готовими до розширення схеми.
ПЗ майданчика має бути готовим до змін у ЦБД, передбачаючи гнучку обробку нових версій API

4. Логування запитів до ЦБД

4.1. Загальні вимоги

ПЗ майданчика має забезпечувати окреме логування всіх запитів до API ЦБД, незалежно від логів роботи самого ПЗ.
Логи мають бути доступними Prozorro.Sale за запитом

4.2. Вміст логів

Лог кожного запиту до ЦБД повинен включати:

HTTP-метод (GET, POST тощо)
Повний URI запиту (з query-параметрами, але без чутливої інформації, наприклад, access token)
Дату та час запиту та відповіді (у UTC)
Статус відповіді ЦБД
Унікальний ідентифікатор X-Request-ID, який ЦБД повернуло у заголовку відповіді

4.3. Доступ до логів

НЕПРОД: доступ можуть отримати тестувальники, розробники, DevOps за запитом
ПРОД: доступ можливий лише через офіційне звернення бізнес-сторони (через наявність конфіденційних даних)

4.4. Формат і доступ

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

4.5. Мінімальні можливості фільтрації логів

Майданчик має забезпечити можливість фільтрації логів:

за часовим інтервалом
за значенням X-Request-ID
за API-ендпоінтом
за HTTP-статусом відповіді
за HTTP-методом

4.6. Зберігання логів

НЕПРОД: щонайменше 14 днів
ПРОД: щонайменше 30 днів
Логи мають бути чітко розділені за середовищами ЦБД (наприклад: sandbox, production), не об’єднані в один рядок

5. Базові вимоги до процедур взаємодії

5.1. Обов’язкове використання Mirror-сервісу

Майданчик зобов’язаний інтегруватися з Mirror-сервісом для синхронізації з ЦБД
ПЗ має підтримувати постійне з'єднання з Mirror-сервісом і забезпечувати неперервну синхронізацію
Заборонено використовувати Mirror-сервіс у вигляді періодичного cron-сценарію (наприклад, раз на годину/добу)

Для забезпечення стабільності синхронізації даних, майданчики повинні коректно обробляти об'єкти великого розміру.

Вимоги до налаштування майданчиків

Переконайтеся, що налаштування вашого WebSocket-клієнта дозволяють передачу пакетів розміром до 7.5 Мб.

Базовий тесткейс

Цей сценарій є обов'язковим для проходження при підключенні нових майданчиків або оновленні логіки роботи з Mirror.

Кроки тестування:

Створення даних (Create):
- Створити процедуру кожного доступного типу з наповненням (текст, метадані), що сумарно складає 7.5 Мб
- Створити кожен об'єкт реєстру (Registry Object) розміром 7.5 Мб
- Створити кожен об'єкт джоббера розміром 7.5 Мб
- Очікуваний результат: Об'єкт успішно валідується, передається в ЦБД та стає доступним для інших учасників через Mirror
Отримання даних (Sync):
- У ЦБД (на середовищі Sandbox) створюється об'єкт процедури розміром 7.5 Мб.
- Очікуваний результат: Клієнт Mirror майданчика не розриває з'єднання, успішно парсить отриманий JSON та оновлює локальну базу даних.

Для перевірки роботи міррора, протестувати створення наступних сутностей

процедури (з будь-якого напрямку)
процедури dgf
об'єкт реєстра (registry)
Announcement з послідуючим створенням процедури великого обʼєму (більше 6 Мб)

можна розбити на наступні етапи (якщо потрібно) - 2, 5, 7.5 метри об'єкт

Майданчик у себе перевіряє роботу клієнту (опрацювання помилки 1009 або схожих в залежності від реалізації клієнту) і також можливість швидко налаштувати максимальний розмір повідомлення яке Майданчик може отримувати з Mirror

Для тестувальників: тестувальник перевіряє, що об'єкт був синхронізований і корректно відображається на фронті Майданчика (публічний перегляд, кабінет організатора і учасника) при створенні об'єкту і його редагуванні як зі сторони самого Майданчика, так і зі сторони, коли обʼєкт створено іншим Майданчиком

5.2. Генерація мініатюр

ПЗ майданчика має використовувати генератор мініатюр для ілюстрацій, що відображаються в інтерфейсі

6. Використання VPN для авторизованих HTTP-запитів

Підключення до API з використанням AUTH токена дозволене лише всередині VPN-з'єднання, яке попередньо сертифіковане Prozorro.Sale
Заборонено виконання авторизованих запитів без VPN, навіть якщо передача відбувається по HTTPS
Винятком можуть бути лише публічні GET-запити, які не потребують авторизації, якщо інше не зазначено окремо

Мета: Забезпечення безпеки та конфіденційності авторизованої взаємодії з API ЦБД, запобігання перехопленню або компрометації токенів авторизації сторонніми особами.

6.1. Отримання доступу до VPN

Для підключення до захищеного середовища необхідно попередньо отримати сертифікат VPN.
Заявка на отримання сертифікату VPN подається через Service Desk Prozorro.Sale за посиланням: https://jira-sale.prozorro.org/servicedesk/customer/portal/33/create/481

7. Додатково

Загальні вимоги до процедур описані за посиланням Базові вимоги до майданчиків