Метою розробки є інтеграція з ЄДР для автоматизації та централізації отримання даних про КБВ (кінцевого бенефеціарного власника) для учасників що є юридичними особами. Даний Дана інформація може бути обовʼязковим/не обовʼязковим для певних процедур (наразі розробка інтеграції відбувається тільки для процедур де є документ з типом x_ultimateBeneficiaryInfo)як обовʼязковою так і не обовʼязковою для певних процедур.

Для реалізації цієї інтеграції необхідно виконати дії:

Додати до базової моделі award необовʼязкову до заповнення поле beneficiaries моделю даних beneficiariesGeneralInfo (модель даних наведено нижче)
Налаштувати інтеграцію з ЄДР де після відпраки відправки запиту заповнюється модель beneficiariesGeneralInfo
При внесенні інформації змінюємо award.dateModified, dateModified (procedure) та systemDateModifiedsystemDateModified
Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)Модель даних beneficiariesGeneralInfo
Технічна назваБізнес назва (x-legalName)ТипRead onlyОбовʼязковість (потребує уточнень)Коментарuk_UAen_USbeneficiaries
Інформація про кінцевого бенефеціарного влсникаInformation about the ultimate beneficial owner
list of objectstruefalse
beneficiariesGeneralInfo
objecttruefalsebeneficialNameПІБ кінцевого бенефеціарного власникаFull name of the ultimate beneficial ownerstring (multilang)truetrueВ запиті Прізвище це відповідь на один запит, Імʼя та По батькові - відповідь на інший запитaddressАдресаAddressmodeltruetrue
beneficiariesType
Тип бенефіціарного володінняType of
beneficiaries
string (multilang)truetrueroleРоль КБВ по відношенню до пов’язаного суб’єктаstringtruetrueВідповідь на запит текстове відображення ролі (roleText)
interest
Відсоток частки статутного капіталу або відсоток права голосуfloat truetrue
indirectInterest
Відсоток частки статутного капіталу або відсоток права голосу у разі непрямого впливуfloattruetrue
otherImpact
Інший характер та міру впливу
beneficiaryFalse
Ознака можливої недостовірності інформації про КБВ
excluded
Ознака виключення відомостей про КБВ за вказівкою Міністерства юстиції України
isMissing
Ознака відсутності КБВ юридичної особи
reason
Причина відсутності КБВ юридичної особи informationDateДата отримання данихDate of informationstring ($dateTime)truetrue

Технічні вимоги до автоматичного збагачення award даними КБВ з ЄДР

Майданчик, залучає користувача до участі в аукціоні де звіт з інформацією про КБВ (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	Сервіс вимкнено або проходить оновлення.

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

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

{"errors":[{"message":"Invalid or expired token","code":2}]}

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

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

Код	Текст	Пояснення
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

...

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

...

Назва

...

ЦБД (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

...

When

...

Then

...

2

...

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

...

When

...

Then

...

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

...

When

...

Then

...

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

...

Назва

...

ЦБД (primary)
ЄДР API (external)

...

Отримано HTTP код:
500, 502

...

ЦБД відправляє запит
Отримує 500 або 502
Виконує retry
Повторює до 3 разів

...

після 3 невдалих спроб → fallback

...

якщо успіх → UC1
якщо ні → запис тексту помилки

Acceptance Criteria

...

1

...

When

...

Then

...

Система повторює запит до 3 разів

...

2

...

Then

...

Записується повідомлення:
"Не вдалось отримати інформацію з сервісу"

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

...

Назва

...

ЦБД (primary)
ЄДР API (external)

...

Отримано HTTP код:
400, 401, 402, 403, 404, 406, 429

...

ЦБД отримує помилку
Формує повідомлення
Відправляє в Slack канал

...

команда отримує alert

Acceptance Criteria

...

1

...

When

...

Then

...

Відправляється повідомлення в Slack

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

...

Назва

...

ЦБД (primary)
ЄДР API (external)

...

Будь-яка з умов НЕ виконується:

- процедура не з переліку
- відсутній x_ultimateBeneficiaryInfo
- не юрособа
- не UA-EDR
- статус award не підходить

...

Створюється award
ЦБД перевіряє умови
Інтеграція НЕ запускається

...

Жодних запитів до ЄДР

Acceptance Criteria

...

1

...

When

...

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

...

When

...

Then

...

User Story 2

...

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

...

Назва

...

ЦБД (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

...

When

...

Then

...

2

...

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

...

When

...

Then

...

3

...

Then

...

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

award.dateModified
dateModified (procedure)
systemDateModified

Use Case 1 —

Назва

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

Актори

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

Передумови

Інтеграція з ЄДР активна
ЦБД направляє запит до ЄДР для отримання даних КБВ
ЄДР повертає HTTP 402
У вимогах уже передбачено фіксацію таких помилок у Slack.

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

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

Результат

Нові запити до ЄДР не направляються.
Команда отримала повідомлення про необхідність внесення коштів.
Дані КБВ для нових awards тимчасово не збагачуються.

Acceptance Criteria

AC1
Given ЦБД отримала від ЄДР відповідь 402
When система обробляє відповідь
Then інтеграція з ЄДР переходить у статус призупинення.

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

AC3
Given отримано 402
When система фіксує помилку
Then повідомлення надсилається в Slack канал.

Use Case 2 — Зупинка запитів після отримання 429

Назва

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

Актори

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

Передумови

Інтеграція з ЄДР активна
ЦБД направляє запит до ЄДР
ЄДР повертає HTTP 429
429 означає, що вичерпано обмеження запитів до ресурсу.

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

ЦБД направляє запит до ЄДР.
ЄДР повертає відповідь 429 Many Requests.
ЦБД фіксує помилку.
ЦБД призупиняє направлення нових запитів до ЄДР.
ЦБД відправляє повідомлення в Slack канал.
Нові awards, які підпадають під інтеграцію, не ініціюють запит до ЄДР.
Система фіксує причину призупинення:
- Перевищено ліміт запитів до ЄДР.

Результат

Інтеграція тимчасово зупинена.
Нові запити до ЄДР не виконуються.
Команда повідомлена про перевищення ліміту.

Acceptance Criteria

AC1
Given ЦБД отримала відповідь 429
When система обробляє відповідь
Then направлення нових запитів до ЄДР зупиняється.

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

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

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

Назва

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

Актори

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

Передумови

Інтеграція з ЄДР була призупинена через 402
Кошти внесено / доступ до сервісу відновлено

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

Відповідальна команда вносить кошти.
Адміністратор ініціює відновлення інтеграції.
ЦБД змінює статус інтеграції з:
- payment_required / suspended
- на active.
ЦБД відновлює направлення запитів до ЄДР.
При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.
Якщо ЄДР повертає 200, дані КБВ обробляються та записуються в award.

Результат

Інтеграція з ЄДР активна.
Нові запити знову направляються.
Дані КБВ можуть бути отримані та внесені в award.

Acceptance Criteria

AC1
Given інтеграція призупинена через 402
And кошти внесено
When адміністратор активує інтеграцію
Then статус інтеграції змінюється на active.

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

...

Business flow

Майданчик, залучає користувача до участі в аукціоні де звіт з інформацією про КБВ

Учасник є юридичною особою
Учасник подає заявку на участь
Майданчик активує заявку на участь
Заявка на участь перейшла в кваліфікацію
Під час створення award ЦБД направляє асинхроний запит в ЄДР зі статичним API Token і даними для пошуку де виконуються умови:
1. Для award в статусах: pending_waiting, pending_admission, pending
2. Для award.buyers.identifier.UA-EDR
3. Для процедур з переліку процедур
  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

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

Аутентифікація до API ЄДР здійснюється за допомогою статичного API токена.

Токен передається у заголовку: Authorization: Token {API_TOKEN}

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

Формат відповіді визначається заголовком: Accept: application/json

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

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

Аутентифікація за API Token
Передача API Token у заголовку Authorization
Метод отримання унікального ідентифікатора
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, наприклад:

{"errors":[{"message":"Invalid or expired token","code":2}]}

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

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

Код	Текст	Пояснення
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.

Технічні вимоги до автоматичного збагачення award даними КБВ з ЄДР

Модель даних beneficiaries

Поле в award

beneficiaries: [beneficiariesGeneralInfo ]

Правила

тип: list of objects
може містити: кілька КБВ або визначення причини відсутності даних (excluded, isMissing,reason) або status має значення error .

Expand

title	Модель даних beneficiaries

Технічна назва			Бізнес назва (x-legalName)		Тип	Read only	Обовʼязковість (потребує уточнень)	Коментар
Технічна назва			uk_UA	en_US	Тип	Read only	Обовʼязковість (потребує уточнень)	Коментар
beneficiaries			Інформація про кінцевого бенефеціарного влсника	Information about the ultimate beneficial owner	list of objects	true	false
	status		Статус обробки даних	Status of data	string	true	false	enum [processing, complete, error]
	errorReason		Причина помилки	Error reason	string	true	false	Записується тільки якщо значення status = error
	excluded		Ознака виключення відомостей про КБВ за вказівкою Міністерства юстиції України		string	true	false
	isMissing		Ознака відсутності КБВ юридичної особи		string	true	false
	reason		Причина відсутності КБВ юридичної особи		string (multilang)	true	false
	informationDate		Дата отримання даних	Date of information	string ($dateTime)	true	true
	beneficiariesGeneralInfo				object	true	false	Може бути декілька. Якщо хоча б один КБВ невалідний → НЕ записується жоден
		beneficialName	ПІБ кінцевого бенефеціарного власника	Full name of the ultimate beneficial owner	string (multilang)	true	true	В запиті Прізвище це відповідь на один запит, Імʼя та По батькові - відповідь на інший запит
		address	Адреса	Address	model	true	true
		beneficiariesType	Тип бенефіціарного володіння	Type of beneficiaries	string (multilang)	true	true
		role	Роль КБВ по відношенню до пов’язаного суб’єкта		string	true	true	Відповідь на запит текстове відображення ролі (roleText)
		interest	Відсоток частки статутного капіталу або відсоток права голосу		float	true	true
		indirectInterest	Відсоток частки статутного капіталу або відсоток права голосу у разі непрямого впливу		float	true	true
		otherImpact	Інший характер та міру впливу
		beneficiaryFalse	Ознака можливої недостовірності інформації про КБВ

Ключові правила

Інтеграція тригериться тільки при створенні award в модель даних beneficiariesGeneralInfo
Запит асинхронний
Дані записуються тільки якщо валідні
Запис — атомарний (все або нічого):
1. або записуються всі КБВ (якщо хоча б один КБД не валідний - не записується жоден)
2. або записується один fallback - обʼєкт
3. Основний сценарій:
4. Створюється award
5. Перевіряються умови
6. Виконується аутентифікація в ЄДР
7. Виконується запит до ЄДР
8. Отримується відповідь
9. Відбувається валідація
10. Якщо валідно:
  - запис у award.beneficiaries[]
  - оновлення:
    - award.dateModified
    - procedure.dateModified
    - systemDateModified
Retry (до 3 разів) тільки для: 500, 502
1. retry з exponential backoff
2. після 3 спроб → beneficiaries.status = error
API_TOKEN зберігається:
- у захищеному конфігураційному середовищі
- не логуються
- не передається у відкритому вигляді
Порожній результат (200 без даних) НЕ є помилкою API, але вимагає fallback
Асинхронність має пріоритет над статусом award — відповідь завжди обробляється
Timeout прирівнюється до технічної помилки (500/502)

Обмеження

Система не повинна виконувати безкінечні повторні запити.
Інтеграція не виконується без умов
Частковий запис даних заборонений
У межах POC система не виконує:
1. Автоматичну ретро-обробку awards, створених під час зупинки інтеграції.
2. Масовий ручний запуск має мати обмеження на кількість awards за одну операцію.
3. Ручний запуск має бути доступний тільки користувачам з відповідними адміністративними правами.
4. Ручний запуск має пріоритет над статусом інтеграції
5. Ручний запуск НЕ залежить від моменту створення award
6. Масовий запуск має виконуватись асинхронно
7. Повторний запуск перезаписує beneficiaries
8. Обмеження на масовий запуск (наприклад, ≤100 awards)

Статуси обробки даних

Статус	Опис
processing	Триває обробка даних
complete	Дані внесено
error	Не вдалось отримати інформацію з сервісу

Послідовність зміни статусів

При створенні відправці даних для отримання даних з ЄДР про КБВ beneficiaries.status змінюється на processing
При правильному отриманні відповіді 200 з даними beneficiaries.status змінюється з processing на complete
При отриманні помилки beneficiaries.status змінюється з processing на error і в залежності від типу помилки відправляється повідомлення РО

Статуси інтеграції

Статус	Опис
`active`	Запити до ЄДР виконуються
`payment_required`	Отримано 402, запити зупинено
`rate_limit_exceeded`	Отримано 429, запити зупинено
`suspended`	Інтеграцію вручну зупинено адміністратором
auth_error	Проблема з токеном
access_denied	403
invalid_request	400/406

Статус suspended_manual має пріоритет над автоматичними статусами.

Обробка помилок

Класифікація помилок

Тип	Коди
Tech	500, 502
Auth	401
Business	402, 429
Access	403
Data	400, 404, 406

Таблиця зведених правил обробки помилок

HTTP code	Retry	Зупинка інтеграції	Slack	Дія
400	Ні	Ні (можливо)	Так	помилка запиту
401	Ні	Так / auth_error	Так	невалідний або відкликаний API Token
402	Ні	Так	Так	очікування оплати
403	Ні	Ні (можливо)	Так	перевірка доступу
404	Ні	Ні	Ні	суб'єкт відсутній
406	Ні	Ні (можливо)	Так	помилка формату
429	НІ	Так	Так	перевищено ліміт
500	Так (3 рази)	Ні	Ні	тимчасова помилка
502	Так (3 рази)	Ні	Ні	сервіс недоступний

Правила додаткової обробки помилок

Обробка 401
1. означає невалідний або відкликаний токен
2. retry НЕ виконується
3. надсилається Slack alert
4. статус інтеграції → auth_error
Обробка 404
1. Отримано 404
2. зміна beneficiaries.status з processing на error

Slack повідомлення

Відправляються для:

400
402
403
406
429
auth_error

Зупинка інтеграції

Тригер

Інтеграція зупиняється при:

першому 402
першому 429

Поведінка

всі нові запити НЕ виконуються
статус інтеграції змінюється

Відновлення інтеграції

Після 402
1. внесення коштів
2. ручне відновлення
3. статус → active
Після 429
1. відновлення ліміту
2. ручне відновлення
3. статус → active

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

Після відновлення інтеграції система обробляє тільки нові awards, створені після зміни статусу інтеграції на active.
Awards, створені під час зупинки інтеграції, автоматично не обробляються повторно в межах POC.
За потреби такі awards можуть бути оброблені через ручний запуск з адмінки.

Info

title	Важливо

Старі awards НЕ обробляються повторно після відновлення інтеграції - для POC
Для етапу розробки адмінки треба передбачити

Ручна зупинка інтеграції
Ручне відновлення інтеграції (є окремим сценарієм і не вважається автоматичною ретро-обробкою)
Ручний запуск інтеграції по конкретному аварду, або переліку авардів (множинний вибір)
1. Масовий ручний запуск має виконуватись через чергу задач.
2. При повторному запуску по award дані beneficiaries перезаписуються.

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

Адміністратор має можливість:

Вручну зупинити інтеграцію;
Вручну відновити інтеграцію;
Запустити інтеграцію для конкретного award;
Запустити інтеграцію для переліку awards через множинний вибір.

Ручний запуск інтеграції по award виконує стандартну логіку запиту до ЄДР та обробки відповіді.

Ручний запуск не залежить від тригера створення award.

Для масового запуску обробка має виконуватись асинхронно через чергу.

Логування

Обовʼязково логувати:

correlationId
request/response
error code
retry count

Timeout

timeout = 5-10 секунд
retry = ексоненційна затримка

Сценарії роботи інтеграції з ЄДР

User Story 1. Автоматичне отримання КБВ

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

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

Назва	Отримання та запис КБВ з ЄДР в award
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Процедура входить в перелік дозволених (LLE, LLD, …, SUD) Учасник є юридичною особою award.buyers.identifier.scheme = UA-EDR award.status ∈ {pending_waiting, pending_admission, pending} інтеграція має статус active
Основний сценарій	Дані невалідні → UC2 Помилка API → UC3/UC11-15 Учасник подає заявку Майданчик активує заявку Заявка переходить у кваліфікацію ЦБД створює `award` ЦБД перевіряє умови запуску інтеграції ЦБД змінює beneficiaries.status на processing ЦБД формує запит до ЄДР із заголовками: Authorization: Token {API_TOKEN} Accept: application/json ЦБД відправляє запит до ЄДР з `code = ЄДРПОУ` ЄДР повертає дані КБВ (може бути список) ЦБД валідовує відповідь Дані відповідають моделі `beneficiariesGeneralInfo` ЦБД записує дані в `award.beneficiaries` ЦБД змінює beneficiaries.status з processing на complete Оновлює: `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)
Передумови	Отримано відповідь ЄДР
Основний сценарій	ЦБД отримує дані Перевіряє дані на відповідність моделі даних Якщо дані: неповні / некоректні / не мапляться ЦБД НЕ записує дані ЦБД змінює beneficiaries.status з processing на error
Альтернативний сценарій	Всі КБВ валідні → UC1
Результат	award без змін

Acceptance Criteria

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

...

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

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

Acceptance Criteria

1	Given	Отримано 500/502
	When	Виконується retry
	Then	Система повторює запит до 3 разів
2	Given	Всі retry невдалі
2	Then	beneficiaries.status змінюється з processing на error

...

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

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

Acceptance Criteria

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

...

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

Назва	Запис кількох бенефіціарів
Актори	ЦБД (primary) ЄДР API (external)
Передумови	Виконується UC1 ЄДР повертає список КБВ
Основний сценарій	ЦБД мапить кожен запис (кожен КБВ проходить однаковий mapping) Формує list of objects Записує в `award.beneficiaries[]` усі КБВ з відповіді ЄДР зберігаються, а не тільки перший; порядок не змінюється
Альтернативний сценарій	хоча б один невалідний КБВ → UC2
Результат	Збережено всі КБВ

Acceptance Criteria

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

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

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

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

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

Acceptance Criteria

1	Given	ЦБД отримала від ЄДР відповідь `402`
	When	Система обробляє відповідь
	Then	Інтеграція з ЄДР переходить у статус призупинення.
2	Given	Інтеграція має статус призупинення через `402`
	When	Створюється новий award, який відповідає умовам інтеграції
	Then	ЦБД не направляє запит до ЄДР.
3	Given	Отримано `402`
	When	Система фіксує помилку
	Then	Повідомлення надсилається в Slack канал.

...

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

Назва	Автоматичне призупинення інтеграції з ЄДР при помилці `429 Many Requests`
Актори	ЦБД ЄДР Slack канал Адміністратор/відповідальна команда
Передумови	Інтеграція з ЄДР активна ЄДР повертає HTTP `429 (`означає, що вичерпано обмеження запитів до ресурсу)
Основний сценарій	ЦБД направляє запит до ЄДР. ЄДР повертає відповідь `429 Many Requests`. ЦБД фіксує помилку. ЦБД змінює внутрішній статус інтеграції з ЄДР на → rate_limit_exceeded ЦБД призупиняє направлення нових запитів до ЄДР. ЦБД відправляє повідомлення в Slack канал. (`Перевищено ліміт запитів до ЄДР`) Нові awards, які підпадають під інтеграцію, не ініціюють запит до ЄДР.
Результат	Інтеграція тимчасово зупинена. Нові запити до ЄДР не виконуються. Команда повідомлена про перевищення ліміту. Дані КБВ для нових awards тимчасово не збагачуються.

Acceptance Criteria

1	Given	ЦБД отримала відповідь `429`
	When	Система обробляє відповідь
	Then	Направлення нових запитів до ЄДР зупиняється.
2	Given	Інтеграція призупинена через `429`
	When	Створюється новий award
	Then	ЦБД не направляє запит до ЄДР
3	Given	Отримано `429`
	When	Система обробляє помилку
	Then	Повідомлення надсилається в Slack канал.

...

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

Назва	Ручне або автоматичне відновлення інтеграції з ЄДР після внесення коштів
Актори	Адміністратор/відповідальна команда ЦБД ЄДР
Передумови	Інтеграція з ЄДР була призупинена через `402` Статус інтеграці = payment_required Кошти внесено / доступ до сервісу відновлено
Основний сценарій	Відповідальна команда вносить кошти. Адміністратор ініціює відновлення інтеграції. ЦБД змінює статус інтеграції з payment_required на active ЦБД відновлює направлення запитів до ЄДР. При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР. Якщо ЄДР повертає `200`, дані КБВ обробляються та записуються в `award`.
Результат	Інтеграція з ЄДР активна. Запити до ЄДР відновлені. Система продовжує автоматичне збагачення awards даними КБВ.

Acceptance Criteria

1	Given	Інтеграція призупинена через `402`
	And	Кошти внесено
	When	Адміністратор активує інтеграцію
	Then	Статус інтеграції змінюється на `active`.
2	Given	Інтеграція активна після відновлення
	When	Створюється новий award
	Then	ЦБД направляє запит до ЄДР
3	Given	ЄДР після відновлення повертає `200`
	When	ЦБД отримує валідні дані
	Then	Дані записуються в `award.beneficiaries`

...

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

Назва	Відновлення інтеграції після помилки `429`
Актори	Адміністратор/відповідальна команда ЦБД ЄДР
Передумови	Інтеграція була призупинена через `429` Статус інтеграці = rate_limit_exceeded Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу
Основний сценарій	Відповідальна команда перевіряє, що ліміт запитів відновлено. Адміністратор активує інтеграцію. ЦБД змінює статус інтеграції з rate_limit_exceeded на active Наступні awards знову запускають запит до ЄДР. Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.
Результат	Інтеграція з ЄДР активна. Запити до ЄДР відновлені. Система продовжує автоматичне збагачення 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 10 — Обробка 401 Unauthorized при невалідному API Token

Назва	Автоматичне оновлення токена при помилці 401
Актори	ЦБД ЄДР Slack
Передумови	Запит до ЄДР виконано Отримано `401 Unauthorized`
Основний сценарій	ЦБД отримує 401 Визначає, що токен невалідний НЕ виконує retry Надсилає Slack alert Статус інтеграції → `auth_error`
Результат	Інтеграція відновлюється без втручання людини або помилка auth

Acceptance Criteria

1	Given	Отримано 401
	When	Система обробляє відповідь
	Then	Retry не виконується
2	Given	Отримано 401
	When	Система фіксує помилку
	Then	Статус інтеграції змінюється на auth_error
3	Given	Отримано 401
	When	Система фіксує помилку
	Then	Повідомлення надсилається в Slack канал
4	Given	Статус інтеграції = auth_error
	When	Створюється новий award, який відповідає умовам інтеграції
	Then	Запит до ЄДР не виконується до заміни/актуалізації API Token

...

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

Назва	Обробка некоректного запиту до ЄДР
Актори	ЦБД ЄДР Slack
Передумови	Запит до ЄДР виконано Отримано `400`
Основний сценарій	ЦБД отримує `400` Аналізує помилку Визначає: помилка у формуванні запиту НЕ виконує retry Логує помилку Надсилає повідомлення в Slack Переводить інтеграцію в статус invalid_request
Рішення	Виправлення формату запиту (dev fix)
Результат	запит не повторюється потрібне втручання розробника

Acceptance Criteria

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

...

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

Назва	Обробка відсутності прав доступу
Актори	ЦБД ЄДР Slack
Передумови	Запит до ЄДР виконано Отримано `403` змінились права доступу до API акаунт не має доступу
Основний сценарій	ЦБД отримує `403` Аналізує помилку НЕ виконує retry Відправляє повідомлення в Slack Переводить інтеграцію в статус `access_denied`
Рішення	перевірка прав доступу перевидача ключів / ролей
Результат	Інтеграція не працює до виправлення

Acceptance Criteria

1

Given

Отримано 403

Then

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

And

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

...

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

Назва	Обробка відсутності суб’єкта в ЄДР
Актори	ЦБД ЄДР Slack
Передумови	Запит до ЄДР виконано Отримано `404`
Основний сценарій	ЦБД отримує `404` Аналізує помилку Визначає, що суб'єкт відсутній НЕ виконує retry Змінює beneficiaries.status з processing на error
Результат	award без КБВ award містить beneficiaries.status = error

Acceptance Criteria

1

Given

Отримано 404

Then

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

And

Змінює beneficiaries status з processing на error

...

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

Назва	Обробка помилки формату даних
Актори	ЦБД ЄДР Slack
Передумови	Запит до ЄДР виконано Отримано `406`
Основний сценарій	ЦБД отримує `406` ЦБД змінює beneficiaries.status з processing на error Аналізує помилку НЕ виконує retry Відправляє alert в Slack Переводить інтеграцію в статус invalid_request
Рішення	перевірка контракту API виправлення формату
Результат	інтеграція не виконується для цього запиту

Acceptance Criteria

1

Given

Отримано 406

Then

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

And

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

User Story 4. Обробка випадків, коли дані не знайдені або недоступні

Як	ЦБД Prozorro.Sale
я хочу	оректно обробляти випадки, коли ЄДР не повертає дані або повертає пустий результат
щоб	забезпечити прозору причину відсутності КБВ у системі

USE CASE 15 — Порожній результат (200, але без даних)

Назва	Суб’єкт не знайдений за кодом ЄДРПОУ (порожній результат)
Актори	ЦБД ЄДР
Передумови	Інтеграція з ЄДР активна Запит до ЄДР виконано ЄДР повертає HTTP 200 Список `beneficiaries` порожній
Основний сценарій	ЦБД отримує відповідь 200 Перевіряє тіло відповіді Визначає, що список результатів порожній Не виконує заповнення КБВ ЦБД змінює beneficiaries.status з processing на error Записує fallback з причиною
Результат	Інтеграція зупинена Нові запити до ЄДР не направляються. Команда отримала повідомлення про необхідність внесення коштів. Дані КБВ для нових awards тимчасово не збагачуються.

Acceptance Criteria

1	Given	ЦБД отримала від ЄДР відповідь `200`
	And	Список результатів порожній
	When	Система обробляє відповідь
	Then	КБВ не заповнюються
2	Given	Пустий результат
2	Then	Змінює в beneficiaries status з processing на error

...

User Story 5. Узгодженість даних при зміні статусу award

Як	ЦБД Prozorro.Sale
я хочу	завершувати обробку запиту до ЄДР навіть якщо статус award змінився
щоб	уникнути втрати даних через асинхронність

USE CASE 16 — Award змінив статус під час запиту

Назва	Обробка відповіді ЄДР після зміни статусу award
Актори	ЦБД ЄДР
Передумови	Запит до ЄДР вже відправлений Award змінив статус (наприклад: дискваліфіковано cancelled unsuccessful)
Основний сценарій	ЦБД відправляє запит Award змінює статус ЦБД отримує відповідь від ЄДР НЕ перевіряє актуальний статус award Обробляє відповідь за стандартною логікою: або запис КБВ або fallback
Результат	Дані КБВ (або fallback) збережені незалежно від статусу award

Acceptance Criteria

1	Given	Запит до ЄДР відправлено
	And	Award змінив статус
	When	Отримано відповідь
	Then	Відповідь обробляється
	And	Дані записуються незалежно від поточного статусу award

...

User Story 6. Обробка timeout

Як	ЦБД Prozorro.Sale
я хочу	коректно обробляти timeout від ЄДР
щоб	забезпечити стабільність інтеграції

USE CASE 17 — Timeout від ЄДР

Назва	Обробка перевищення часу очікування відповіді
Актори	ЦБД ЄДР
Передумови	Запит відправлено Відповідь не отримано в межах timeout (5–10 сек)
Основний сценарій	ЦБД очікує відповідь Timeout перевищено ЦБД фіксує помилку Виконує retry (як для 500/502) До 3 спроб
Альтернативний сценарій	retry успішний → UC1 retry неуспішний → ЦБД змінює beneficiaries.status з processing на error
Результат	або отримані дані beneficiaries.status = error

Acceptance Criteria

1	Given	Перевищено timeout
	When	Система обробляє запит
	Then	Виконується retry
2	Given	Retry неуспішний
2	Then	Записується fallback

...

User Story 7. Відсутність автоматичної ретро-обробки

Як	ЦБД Prozorro.Sale
я хочу	Не обробляти старі awards після відновлення інтеграції
щоб	Уникнути неочікуваного навантаження та складної логіки в межах POC

USE CASE 18 — Відсутність ретро-обробки

Назва	Обробка перевищення часу очікування відповіді
Актори	ЦБД Адміністратор
Передумови	Інтеграція була в статусі: `payment_required` або `rate_limit_exceeded` або `suspended_manual` Існують awards без КБВ Інтеграцію переведено в `active`
Основний сценарій	Інтеграція відновлюється Система НЕ виконує повторну обробку існуючих awards Нові awards обробляються стандартно
Альтернативний сценарій	Адміністратор запускає ручну обробку → UC21/UC22
Результат	Старі awards залишаються без змін

Acceptance Criteria

1	Given	Інтеграція була зупинена
	And	Існують awards без КБВ
	When	Інтеграція відновлена
	Then	Обробляються тільки нові awards
2	Given	Існують старі awards
2	Then	Вони НЕ обробляються автоматично

...

User Story 8. Ручне керування інтеграцією

Як	Адміністратор ЦБД Prozorro.Sale
я хочу	Мати можливість вручну керувати інтеграцією
щоб	Контролювати її роботу незалежно від автоматичних сценаріїв

USE CASE 19 — Ручна зупинка інтеграції

Назва	Зупинка інтеграції через Адміністративну панель
Актори	ЦБД Адміністратор
Передумови	Статус інтеграції = `active`
Основний сценарій	Адміністратор відкриває адмінку Натискає “Зупинити інтеграцію” Система встановлює статус → `suspended` Нові запити до ЄДР не виконуються
Результат	Інтеграція зупинена вручну

Acceptance Criteria

1	Given	Інтеграція активна
	When	Адміністратор її зупиняє
	Then	Статус = suspended
	And	Запити до ЄДР не виконуються

...

USE CASE 20 — Ручне відновлення інтеграції

Назва	Відновлення інтеграції через Адміністративну панель
Актори	ЦБД Адміністратор
Передумови	Статус: `suspended` або `payment_required` або `rate_limit_exceeded`
Основний сценарій	Адміністратор натискає “Відновити” Система змінює статус → `active` Запити до ЄДР дозволяються
Результат	Інтеграція відновлена

Acceptance Criteria

1

Given

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

When

Адміністратор її відновлює

Then

Статус = active

...

User Story 9. Ручний запуск інтеграції для awards

Як	Адміністратор ЦБД Prozorro.Sale
я хочу	Запускати інтеграцію для конкретних awards
щоб	Обробляти пропущені або проблемні записи

USE CASE 21 — Ручний запуск для одного award

Назва	Зупинка інтеграції через Адміністративну панель
Актори	ЦБД Адміністратор
Передумови	Award існує Користувач має права адміністратора
Основний сценарій	Адміністратор обирає award (id) Натискає “Запустити інтеграцію” Система: ігнорує тригер “тільки при створенні award” формує запит до ЄДР Обробляє відповідь стандартно Оновлює beneficiaries
Альтернативний сценарій	Інтеграція глобально зупинена → ручний запуск дозволений
Результат	beneficiaries оновлено

Acceptance Criteria

1	Given	Обрано award
	When	Адміністратор запускає інтеграцію
	Then	Виконується запит до ЄДР
	And	beneficiaries перезаписуються

...

USE CASE 22 — Масовий запуск інтеграції

Назва	Зупинка інтеграції через Адміністративну панель
Актори	ЦБД Адміністратор
Передумови	Обрано список існуючих awards Користувач має права адміністратора
Основний сценарій	Адміністратор обирає кілька awards (id) Натискає “Запустити для вибраних” Система: формує список задач відправляє їх у чергу Кожен award обробляється окремо
Альтернативний сценарій	перевищено ліміт → операція блокується
Результат	всі awards оброблені асинхронно

Acceptance Criteria

1	Given	Обрано список awards
	When	Запускається обробка
	Then	Кожен award обробляється незалежно
2	Given	Масовий запуск
2	Then	Обробка виконується через чергу

...

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 33

New Version Current

Key

Технічні вимоги до автоматичного збагачення award даними КБВ з ЄДР

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

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

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

Оновлення 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

Acceptance Criteria

User Story 2

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

Acceptance Criteria

Use Case 1 —

Назва

Актори

Передумови

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

Результат

Acceptance Criteria

Use Case 2 — Зупинка запитів після отримання 429

Назва

Актори

Передумови

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

Результат

Acceptance Criteria

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

Назва

Актори

Передумови

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

Результат

Acceptance Criteria

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

Назва

Актори

Передумови

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

Результат

Acceptance Criteria

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

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

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

Business flow

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

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

Аутентифікація за API Token

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

Метод: POST

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

Помилки

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

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

Технічні вимоги до автоматичного збагачення award даними КБВ з ЄДР

Модель даних beneficiaries

Ключові правила