Майданчик, залучає користувача до участі в аукціоні де звіт з інформацією про КБВ (x_ultimateBeneficiaryInfo) визначений як тип документу
Учасник є юридичною особою
Учасник подає заявку на участь
Майданчик активує заявку на участь
Заявка на участь перейшла в кваліфікацію
Під час створення award (асинхронний запит)ЦБД направляє запит в ЄДР з авторизаційним ключем і даними для пошуку де виконуються умови:
1. Для award в статусах: pending_waiting, pending_admission, pending
2. Для award.bidders.identifier.UA-EDR
3. Для процедур де x_ultimateBeneficiaryInfo є типом документу. Перелік процедур
  1. LLE, LLD, LLP - Оренда за законом
  2. LRE - Земельні торги - оренда
  3. LSE + LSP - Земельні торги - продаж/продаж з переважним правом
  4. REM - Процедури розподілу квот
  5. SSW - Продаж майна приватних компаній (Закриті пропозиції)
  6. SPE + SPD - Мала приватизація
  7. LPE - Велика приватизація
  8. LAE + LAP + LAW - Продаж арештованої землі
  9. APE + APD - Арештовані активи АРМА
  10. SAE + SAD - Санкційне майно
  11. SUE+SUD - Спеціальні дозволи на користування надрами
  12. Процедури, яких немає в переліку не використовують даний функціонал - РО попереджено що додавання нових напрямків йде через розробку
ЦБД отримує дані з ЄДР
1. Перевіряє отримані дані:
  1. Якщо в отриманій відповіді містяться дані, які не можна внести в award → ЦБД не вносить дані в award
  2. Якщо в отриманій відповіді містяться дані, які можна внести в award → ЦБД вносить дані в award
    1. При внесенні даних змінюється:
      1. award.dateModified
      2. dateModified (procedure)
      3. systemDateModified

Особливості:

Тип поля beneficiaryInfo в award - list of objects
Запит на ЄДР може віддати дані про декількох КБВ
Потрібно передбачити що повторний запит відправляється в разі отримання відповіді 500 або 502 омежений 3ма спробами
Якщо не вдається отримати відповідь виводимо в поле текст "Не вдалось отримати інформацію з сервісу"
Нам потрібно фіксувати повідомленням в Slack канал якщо отримуємо відповіді:
1. 400
2. 401
3. 402
4. 403
5. 404
6. 406
7. 429

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

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

Дія тестового ключа 6 місяців

Доступні ендпоінти (Потребує перевірки та доповнення після отримання тестових ключей)

Авторизація (отримання токенів)
Оновлення access_token
Метод отримання унікального ідентифікатора
1. Метод: POST
2. Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника
3. Приймає на вхід:
  - Обовʼязковий query-параметр: code
4. Приклад запиту:
5. Приклади відповіді:
  1. Якщо code знайдено, а також токен авторизації є валідним:
  2. Якщо code не знайдено:
  3. Якщо сплив термін дії токена авторизації:
  4. Якщо сервіс наразі недоступний:

Також можливий кейс, що АРІ поверне 403 помилку, якщо, наприклад, ЄДР змінить права доступу нашого акаунту.

Перелік кодів помилок

Коди помилок та відповідей:

Коди відповідей HTTP

Код	Текст	Пояснення
200	OK	Запит успішно оброблено і повернуто результат
400	Bad Request	Запит має помилку або не може бути оброблений. Відповідне повідомлення з поясненнями додане до відповіді.
401	Unauthorized	Параметри авторизації не правильні, або не вказані взагалі.
402	PaymentRequired	Для виконання запиту необхідна оплата.
403	Forbidden	Запит вірний але в обробці відмовлено. Відповідне повідомлення з поясненнями додано до відповіді.
404	Not Found	Адреса не правильна або ресурс до якого йде запит не існує.
406	Not Acceptable	Дані передані в запиті мають не зрозумілий формат.
429	Many Requests	API повертає таку відповідь коли вичерпано обмеження запитів до ресурсу.
500	Internal Server Error	Щось зламалось.
502	Bad Gateway	Сервіс вимкнено або проходить оновлення.

Повідомлення з інформацією про помилку.

Ключові бізнес-правила

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

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

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

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

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

Дія тестового ключа 6 місяців

Доступні ендпоінти (Потребує перевірки та доповнення після отримання тестових ключей)

Авторизація (отримання токенів)
Оновлення access_token
Метод отримання унікального ідентифікатора
1. Метод: POST
2. Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника
3. Приймає на вхід:
  - Обовʼязковий query-параметр: code
4. Приклад запиту:
5. Приклади відповіді:
  1. Якщо code знайдено, а також токен авторизації є валідним:
  2. Якщо code не знайдено:
  3. Якщо сплив термін дії токена авторизації:
  4. Якщо сервіс наразі недоступний:

Також можливий кейс, що АРІ поверне 403 помилку, якщо, наприклад, ЄДР змінить права доступу нашого акаунту.

Перелік кодів помилок

Коди помилок та відповідей:

Коди відповідей HTTP

Код	Текст	Пояснення
200	OK	Запит успішно оброблено і повернуто результат
400	Bad Request	Запит має помилку або не може бути оброблений. Відповідне повідомлення з поясненнями додане до відповіді.
401	Unauthorized	Параметри авторизації не правильні, або не вказані взагалі.
402	PaymentRequired	Для виконання запиту необхідна оплата.
403	Forbidden	Запит вірний але в обробці відмовлено. Відповідне повідомлення з поясненнями додано до відповіді.
404	Not Found	Адреса не правильна або ресурс до якого йде запит не існує.
406	Not Acceptable	Дані передані в запиті мають не зрозумілий формат.
429	Many Requests	API повертає таку відповідь коли вичерпано обмеження запитів до ресурсу.
500	Internal Server Error	Щось зламалось.
502	Bad Gateway	Сервіс вимкнено або проходить оновлення.

Повідомлення з інформацією про помилку.

У разі помилки API повертає відповідь з поясненням, формат - JSON, наприклад:

...

Код	Текст	Пояснення
1	Could not authenticate you або Authentication credentials were not provided	Помилка аутентифікації.
2	Invalid or expired token	Недіючий або некоректний токен.
3	Your account is not permitted to access this resource	Відповідь надається разом із HTTP статусом 403. Користувач, з використанням токену якого було виконано аутентифікацію, не має достатніх прав для виконання запиту.
4	Sorry, that page does not exist	Відповідь надається разом із HTTP статусом 404. Сторінка до якої виконується запит не знайдена.
5	Paiment required	Відповідь надається разом із HTTP статусом 402. Недостатньо коштів для виконання платного запиту.
6	Parse Error або `search_date` has wrong format	Відповідь надається разом із HTTP статусом 400. Не правильний формат одного або декількох параметрів запиту.
9	Rate limit exceeded	Відповідь надається разом із HTTP статусом 429. Вичерпано кількість запитів, дозволених виконати протягом проміжку часу.
10	`code` or `passport` parameter must be provided.	У запиті не надано параметрів необхідних для виконання пошуку.
11	`passport` parameter has wrong value.	Один або більше параметрів запиту має невірний формат.
20	Internal error	Відповідь надається разом із HTTP статусом 500.

Правила обробки помилок

HTTP code	Дія системи
400	Slack alert, дані не записуються
401	Slack alert, спроба оновити token
402	Slack alert, дані не записуються
403	Slack alert, дані не записуються
404	Slack alert, дані не записуються
406	Slack alert, дані не записуються
429	Slack alert, дані не записуються
500	Retry до 3 разів
502	Retry до 3 разів

User Story 1

Як	ЦБД Prozorro.Sale
я хочу	автоматично отримувати та зберігати інформацію про кінцевих бенефіціарних власників (КБВ) з ЄДР при створенні award
щоб	забезпечити актуальність, централізацію та зменшити залежність від ручного введення даних

USE CASE 1 — Успішне отримання та збереження КБВ

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

Acceptance Criteria

1	Given	Всі умови виконані
	When	Створюється award
	Then	Відправляється запит до ЄДР
2	Given	ЄДР повернув валідні дані
	When	Дані проходять валідацію
	Then	Вони записуються в award.beneficiaries
3	Given	Дані записані
3	Then	оновлюються всі dateModified: `award.dateModified` `dateModified (procedure)` `systemDateModified`

...

USE CASE 2 — Дані не можуть бути внесені

Назва	Відмова у записі КБВ
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Отримано HTTP код: 400, 401, 402, 403, 404, 406, 429
Основний сценарій	ЦБД отримує відповідь від ЄДР Перевіряє структуру Дані: неповні / некоректні / не мапляться ЦБД НЕ записує дані
Результат	award без змін

Acceptance Criteria

1	Given	Дані не відповідають моделі
	When	Виконується валідація
	Then	Дані не записуються

...

USE CASE 3 — Retry при помилках 500 / 502

Назва	Повторна спроба отримання даних
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Отримано HTTP код: 500, 502
Основний сценарій	ЦБД відправляє запит Отримує 500 або 502 Виконує retry Повторює до 3 разів
Альтернативний сценарій	після 3 невдалих спроб → fallback
Результат	якщо успіх → UC1 якщо ні → запис тексту помилки

Acceptance Criteria

1	Given	Отримано 500/502
	When	Виконується retry
	Then	Система повторює запит до 3 разів
2	Given	Всі retry невдалі
2	Then	Записується повідомлення: "Не вдалось отримати інформацію з сервісу"

...

USE CASE 4 — Логування помилок в Slack

Назва	Моніторинг інтеграції з ЄДР
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Отримано HTTP код: 400, 401, 402, 403, 404, 406, 429
Основний сценарій	ЦБД отримує помилку Формує повідомлення Відправляє в Slack канал
Результат	команда отримує alert

Acceptance Criteria

1	Given	Отримано помилку зі списку
	When	Обробляється відповідь
	Then	Відправляється повідомлення в Slack

...

USE CASE 5 — Інтеграція не запускається

Назва	Неініціювання запиту до ЄДР
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Будь-яка з умов НЕ виконується: процедура не з переліку відсутній `x_ultimateBeneficiaryInfo` не юрособа не UA-EDR статус award не підходить
Основний сценарій	Створюється award ЦБД перевіряє умови Інтеграція НЕ запускається
Результат	Жодних запитів до ЄДР

Acceptance Criteria

1	Given	Умови не виконані
	When	Створюється award
	Then	запит до ЄДР не виконується

...

USE CASE 6 — Обробка множинних КБВ

Назва	Запис кількох бенефіціарів
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Процедура входить в перелік дозволених (LLE, LLD, …, SUD) В процедурі використовується документ `x_ultimateBeneficiaryInfo` Учасник є юридичною особою `award.bidders.identifier.scheme = UA-EDR` `award.status ∈ {pending_waiting, pending_admission, pending}`
Основний сценарій	ЄДР повертає список КБВ ЦБД мапить кожен запис Формує list of objects Записує в `award.beneficiaries[]`
Результат	Збережено всі КБВ

...

Acceptance Criteria

1	Given	ЄДР повертає кілька КБВ
	When	Відбувається запис
	Then	Всі КБВ зберігаються в масиві

User Story 2. Зупинка запитів в разі отримання помилок 402 або 429

Як	ЦБД Prozorro.Sale
я хочу	зупиняти направлення запитів до ЄДР після першого отримання помилки 402 або 429
щоб	не створювати зайве навантаження на сервіс, не витрачати ліміти та уникати повторних неуспішних запитів до моменту відновлення доступу/поповнення коштів.
додатково	Після внесення коштів або відновлення ліміту система має відновити направлення запитів до ЄДР.

USE CASE

...

7 — Зупинка запитів після отримання 402

Назва

Отримання та запис КБВ з ЄДР в award

Автоматичне призупинення інтеграції з ЄДР при помилці `402 Payment Required`
Актори	ЦБД

(primary)

ЄДР

API (external)Передумови

Процедура входить в перелік дозволених (LLE, LLD, …, SUD)
В процедурі використовується документ x_ultimateBeneficiaryInfo
Учасник є юридичною особою
award.bidders.identifier.scheme = UA-EDR
award.status ∈ {pending_waiting, pending_admission, pending}

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

Учасник подає заявку
Майданчик активує заявку
Заявка переходить у кваліфікацію
ЦБД створює award
ЦБД перевіряє умови запуску інтеграції
ЦБД виконує авторизацію в ЄДР (отримує JWT токен)
ЦБД відправляє запит до ЄДР з code = ЄДРПОУ
ЄДР повертає дані КБВ (може бути список)
ЦБД валідовує відповідь
Дані відповідають моделі beneficiariesGeneralInfo
ЦБД записує дані в award.beneficiaries
Оновлює:

award.dateModified
procedure.dateModified
systemDateModified

Результат

Адміністратор/відповідальна команда Slack канал
Передумови	Інтеграція з ЄДР активна ЦБД направляє запит до ЄДР для отримання даних КБВ ЄДР повертає HTTP `402` У вимогах уже передбачено фіксацію таких помилок у Slack.
Основний сценарій	ЦБД направляє запит до ЄДР. ЄДР повертає відповідь `402 Payment Required`. ЦБД фіксує факт отримання помилки. ЦБД змінює внутрішній статус інтеграції з ЄДР на умовний: `suspended`; або `payment_required`; або `temporarily_disabled`. ЦБД припиняє направлення нових запитів до ЄДР. ЦБД відправляє повідомлення в Slack канал. Для нових awards, які підпадають під умови інтеграції, запит до ЄДР не виконується. У відповідному полі/технічному статусі фіксується причина: `Запити до ЄДР тимчасово призупинено через необхідність оплати`.
Результат	Нові запити до ЄДР не направляються. Команда отримала повідомлення про необхідність внесення коштів. Дані КБВ для нових awards тимчасово не збагачуються.

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

Acceptance Criteria

1

Given

Всі умови виконані

ЦБД отримала від ЄДР відповідь 402

When

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

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

Then

Відправляється запит до ЄДР

Інтеграція з ЄДР переходить у статус призупинення.

2

Given

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

Інтеграція має статус призупинення через 402

When

Дані проходять валідацію

Створюється новий award, який відповідає умовам інтеграції

Then

Вони записуються в award.beneficiaries

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

Дані записані

Отримано `402`
When	Система фіксує помилку
Then

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

award.dateModified
dateModified (procedure)
systemDateModified

...

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

...

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

Назва

Автоматичне призупинення інтеграції з ЄДР при помилці

...

`429 Many Requests`
Актори	ЦБД ЄДР Slack канал Адміністратор/відповідальна команда

...


Передумови	Інтеграція з ЄДР активна ЦБД направляє запит до ЄДР

...

ЄДР повертає HTTP

...

`429` `429` означає, що вичерпано обмеження запитів до ресурсу.
Основний сценарій	ЦБД направляє запит до ЄДР. ЄДР повертає відповідь

...

429 Many Requests.
ЦБД фіксує

...

помилку.
ЦБД

...

suspended;
або payment_required;
або temporarily_disabled.

...

призупиняє направлення нових запитів до ЄДР.
ЦБД відправляє повідомлення в Slack канал.

...

Нові awards, які підпадають під

...

інтеграцію, не ініціюють запит до ЄДР

...

.

...

Запити до ЄДР тимчасово призупинено через необхідність оплати.

Система фіксує причину призупинення: `Перевищено ліміт запитів до ЄДР`.
Результат	Інтеграція тимчасово зупинена.

...

Нові запити до ЄДР не

...

виконуються.
Команда

...

повідомлена про перевищення ліміту.

Acceptance Criteria

...

1

Given

ЦБД отримала

...

відповідь

...

429

When

...

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

...

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

...

2

Given

...

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

...

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

...


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

...

3

Given

...

	Отримано `429`
When

...

	Система обробляє помилку
Then

...

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

...

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

...

внесення коштів

Назва

...

Ручне або автоматичне відновлення інтеграції з ЄДР

...

після внесення коштів

Актори

...

Адміністратор/відповідальна команда ЦБД ЄДР
Передумови	Інтеграція з ЄДР

...

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

...

була призупинена через `402` Кошти внесено / доступ до сервісу відновлено
Основний сценарій	Відповідальна команда вносить кошти. Адміністратор ініціює відновлення інтеграції. ЦБД змінює статус інтеграції з: `payment_required` / `suspended` на `active`. ЦБД відновлює направлення

...

запитів до ЄДР.

...

При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.

...

Якщо ЄДР повертає `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

Use Case 3 — Відновлення запитів після внесення коштів

Назва

...


Актори	Адміністратор/відповідальна команда ЦБД ЄДР
Передумови	Інтеграція

...

була призупинена через

...

429
Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу

...


Основний сценарій	Відповідальна команда

...

перевіряє, що ліміт запитів відновлено.
Адміністратор

...

активує інтеграцію.
ЦБД змінює статус інтеграції

...

на active.

...

Наступні awards знову запускають запит до ЄДР.

...

Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.

Результат

...

Запити до ЄДР

...

відновлені.

...

Система продовжує автоматичне збагачення awards даними КБВ.

Acceptance Criteria

...

1

Given

...

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

...

429

...

When	Ліміт запитів відновлено
And	Адміністратор активує інтеграцію
Then

...

AC2
Given інтеграція активна після відновлення
When створюється новий award
Then ЦБД направляє запит до ЄДР.

AC3
Given ЄДР після відновлення повертає 200
When ЦБД отримує валідні дані
Then дані записуються в award.beneficiaries.

Use Case 4 — Відновлення після вичерпання ліміту запитів

Назва

Відновлення інтеграції після помилки 429

Актори

ЦБД
Адміністратор/відповідальна команда
ЄДР

Передумови

Інтеграція була призупинена через 429
Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу

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

Відповідальна команда перевіряє, що ліміт запитів відновлено.
Адміністратор активує інтеграцію.
ЦБД змінює статус інтеграції на active.
Наступні awards знову запускають запит до ЄДР.
Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.

Результат

Запити до ЄДР відновлені.
Система продовжує автоматичне збагачення awards даними КБВ.

Acceptance Criteria

AC1
Given інтеграція призупинена через 429
When ліміт запитів відновлено
And адміністратор активує інтеграцію
Then ЦБД знову направляє запити до ЄДР.

AC2
Given інтеграція активована після 429
When створюється award
Then запит до ЄДР виконується.

Додаткове бізнес-правило для ТЗ

Ключові бізнес-правила (дуже важливо)

...

500
502

...

4xx + 429

...

	ЦБД знову направляє запити до ЄДР
2	Given	Інтеграція активована після `429`
	When	Створюється award
	Then	Запит до ЄДР виконується

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

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

USE CASE 1 — Успішне отримання та збереження КБВ

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

Acceptance Criteria

1	Given	Всі умови виконані
	When	Створюється award
	Then	Відправляється запит до ЄДР
2	Given	ЄДР повернув валідні дані
	When	Дані проходять валідацію
	Then	Вони записуються в award.beneficiaries
3	Given	Дані записані
3	Then	оновлюються всі dateModified: `award.dateModified` `dateModified (procedure)` `systemDateModified`

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

Назва:

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

...

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

Назва

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

Актори

ЦБД
ЄДР
Slack

Передумови

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

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

ЦБД отримує 401
Визначає, що токен невалідний / протермінований
Виконує запит на оновлення access_token через refresh_token
Отримує новий токен
Повторює запит до ЄДР (1 раз)
Якщо успішно → стандартний сценарій (запис даних)

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

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

Результат

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

Acceptance Criteria

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

...

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

Назва

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

Причина

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

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

ЦБД отримує 400
Аналізує помилку
Визначає:
- помилка у формуванні запиту
НЕ виконує retry
Логує помилку
Надсилає повідомлення в Slack

Рішення

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

Результат

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

Acceptance Criteria

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

...

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

Назва

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

Причина

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

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

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

Рішення

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

Результат

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

Acceptance Criteria

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

...

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

Назва

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

Причина

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

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

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

Результат

award без КБВ

Acceptance Criteria

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

...

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

Назва

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

Причина

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

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

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

Рішення

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

Результат

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

Acceptance Criteria

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

...

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

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

Назва

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

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

ЦБД отримує 500 або 502
Виконує retry (до 3 разів)
Якщо успіх → стандартний сценарій
Якщо всі 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, 502) → retry
- авторизаційні (401) → refresh token
- бізнес/доступ (402, 403, 429) → зупинка або alert
- помилки даних (400, 404, 406) → без retry, з логуванням

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

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 33

New Version 34

Key

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

Доступні ендпоінти (Потребує перевірки та доповнення після отримання тестових ключей)

Авторизація (отримання токенів)

Оновлення access_token

Метод отримання унікального ідентифікатора

Метод: POST

Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника

Перелік кодів помилок

Коди відповідей HTTP

Ключові бізнес-правила

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

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

Доступні ендпоінти (Потребує перевірки та доповнення після отримання тестових ключей)

Авторизація (отримання токенів)

Оновлення access_token

Метод отримання унікального ідентифікатора

Метод: POST

Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника

Перелік кодів помилок

Коди відповідей HTTP

Правила обробки помилок

User Story 1

USE CASE 1 — Успішне отримання та збереження КБВ

Acceptance Criteria

USE CASE 2 — Дані не можуть бути внесені

Acceptance Criteria

USE CASE 3 — Retry при помилках 500 / 502

Acceptance Criteria

USE CASE 4 — Логування помилок в Slack

Acceptance Criteria

USE CASE 5 — Інтеграція не запускається

Acceptance Criteria

USE CASE 6 — Обробка множинних КБВ

Acceptance Criteria

User Story 2. Зупинка запитів в разі отримання помилок 402 або 429

USE CASE

7 — Зупинка запитів після отримання 402

Acceptance Criteria

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

Acceptance Criteria

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

внесення коштів

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

Acceptance Criteria

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

Use Case 3 — Відновлення запитів після внесення коштів

Назва

Acceptance Criteria

Use Case 4 — Відновлення після вичерпання ліміту запитів

Назва

Актори

Передумови

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

Результат

Acceptance Criteria

Додаткове бізнес-правило для ТЗ

Рекомендовані статуси інтеграції

Ключові бізнес-правила (дуже важливо)

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

USE CASE 1 — Успішне отримання та збереження КБВ

Acceptance Criteria

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

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

Назва

Актори

Передумови

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

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

Результат

Acceptance Criteria

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

Назва

Причина