Versions Compared

Old Version 32

changes.mady.by.user valeriia denysenko

Saved on

compared with

New Version 33

changes.mady.by.user valeriia denysenko

Saved on

Key

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

...

Код

Текст

Пояснення

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Дія системи
400Slack alert, дані не записуються
401Slack alert, спроба оновити token
402Slack alert, дані не записуються
403Slack alert, дані не записуються
404Slack alert, дані не записуються
406Slack alert, дані не записуються
429Slack alert, дані не записуються
500Retry до 3 разів
502Retry до 3 разів

User Story 1

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

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

Назва

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

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

Acceptance Criteria

1

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

When

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

Then

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

2


Given

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

When

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

Then

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

3

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

Then

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

  • award.dateModified
  • dateModified (procedure)
  • systemDateModified


...

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

Назва

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

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

Основний сценарій
  1. ЦБД отримує відповідь від ЄДР
  2. Перевіряє структуру
  3. Дані:
    • неповні / некоректні / не мапляться
  4. ЦБД НЕ записує дані
Результат

award без змін


Acceptance Criteria

1

GivenДані не відповідають моделі

When

Виконується валідація

Then

Дані не записуються


...

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

Назва

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

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

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

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

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


Acceptance Criteria

1

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

When

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

Then

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

2

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

Then

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


...

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

Назва

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


Acceptance Criteria

1

GivenОтримано помилку зі списку

When

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

Then

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


...

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

Назва

Неініціювання запиту до ЄДР
Актори
  • ЦБД (primary)
  • ЄДР API (external)
Передумови

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

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

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


Acceptance Criteria

1

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

When

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

Then

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


...

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

Назва

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

Збережено всі КБВ


Acceptance Criteria

Acceptance Criteria

1

GivenЄДР повертає кілька КБВ

When

Відбувається запис

Then

Всі КБВ зберігаються в масиві


User Story 2

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

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

Назва

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

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

Acceptance Criteria

1

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

When

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

Then

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

2


Given

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

When

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

Then

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

3

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

Then

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

  • award.dateModified
  • dateModified (procedure)
  • systemDateModified


Use Case 1 — 

Назва

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

Актори

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

Передумови

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

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

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

Результат

  • Нові запити до ЄДР не направляються.
  • Команда отримала повідомлення про необхідність внесення коштів.
  • Дані КБВ для нових 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 означає, що вичерпано обмеження запитів до ресурсу.

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

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

Результат

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

Acceptance Criteria

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

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

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

...

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

Назва

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

Актори

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

Передумови

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

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

  1. Відповідальна команда вносить кошти.
  2. Адміністратор ініціює відновлення інтеграції.
  3. ЦБД змінює статус інтеграції з:
    • payment_required / suspended
    • на active.
  4. ЦБД відновлює направлення запитів до ЄДР.
  5. При створенні наступного award ЦБД знову виконує стандартну логіку запиту до ЄДР.
  6. Якщо ЄДР повертає 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
  • Ліміт запитів поновлено або відповідальна команда підтвердила можливість повторного використання сервісу

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

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

Результат

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

Acceptance Criteria

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

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

...

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


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

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

...

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

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