Versions Compared

Old Version 34

changes.mady.by.user valeriia denysenko

Saved on

compared with

New Version 35

changes.mady.by.user valeriia denysenko

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  1. Додати до базової моделі award необовʼязкову до заповнення поле beneficiaries моделю даних beneficiariesGeneralInfo (модель даних наведено нижче)
  2. Налаштувати інтеграцію з ЄДР де після відпраки запиту заповнюється модель beneficiariesGeneralInfo
  3. При внесенні інформації змінюємо award.dateModified, dateModified (procedure) та systemDateModified
  4. Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)
  5. Модель даних beneficiariesGeneralInfo
    Технічна назваБізнес назва (x-legalName)ТипRead onlyОбовʼязковість (потребує уточнень)Коментар
    uk_UAen_US
    beneficiaries
    		Інформація про кінцевого бенефеціарного влсникаInformation about the ultimate beneficial owner
    		list of objectstruefalse
     

    reason

    		  string (multilang)truefalse
     

    beneficiariesGeneralInfo

    		  objecttruefalse


    		beneficialNameПІБ кінцевого бенефеціарного власникаFull name of the ultimate beneficial ownerstring (multilang)truetrueВ запиті Прізвище це відповідь на один запит, Імʼя та По батькові - відповідь на інший запит


    		addressАдресаAddressmodeltruetrue


    beneficiariesType

    		Тип бенефіціарного володінняType of 

    beneficiaries

    		string (multilang)truetrue


    		roleРоль КБВ по відношенню до пов’язаного суб’єкта
    		stringtruetrueВідповідь на запит текстове відображення ролі (roleText)


    interest

    		Відсоток частки статутного капіталу або відсоток права голосу
    		float truetrue


    indirectInterest

    		Відсоток частки статутного капіталу або відсоток права голосу у разі непрямого впливу
    		floattruetrue


    otherImpact

    		Інший характер та міру впливу
    		 




    beneficiaryFalse

    		Ознака можливої недостовірності інформації про КБВ
    		 




    excluded

    		Ознака виключення відомостей про КБВ за вказівкою Міністерства юстиції України
    		 




    isMissing

    		Ознака відсутності КБВ юридичної особи
    		 




    reason

    		Причина відсутності КБВ юридичної особи
    		 




    		informationDateДата отримання данихDate of informationstring ($dateTime)truetrue

...

  • Інтеграція тригериться тільки при створенні award
  • Запит асинхронний
  • Дані записуються тільки якщо валідні
  • Запис — атомарний (все або нічого)
  • Можливі декілька КБВ
  • Retry (3 рази) тільки для:
    • 500
    • 502
  • Slack alert тільки для:
    • 4xx + 429
  • Fallback текст при недоступності ЄДР
  • У разі отримання першої відповіді від ЄДР з HTTP статусом 402 або 429 ЦБД має призупинити направлення всіх наступних запитів до сервісу ЄДР до моменту ручного або автоматичного відновлення інтеграції після внесення коштів / відновлення ліміту.
  • Система повинна диференційовано обробляти помилки ЄДР:
    • технічні помилки (500, 502) → retry (Якщо не вдається отримати відповідь виводимо в поле reason текст "Не вдалось отримати інформацію з сервісу")

Статуси інтеграції (В разі якщо будемо виносити в Адмінку та або будемо в принципі зупиняти запити в разі отримання помилок)

    • авторизаційні (401) → refresh token
    • бізнес/доступ (402, 403, 406, 429) → зупинка або alert
    • помилки даних (400, 404) → без retry, з логуванням

      Система не повинна виконувати безкінечні повторні запити.

Статуси інтеграції (В разі якщо будемо виносити в Адмінку та або будемо в принципі зупиняти запити в разі отримання помилок)

СтатусОпис
СтатусОпис
activeЗапити до ЄДР виконуються
payment_requiredОтримано 402, запити зупинено
rate_limit_exceededОтримано 429, запити зупинено
suspendedЗагальний статус призупинення
restoredІнтеграцію відновлено

Як працює сервіс ЄДР

Сервіс ЄДР реалізований як API для автоматичного отримання даних для внесення інформації про КБВ учасника торгів що кваліфікується. Взаємодія працює по протоколу HTTP з використанням авторизації через JWT. Загальна логіка процесу: спочатку через метод авторизації отримуємо access та refresh токени, а потім використовуємо їх для виклику ендпоінту отримання даних для заповнення інформації про КБВ за кодом ЄДРПОУ юридичною особи. - Детальніше буде додано після отримання тестового ключа

...

USE CASE 8 — Зупинка запитів після отримання 429

Назва

Автоматичне призупинення інтеграції з ЄДР при помилці 429 Many Requests
Актори
  • ЦБД
  • ЄДР
  • Slack канал
  • Адміністратор/відповідальна команда
Передумови
  • Інтеграція з ЄДР активна
  • ЦБД направляє запит до ЄДР
  • ЄДР повертає HTTP 429
  • 429 означає, що вичерпано обмеження запитів до ресурсу.
Основний сценарій
  1. ЦБД направляє запит до ЄДР.
  2. ЄДР повертає відповідь 429 Many Requests.
  3. ЦБД фіксує помилку.
  4. ЦБД призупиняє направлення нових запитів до ЄДР.
  5. ЦБД відправляє повідомлення в Slack канал.
  6. Нові awards, які підпадають під інтеграцію, не ініціюють запит до ЄДР.
  7. Система фіксує причину призупинення:
    • Перевищено ліміт запитів до ЄДР.
Результат
  • Інтеграція тимчасово зупинена.
  • Нові запити до ЄДР не виконуються.
  • Команда повідомлена про перевищення ліміту.

Acceptance Criteria

1

GivenЦБД отримала відповідь 429

When

Система обробляє відповідь

Then

Направлення нових запитів до ЄДР зупиняється.

2


Given

Інтеграція призупинена через 429

When

Створюється новий award

Then

ЦБД не направляє запит до ЄДР

3

GivenОтримано 429
WhenСистема обробляє помилку

Then

Повідомлення надсилається в Slack канал.


...

USE CASE 9 — Відновлення запитів після внесення коштів

Назва

Ручне або автоматичне відновлення інтеграції з ЄДР після внесення коштів
Актори
  • Адміністратор/відповідальна команда
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція з ЄДР була призупинена через 402
  • Кошти внесено / доступ до сервісу відновлено
Основний сценарій
  1. Відповідальна команда вносить кошти.
  2. Адміністратор ініціює відновлення інтеграції.
  3. ЦБД змінює статус інтеграції з:
    • payment_required / suspended
    • на active.
  4. ЦБД відновлює направлення запитів до ЄДР.
  5. При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.
  6. Якщо ЄДР повертає 200, дані КБВ обробляються та записуються в award.
Результат
  • Інтеграція з ЄДР активна.
  • Нові запити знову направляються.
  • Дані КБВ можуть бути отримані та внесені в award.

Acceptance Criteria

1

GivenІнтеграція призупинена через 402
AndКошти внесено

When

Адміністратор активує інтеграцію

Then

Статус інтеграції змінюється на active.

2


Given

Інтеграція активна після відновлення

When

Створюється новий award

Then

ЦБД направляє запит до ЄДР

3

GivenЄДР після відновлення повертає 200
WhenЦБД отримує валідні дані

Then

Дані записуються в award.beneficiaries


...

USE CASE 10 — Відновлення після вичерпання ліміту запитів

Назва

Відновлення інтеграції після помилки 429
Актори
  • Адміністратор/відповідальна команда
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція була призупинена через 429
  • Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу
Основний сценарій
  1. Відповідальна команда перевіряє, що ліміт запитів відновлено.
  2. Адміністратор активує інтеграцію.
  3. ЦБД змінює статус інтеграції на active.
  4. Наступні awards знову запускають запит до ЄДР.
  5. Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.
Результат
  • Запити до ЄДР відновлені.
  • Система продовжує автоматичне збагачення awards даними КБВ.

Acceptance Criteria

1

GivenІнтеграція призупинена через 429

When

Ліміт запитів відновлено

And

Адміністратор активує інтеграцію

Then

ЦБД знову направляє запити до ЄДР

2


Given

Інтеграція активована після 429

When

Створюється award

Then

Запит до ЄДР виконується

User Story 3. Обробка помилок інтеграції з ЄДР та забезпечення стабільності системи

ЯкЦБД Prozorro.Sale
я хочукоректно обробляти всі типи помилок від ЄДР (400, 401, 403, 404, 406, 500, 502)
щобзабезпечити стабільну роботу системи, не втрачати дані та мати можливість відновлення інтеграції

USE CASE

...

11 — Обробка 401 (Unauthorized)

Назва

Автоматичне оновлення токена при помилці 401

Назва

Отримання та запис КБВ з ЄДР в award
Актори
  • ЦБД
(primary)
  • ЄДР
API (external)
  • Slack
Передумови
  • Процедура входить в перелік дозволених (LLE, LLD, …, SUD)
  • В процедурі використовується документ x_ultimateBeneficiaryInfo
  • Учасник є юридичною особою
  • award.bidders.identifier.scheme = UA-EDR
  • award.status ∈ {pending_waiting, pending_admission, pending}
Основний сценарій
  1. Учасник подає заявку
  2. Майданчик активує заявку
  3. Заявка переходить у кваліфікацію
  4. ЦБД створює award
  5. ЦБД перевіряє умови запуску інтеграції
  6. ЦБД виконує авторизацію в ЄДР (отримує JWT токен)
  7. ЦБД відправляє запит до ЄДР з code = ЄДРПОУ
  8. ЄДР повертає дані КБВ (може бути список)
  9. ЦБД валідовує відповідь
  10. Дані відповідають моделі beneficiariesGeneralInfo
  11. ЦБД записує дані в award.beneficiaries
  12. Оновлює:
  • award.dateModified
  • procedure.dateModified
  • systemDateModified
Результат

award містить список КБВ (може бути декілька)

Acceptance Criteria

...

1

...

When

...

Then

...

2

...

ЄДР повернув валідні дані

...

When

...

Then

...

3

...

Then

...

оновлюються всі dateModified:

  • award.dateModified
  • dateModified (procedure)
  • systemDateModified

🧩 USER STORY (для обробки помилок ЄДР)

...

User Story:
Як ЦБД
я хочу 
щоб 

🔐 USE CASE 1 — Обробка 401 (Unauthorized)

Назва

Автоматичне оновлення токена при помилці 401

Актори

  • ЦБД
  • ЄДР
  • Slack

Передумови

  • Запит до ЄДР виконано
  • Отримано 401 Unauthorized

Основний сценарій

...

  • Запит до ЄДР виконано
  • Отримано 401 Unauthorized
Основний сценарій
  1. ЦБД отримує
  1. 401
  2. Визначає, що токен невалідний / протермінований
  3. Виконує запит на оновлення access_token через refresh_token
  4. Отримує новий токен
  5. Повторює запит

...

  1. до ЄДР (1 раз)
  2. Якщо успішно → стандартний сценарій (запис даних)
Альтернативний сценарій

Refresh token невалідний → перейти до помилки критичного рівня

Результат

Інтеграція відновлюється без втручання людини

Acceptance Criteria

1

GivenОтримано 401

When

Токен протермінований

Then

Система виконує refresh token

2


Given

Токен оновлено

Then

Запит повторюється 1 раз

3

Givenповторний запит успішний

Then

дані записуються в award



...

USE CASE 12 — Помилка 400 (Bad Request)

Назва

Обробка некоректного запиту до ЄДР
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • неправильний формат параметрів
  • неправильний code
Основний сценарій
  1. ЦБД отримує 400
  2. Аналізує помилку
  3. Визначає:
    • помилка у формуванні запиту
  4. НЕ виконує retry
  5. Логує помилку
  6. Надсилає повідомлення в Slack
Рішення

Виправлення формату запиту (dev fix)

Результат
  • запит не повторюється
  • потрібне втручання розробника

Acceptance Criteria

1


GivenОтримано 400

When

Обробляється помилка

Then

Retry не виконується

And

Slack отримує повідомлення


...

USE CASE 13 — Помилка 403 (Forbidden)

Назва

Обробка відсутності прав доступу
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • змінились права доступу до API
  • акаунт не має доступу
Основний сценарій
  1. ЦБД отримує 403
  2. Фіксує помилку
  3. НЕ виконує retry
  4. Відправляє alert в Slack
  5. (опційно) переводить інтеграцію в статус restricted
Рішення
  • перевірка прав доступу
  • перевидача ключів / ролей
Результат

Інтеграція не працює до виправлення

Acceptance Criteria

1


GivenОтримано 403

Then

Retry не виконується

And

Slack отримує повідомлення


...

USE CASE 14 — Помилка 404 (Not Found)

Назва

Обробка відсутності суб’єкта в ЄДР
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови

ЄДРПОУ не знайдено

Основний сценарій
  1. ЦБД отримує 404
  2. Визначає, що суб'єкт відсутній
  3. НЕ виконує retry
  4. Записує beneficiaries тільки поле reason:
    • "Суб'єкт не знайдено в ЄДР"
Результат
  • award без КБВ

Acceptance Criteria

1


GivenОтримано 404

Then

Retry не виконується

And

Записує beneficiaries тільки поле reason:

    • "Суб'єкт не знайдено в ЄДР"


...

USE CASE 15 — Помилка 406 (Not Acceptable)

Назва

Обробка помилки формату даних
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови

Некоректний формат request/response

Основний сценарій
  1. ЦБД отримує 406
  2. Фіксує помилку
  3. НЕ виконує retry
  4. Відправляє alert в Slack
Рішення
  • перевірка контракту API
  • виправлення формату
Результат
  • інтеграція потребує доопрацювання

Acceptance Criteria

1


GivenОтримано 406

Then

Retry не виконується

And

Slack отримує повідомлення

ЗВЕДЕНА ТАБЛИЦЯ

Альтернативи

  • Refresh token невалідний → перейти до помилки критичного рівня

Результат

  • Інтеграція відновлюється без втручання людини

Acceptance Criteria

  • Given отримано 401
    When токен протермінований
    Then система виконує refresh token
  • Given токен оновлено
    Then запит повторюється 1 раз
  • Given повторний запит успішний
    Then дані записуються в award

❗ USE CASE 2 — Помилка 400 (Bad Request)

Назва

Обробка некоректного запиту до ЄДР

Причина

  • неправильний формат параметрів
  • неправильний code

Основний сценарій

  1. ЦБД отримує 400
  2. Аналізує помилку
  3. Визначає:
    • помилка у формуванні запиту
  4. НЕ виконує retry
  5. Логує помилку
  6. Надсилає повідомлення в Slack

Рішення

  • виправлення формату запиту (dev fix)

Результат

  • запит не повторюється
  • потрібне втручання розробника

Acceptance Criteria

  • Given отримано 400
    When обробляється помилка
    Then retry не виконується
    And Slack отримує повідомлення

🚫 USE CASE 3 — Помилка 403 (Forbidden)

Назва

Обробка відсутності прав доступу

Причина

  • змінились права доступу до API
  • акаунт не має доступу

Основний сценарій

  1. ЦБД отримує 403
  2. Фіксує помилку
  3. НЕ виконує retry
  4. Відправляє alert в Slack
  5. (опційно) переводить інтеграцію в статус restricted

Рішення

  • перевірка прав доступу
  • перевидача ключів / ролей

Результат

  • інтеграція не працює до виправлення

Acceptance Criteria

  • Given отримано 403
    Then retry не виконується
    And Slack повідомляється

🔍 USE CASE 4 — Помилка 404 (Not Found)

Назва

Обробка відсутності суб’єкта в ЄДР

Причина

  • ЄДРПОУ не знайдено

Основний сценарій

  1. ЦБД отримує 404
  2. Визначає, що суб'єкт відсутній
  3. НЕ виконує retry
  4. НЕ записує beneficiaries
  5. (опційно) записує reason:
    • "Суб'єкт не знайдено в ЄДР"

Результат

  • award без КБВ

Acceptance Criteria

  • Given отримано 404
    Then retry не виконується
    And дані не записуються

⚠️ USE CASE 5 — Помилка 406 (Not Acceptable)

Назва

Обробка помилки формату даних

Причина

  • некоректний формат request/response

Основний сценарій

  1. ЦБД отримує 406
  2. Фіксує помилку
  3. НЕ виконує retry
  4. Відправляє alert в Slack

Рішення

  • перевірка контракту API
  • виправлення формату

Результат

  • інтеграція потребує доопрацювання

Acceptance Criteria

  • Given отримано 406
    Then retry не виконується
    And Slack повідомляється

🔄 USE CASE 6 — Помилки 500 / 502 (Server errors)

(у тебе вже частково є, але тут — повна версія)

Назва

Retry при серверних помилках ЄДР

Основний сценарій

  1. ЦБД отримує 500 або 502
  2. Виконує retry (до 3 разів)
  3. Якщо успіх → стандартний сценарій
  4. Якщо всі retry fail:
    • записує fallback текст
    • НЕ падає

Рішення

  • автоматичне повторення
  • graceful fallback

Результат

  • система стабільна навіть при падінні ЄДР

Acceptance Criteria

  • Given 500/502
    Then retry до 3 разів
  • Given retry fail
    Then записується fallback повідомлення

...

КодRetryЗупинка інтеграціїSlackДія
400
❌
Ні
❌
Ні
✅
Такбаг у запиті
401
🔁
Так (1 раз)
❌
НІ
❌
Ніrefresh token
402
❌
Ні
✅
Так
✅
Такчекати оплату
403
❌⚠️ (можливо)
НіМожливоТак
✅
перевірити доступ
404
❌
Ні
❌
Можливо
❌
Нінемає суб'єкта
406
❌
Ні
❌
Можливо
✅
Такформат
429
❌
НІ
✅
Так
✅ліміт500🔁 (3 рази)❌❌тимчасова помилка502🔁 (3 рази)❌❌сервіс недоступний

🧩 ГЛОБАЛЬНЕ БІЗНЕС-ПРАВИЛО

...

Такліміт
500🔁 (3 рази)НіНітимчасова помилка
502🔁 (3 рази)НіНісервіс недоступний