Versions Compared

Old Version 54

changes.mady.by.user valeriia denysenko

Saved on

compared with

New Version Current

changes.mady.by.user valeriia denysenko

Saved on

Key

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

...

  1. тип: list of objects
  2. може містити: кілька КБВ або fallback-записвизначення причини відсутності даних (excluded, isMissing,reason) або status має значення error .
Expand
titleМодель даних beneficiaries
 string
Технічна назваБізнес назва (x-legalName)ТипRead onlyОбовʼязковість (потребує уточнень)Коментар
uk_UAen_US
beneficiaries
Інформація про кінцевого бенефеціарного влсникаInformation about the ultimate beneficial owner
list of objectstruefalse
 

fallbackstatus

  Статус обробки даних Status of dataobjectstringtruefalseМоже бути тільки один в разі відсутності даних про КБВenum [processing, complete, error]
 

systemReason

Системна причина відсутності данихSystemic reason for missing data

errorReason

Причина помилкиError reasonstringtruefalseЗаписується тільки якщо значення status = error
 

excluded

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

isMissing

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

reason

 Причина відсутності КБВ юридичної особи string (multilang)truefalse
 

informationDate

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

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

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


...

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

...

  1. Система не повинна виконувати безкінечні повторні запити.
  2. Інтеграція не виконується без умов
  3. Частковий запис даних заборонений

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

СтатусОпис
activeЗапити до ЄДР виконуються
payment_requiredОтримано 402, запити зупинено
rate_limit_exceededОтримано 429, запити зупинено
suspendedЗагальний статус призупинення
auth_errorПроблема з токеном
access_denied403
invalid_request400/406

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

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

...

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

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

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

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

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

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

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

400/406

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

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

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

ТипКоди
Tech500, 502
Auth401
Business402, 429
Access403
Data400, 404, 406

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

HTTP codeRetryЗупинка інтеграціїSlackДія
400НіНі

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

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

...

  1. Обробка 401

    1. означає невалідний або відкликаний токен

    2. retry НЕ виконується

    3. надсилається Slack alert

    4. статус інтеграції → auth_error

  2. Обробка 404
    1. Отримано 404
    2. запис в поле beneficiaries.fallback.systemReason = "Суб'єкт не знайдено в ЄДР"зміна  beneficiaries.status з processing на error

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

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

...

  1. Після 402

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

    2. ручне відновлення

    3. статус → active

  2. Після 429

    1. відновлення ліміту

    2. ручне відновлення
    3. статус → active

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

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

Info
titleВажливо

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

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

    Логування

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

    • correlationId
    • request/response
    • error code
    • retry count

    Timeout

      1. Масовий ручний запуск має виконуватись через чергу задач.
      2. При повторному запуску по award дані beneficiaries перезаписуються.

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

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

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

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

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

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

    Логування

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

    • correlationId
    • request/response
    • error code
    • retry count

    Timeout

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

    ...

    Назва

    		Отримання та запис КБВ з ЄДР в 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

    1. Учасник подає заявку
    2. Майданчик активує заявку
    3. Заявка переходить у кваліфікацію
    4. ЦБД створює award
    5. ЦБД перевіряє умови запуску інтеграції
    6. ЦБД змінює beneficiaries.status на processing
    7. ЦБД формує запит до ЄДР із заголовками:
      1. Authorization: Token {API_TOKEN}
      2. Accept: application/json
    8. ЦБД відправляє запит до ЄДР з code = ЄДРПОУ
    9. ЄДР повертає дані КБВ (може бути список)
    10. ЦБД валідовує відповідь
    11. Дані відповідають моделі beneficiariesGeneralInfo
    12. ЦБД записує дані в award.beneficiaries
    13. ЦБД змінює beneficiaries.status з processing на complete
    14. Оновлює:
    • award.dateModified
    • procedure.dateModified
    • systemDateModified
    Результат

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

    ...

    Назва

    		Відмова у записі КБВ
    Актори
    • ЦБД (primary)
    • ЄДР API (external)
    Передумови

    Отримано відповідь ЄДР

    Основний сценарій
    1. ЦБД отримує дані
    2. Перевіряє дані на відповідність моделі даних
    3. Якщо дані:
      • неповні / некоректні / не мапляться
    4. ЦБД НЕ записує дані
    5. ЦБД змінює beneficiaries.status з processing на error
    Альтернативний сценарійВсі КБВ валідні → UC1
    Результат

    award без змін

    ...

    Назва

    		Повторна спроба отримання даних
    Актори
    • ЦБД (primary)
    • ЄДР API (external)
    Передумови

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

    Основний сценарій
    1. ЦБД відправляє запит
    2. Отримує 500 або 502
    3. Виконує retry
    4. Повторює до 3 разів
    5. Якщо успіх → UC1
    Альтернативний сценарій

    Всі retry невдалі → UC4 beneficiaries.status змінюється з processing на error

    Результат
    • або дані записані
    • 500/502: Slack alert не відправляється на кожну помилку, але відправляється після 3 невдалих retry.

    ...

    1

    		GivenОтримано 500/502

    When

    		Виконується retry

    Then

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

    2

    		GivenВсі retry невдалі

    Then

    Записується повідомлення в поле beneficiaries.fallback.systemReason:
    "Не вдалось отримати інформацію з сервісу"status змінюється з processing на error


    ...


    USE CASE 4 —

    ...

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

    Назва

    Внесення системної помилки    		Неініціювання запиту до ЄДР
    Актори

    ЦБД (primary)

    Передумови

    retry завершився невдачею

    Основний сценарій
    1. Формується fallback-об’єкт
    2. Записується в beneficiaries.fallback.systemReason
    Результат

    award містить fallback

    Acceptance Criteria

    ...

    1

    ...

    Then

    ...

    AND

    ...

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

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

    Назва

    		Неініціювання запиту до ЄДР
    Актори

    ЦБД (primary)

    Передумови

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

    • процедура не з визначеного переліку
    • відсутній x_ultimateBeneficiaryInfo
    • не юрособа
      • award.buyers.identifier.scheme ≠ UA-EDR
    • статус award не підходить
    Основний сценарій
    1. Створюється award
    2. ЦБД перевіряє умови
    3. Інтеграція НЕ запускається
    Результат

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

    Acceptance Criteria

    1

    		GivenУмови не виконані

    When

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

    Then

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


    ...

    USE CASE

    ...

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

    Назва

    		Запис кількох бенефіціарів
    Актори
    • ЦБД (primary)
    • ЄДР API (external)
    Передумови
    • Виконується UC1 
    • ЄДР повертає список КБВ
    Основний сценарій
    1. ЦБД мапить кожен запис (кожен КБВ проходить однаковий mapping)
    2. Формує list of objects
    3. Записує в award.beneficiaries[]
    4. усі КБВ з відповіді ЄДР зберігаються, а не тільки перший;
    5. порядок не змінюється
    Альтернативний сценарійхоча б один невалідний КБВ → UC2→ 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
    Основний сценарій
    1. ЦБД направляє запит до ЄДР.
    2. ЄДР повертає відповідь 402 Payment Required.
    3. ЦБД фіксує помилку
    4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → payment_required
    5. ЦБД припиняє направлення нових запитів до ЄДР.
    6. ЦБД відправляє повідомлення в Slack канал.
    7. Для нових 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 (означає, що вичерпано обмеження запитів до ресурсу)
    Основний сценарій
    1. ЦБД направляє запит до ЄДР.
    2. ЄДР повертає відповідь 429 Many Requests.
    3. ЦБД фіксує помилку.
    4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → rate_limit_exceeded
    5. ЦБД призупиняє направлення нових запитів до ЄДР.
    6. ЦБД відправляє повідомлення в Slack канал. (Перевищено ліміт запитів до ЄДР)
    7. Нові 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
    • Кошти внесено / доступ до сервісу відновлено
    Основний сценарій
    1. Відповідальна команда вносить кошти.
    2. Адміністратор ініціює відновлення інтеграції.
    3. ЦБД змінює статус інтеграції з payment_required на active
    4. ЦБД відновлює направлення запитів до ЄДР.
    5. При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.
    6. Якщо ЄДР повертає 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
    • Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу
    Основний сценарій
    1. Відповідальна команда перевіряє, що ліміт запитів відновлено.
    2. Адміністратор активує інтеграцію.
    3. ЦБД змінює статус інтеграції з rate_limit_exceeded на active
    4. Наступні awards знову запускають запит до ЄДР.
    5. Якщо ЄДР повертає успішну відповідь — дані обробляються за стандартним сценарієм.
    Результат
    • Інтеграція з ЄДР активна.
    • Запити до ЄДР відновлені.
    • Система продовжує автоматичне збагачення awards даними КБВ.
    		РезультатЗбережено всі КБВ
    Acceptance Criteria

    1

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

    When

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

    And

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

    Then

    ЄДР повертає кілька КБВ    		ЦБД знову направляє запити до ЄДР

    2


    		Given

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

    When

    Відбувається     		записСтворюється award

    Then

    Всі КБВ зберігаються в масиві    		Запит до ЄДР виконується

    User Story

    ...

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

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

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

    ...

    Назва

    ...

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

    ...

    • Інтеграція з ЄДР активна
    • ЄДР повертає HTTP 402

    ...

    1. ЦБД направляє запит до ЄДР.
    2. ЄДР повертає відповідь 402 Payment Required.
    3. ЦБД фіксує помилку
    4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → payment_required
    5. ЦБД припиняє направлення нових запитів до ЄДР.
    6. ЦБД відправляє повідомлення в Slack канал.
    7. Для нових awards, які підпадають під умови інтеграції, запит до ЄДР не виконується.

    ...

    • Інтеграція зупинена
    • Нові запити до ЄДР не направляються.
    • Команда отримала повідомлення про необхідність внесення коштів.
    • Дані КБВ для нових awards тимчасово не збагачуються.
    коректно обробляти всі типи помилок від ЄДР (400, 401, 403, 404, 406, 500, 502)
    щобзабезпечити стабільну роботу системи, не втрачати дані та мати можливість відновлення інтеграції

    USE CASE 10 — Обробка 401 Unauthorized при невалідному API Token

    Назва

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

    2

    1

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

    When

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

    Then

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

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

    When

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

    Then

    		ЦБД не направляє запит до ЄДР.Retry не виконується

    23


    		Given

    Отримано

    402

    401

    When

    		Система фіксує помилку

    Then

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

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

    ...

    Назва

    ...

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

    ...

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

    ...

    1. ЦБД направляє запит до ЄДР.
    2. ЄДР повертає відповідь 429 Many Requests.
    3. ЦБД фіксує помилку.
    4. ЦБД змінює внутрішній статус інтеграції з ЄДР на → rate_limit_exceeded
    5. ЦБД призупиняє направлення нових запитів до ЄДР.
    6. ЦБД відправляє повідомлення в Slack канал. (Перевищено ліміт запитів до ЄДР)
    7. Нові awards, які підпадають під інтеграцію, не ініціюють запит до ЄДР.

    ...

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

    ...

    1

    ...

    When

    ...

    Then

    ...

    2

    ...

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

    ...

    When

    ...

    Then

    ...

    3

    ...

    Then

    ...

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

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

    ...

    Назва

    ...

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

    ...

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

    ...

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

    ...

    • Інтеграція з ЄДР активна.
    • Запити до ЄДР відновлені.
    • Система продовжує автоматичне збагачення awards даними КБВ.
    Статус інтеграції змінюється на 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
    Основний сценарій
    1. ЦБД отримує 400
    2. Аналізує помилку
    3. Визначає:
      • помилка у формуванні запиту
    4. НЕ виконує retry
    5. Логує помилку
    6. Надсилає повідомлення в Slack
    7. Переводить інтеграцію в статус invalid_request
    Рішення

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

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

    1


    		GivenОтримано 400

    When

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

    Then

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

    And

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


    ...

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

    Назва

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

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

    Acceptance Criteria

    1


    		GivenОтримано 403

    Then

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

    And

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


    ...

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

    Назва

    		Обробка відсутності суб’єкта в ЄДР
    Актори
    • ЦБД
    • ЄДР
    • Slack
    Передумови
    • Запит до ЄДР виконано
    • Отримано 404
    Основний сценарій
    1. ЦБД отримує 404
    2. Аналізує помилку
    3. Визначає, що суб'єкт відсутній
    4. НЕ виконує retry
    5. Змінює 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
    Основний сценарій
    1. ЦБД отримує 406
    2. ЦБД змінює beneficiaries.status з processing на error
    3. Аналізує помилку
    4. НЕ виконує retry
    5. Відправляє alert в Slack
    6. Переводить інтеграцію в статус invalid_request
    Рішення
    • перевірка контракту API
    • виправлення формату
    Результат
    • інтеграція не виконується для цього запиту
    Acceptance Criteria

    1


    		GivenОтримано 406

    Then

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

    And

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


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

    Acceptance Criteria

    ...

    1

    ...

    When

    ...

    Then

    ...

    2

    ...

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

    ...

    When

    ...

    Then

    ...

    3

    ...

    Then

    ...

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

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

    ...

    Назва

    ...

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

    ...

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

    ...

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

    ...

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

    ...

    1

    ...

    When

    ...

    And

    ...

    Then

    ...

    2

    ...

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

    ...

    When

    ...

    Then

    ...

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

    USE CASE 11 — Обробка 401 Unauthorized при невалідному API Token

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

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

    Назва

    Суб’єкт не знайдений за кодом ЄДРПОУ (порожній результат)

    Назва

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

    Актори
    • ЦБД
    • ЄДР
  4. Slack
    5. Передумови
    • Інтеграція з ЄДР активна
    Передумови
    • Запит до
    ЄДР виконаноОтримано 401 Unauthorized
    • ЄДР виконано
    • ЄДР повертає HTTP 200
    • Список beneficiaries порожній
    Основний сценарій
    1. ЦБД отримує
    401
    1. відповідь 200
    2. Перевіряє тіло відповіді
    3. Визначає, що
    токен невалідний
  5. НЕ виконує retry
  6. Надсилає Slack alert
  7. Статус інтеграції → auth_error
    8. Результат
  8. Інтеграція відновлюється без втручання людини
    1. список результатів порожній
    2. Не виконує заповнення КБВ
    3. ЦБД змінює beneficiaries.status з processing на error
    4. Записує fallback з причиною
    Результат
    • Інтеграція зупинена
    • Нові запити до ЄДР не направляються.
    • Команда отримала повідомлення про необхідність внесення коштів.
    • Дані КБВ для нових awards тимчасово не збагачуються.
    або помилка auth
    Acceptance Criteria

    4

    1

    		GivenОтримано 401ЦБД отримала від ЄДР відповідь 200

    And

    		Список результатів порожній

    When

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

    Then

    		Retry КБВ не виконуєтьсязаповнюються

    2


    		Given

    Отримано 401

    When

    		Система фіксує помилку

    Then

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

    3

    		GivenОтримано 401

    When

    Система фіксує помилку

    Then

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

    Given

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

    When

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

    Then

    Запит до ЄДР не виконується до заміни/актуалізації API Token

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

    Пустий результат

    Then

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


    ...

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

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

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

    Назва

    Обробка відповіді ЄДР після зміни статусу award

    Назва

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

    Актори
    • ЦБД
    • ЄДР
    Slack
    Передумови
    • Запит до ЄДР
    виконаноОтримано 400
    • вже відправлений
    • Award змінив статус (наприклад:
      • дискваліфіковано
      • cancelled
      • unsuccessful)
    Основний сценарій
    1. ЦБД
    отримує 400
  9. Аналізує помилку
  10. Визначає:
    • помилка у формуванні запиту
  11. НЕ виконує retry
  12. Логує помилку
  13. Надсилає повідомлення в Slack
  14. Переводить інтеграцію в статус invalid_request
    15. Рішення

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

    Результат
  15. запит не повторюється
    16. потрібне втручання розробника
    1. відправляє запит
    2. Award змінює статус
    3. ЦБД отримує відповідь від ЄДР
    4. НЕ перевіряє актуальний статус award
    5. Обробляє відповідь за стандартною логікою:
      • або запис КБВ
      • або fallback
    Результат
    • Дані КБВ (або fallback) збережені незалежно від статусу award
    Acceptance Criteria

    1


    		GivenОтримано 400Запит до ЄДР відправлено

    And

    		Award змінив статус

    When

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

    Then

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

    And

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

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

    Отримано відповідь

    Then

    		Відповідь обробляється

    And

    		Дані записуються незалежно від поточного статусу award


    ...

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

    ЯкЦБД Prozorro.Sale
    я хочукоректно обробляти timeout від ЄДР
    щоб

    забезпечити стабільність інтеграції

    USE CASE 17 — Timeout від ЄДР

    Назва

    Обробка перевищення часу очікування відповіді

    Назва

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

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

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

    Acceptance Criteria

    1

    ...

    Then

    ...

    And

    ...

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

    ...

    Назва

    ...

    • ЦБД
    • ЄДР
    • Slack

    ...

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

    ...

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

    ...

    • award без КБВ
    • award містить beneficiaries.fallback.systemReason
    Acceptance Criteria

    1

    ...

    Then

    ...

    And

    ...

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

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

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

    ...

    Назва

    ...

    • ЦБД
    • ЄДР
    • Slack

    ...

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

    ...

    1. ЦБД отримує 406
    2. Аналізує помилку
    3. НЕ виконує retry
    4. Відправляє alert в Slack
    5. Переводить інтеграцію в статус invalid_request

    ...

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

    ...

    • інтеграція не виконується для цього запиту
    Acceptance Criteria

    1

    ...

    Then

    ...

    And

    ...

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

    ...

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

    ...

    Назва

    ...

    Суб’єкт не знайдений за кодом ЄДРПОУ (порожній результат)

    ...

    • ЦБД
    • ЄДР

    ...

    • Інтеграція з ЄДР активна
    • Запит до ЄДР виконано
    • ЄДР повертає HTTP 200
    • Список beneficiaries порожній

    ...

    1. ЦБД отримує відповідь 200
    2. Перевіряє тіло відповіді
    3. Визначає, що список результатів порожній
    4. Не виконує заповнення КБВ
    5. Записує fallback з причиною

    ...

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

    1


    		GivenПеревищено timeout

    When

    		Система обробляє запит

    Then

    		Виконується retry

    2


    		GivenRetry неуспішний

    Then

    		Записується fallback


    ...

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

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

    Уникнути неочікуваного навантаження та складної логіки в межах POC

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

    Назва

    Обробка перевищення часу очікування відповіді

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

    1


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

    And

    		Існують awards без КБВ

    When

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

    Then

    		Обробляються тільки нові awards

    2


    		GivenІснують старі awards

    Then

    		Вони НЕ обробляються автоматично


    ...

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

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

    Контролювати її роботу незалежно від автоматичних сценаріїв

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

    Назва

    Зупинка інтеграції через Адміністративну панель

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

    1



    		GivenІнтеграція активна

    When

    		Адміністратор її зупиняє

    Then

    		Статус = suspended

    And

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


    ...

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

    Назва

    Відновлення інтеграції через Адміністративну панель

    Актори
    • ЦБД
    • Адміністратор
    Передумови

    • Статус:

      • suspended
      • або payment_required
      • або rate_limit_exceeded
    Основний сценарій
    1. Адміністратор натискає “Відновити”
    2. Система змінює статус → active
    3. Запити до ЄДР дозволяються
    Результат
    • Інтеграція відновлена
    Acceptance Criteria

    1



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

    When

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

    Then

    Статус = active


    ...

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

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

    Обробляти пропущені або проблемні записи

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

    Назва

    Зупинка інтеграції через Адміністративну панель

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

    Інтеграція глобально зупинена → ручний запуск дозволений

    Результат

    beneficiaries оновлено

    Acceptance Criteria

    1



    		GivenОбрано award

    When

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

    Then

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

    And

    		beneficiaries перезаписуються


    ...

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

    Назва

    Зупинка інтеграції через Адміністративну панель

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

    перевищено ліміт → операція блокується

    Результат

    всі awards оброблені асинхронно

    Acceptance Criteria

    1



    		GivenОбрано список awards

    When

    		Запускається обробка

    Then

    Кожен award обробляється незалежно

    2


    		GivenМасовий запуск
    ThenОбробка виконується через чергу
    Acceptance Criteria

    ...

    1

    ...

    And

    ...

    When

    ...

    Then

    ...

    2

    ...

    Пустий результат

    ...

    Then

    ...

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

    ...

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

    ...

    Назва

    ...

    Обробка відповіді ЄДР після зміни статусу award

    ...

    • ЦБД
    • ЄДР

    ...

    • Запит до ЄДР вже відправлений
    • Award змінив статус (наприклад:
      • дискваліфіковано
      • cancelled
      • unsuccessful)

    ...

    1. ЦБД відправляє запит
    2. Award змінює статус
    3. ЦБД отримує відповідь від ЄДР
    4. НЕ перевіряє актуальний статус award
    5. Обробляє відповідь за стандартною логікою:
      • або запис КБВ
      • або fallback

    ...

    • Дані КБВ (або fallback) збережені незалежно від статусу award
    Acceptance Criteria

    1

    ...

    And

    ...

    When

    ...

    Then

    ...

    And

    ...

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

    ...

    забезпечити стабільність інтеграції

    USE CASE 18 — Timeout від ЄДР

    ...

    Назва

    ...

    Обробка перевищення часу очікування відповіді

    ...

    • ЦБД
    • ЄДР

    ...

    • Запит відправлено
    • Відповідь не отримано в межах timeout (5–10 сек)

    ...

    1. ЦБД очікує відповідь
    2. Timeout перевищено
    3. ЦБД фіксує помилку
    4. Виконує retry (як для 500/502)
    5. До 3 спроб

    ...

    • retry успішний → UC1
    • retry неуспішний → fallback

    ...

    • або отримані дані
    • або fallback
    Acceptance Criteria

    1

    GivenПеревищено timeout

    When

    Система обробляє запит

    Then

    Виконується retry

    2

    GivenRetry неуспішний

    Then

    Записується fallback


    ...