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 секунди або більше).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Синхронізація або ресинхронізація великої кількості об'єктів через ендпоінти пошуку, чи процедури а не механізми 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. Вміст логів

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

дату та час запиту (у UTC),
повний URI запиту з query-параметрами (без чутливої інформації, наприклад, access token),
HTTP-метод (GET, POST, PUT, DELETE тощо),
статус відповіді ЦБД,
значення заголовка request-id, що повертається ЦБД.

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

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

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

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

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

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

за часовим інтервалом,
за значенням request-id,
за API-ендпоінтом,
за HTTP-статусом відповіді,
за HTTP-методом.

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

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

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

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

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

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

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

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

Усі POST та PUT запити до API ЦБД у ПРОД середовищі мають виконуватись через захищене VPN-з’єднання.
Інші типи запитів (GET, DELETE тощо) — рекомендовано виконувати через VPN, але це не є обов’язковою вимогою.

7. Додатково

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