Документація

Загальний опис

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

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

  1. Додати до базової моделі award необовʼязкову до заповнення поле beneficiaries моделю даних beneficiariesGeneralInfo (модель даних наведено нижче)
  2. Налаштувати інтеграцію з ЄДР де після відправки запиту заповнюється модель beneficiariesGeneralInfo
  3. При внесенні інформації змінюємо award.dateModified, dateModified (procedure) та systemDateModified
  4. Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)

Business flow

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

  1. Учасник є юридичною особою
  2. Учасник подає заявку на участь
  3. Майданчик активує заявку на участь
  4. Заявка на участь перейшла в кваліфікацію
  5. Під час створення 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. Процедури, яких немає в переліку не використовують даний функціонал - РО попереджено що додавання нових напрямків йде через розробку
  6. ЦБД отримує дані з ЄДР
    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 місяців

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

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

  2. Передача API Token у заголовку Authorization

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

    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 ]

Правила

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

fallback

  objecttruefalseМоже бути тільки один в разі відсутності даних про КБВ
 

systemReason

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

excluded

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

isMissing

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

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 = "Не вдалось отримати інформацію з сервісу"
  6. API_TOKEN зберігається:
    - у захищеному конфігураційному середовищі
    - не логуються
    - не передається у відкритому вигляді

Обмеження

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

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

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

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

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

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

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

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 = "Суб'єкт не знайдено в ЄДР"

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

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

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

Тригер

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

Поведінка

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

  1. Після 402

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

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

    3. статус → active

  2. Після 429

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

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

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

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

Логування

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

Timeout

  1. timeout = 5-10 секунд
  2. 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

  1. Учасник подає заявку
  2. Майданчик активує заявку
  3. Заявка переходить у кваліфікацію
  4. ЦБД створює award
  5. ЦБД перевіряє умови запуску інтеграції
  6. ЦБД формує запит до ЄДР із заголовками:
    1. Authorization: Token {API_TOKEN}
    2. Accept: application/json
  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)
Передумови

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

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

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 разів
  5. Якщо успіх → UC1
Альтернативний сценарій

Всі retry невдалі → UC4

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

1

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

When

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

Then

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

2

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

Then

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


USE CASE 4 — Fallback

Назва

Внесення системної помилки
Актори

ЦБД (primary)

Передумови

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

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

award містить fallback

Acceptance Criteria

1

GivenДані не отримані після retry

Then

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

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 6 — Обробка множинних КБВ

Назва

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

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

Acceptance Criteria

1

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

When

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

Then

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

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

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

USE CASE 7 — Зупинка запитів після отримання 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 8 — Зупинка запитів після отримання 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 9 — Відновлення запитів після внесення коштів

Назва

Ручне або автоматичне відновлення інтеграції з ЄДР після внесення коштів
Актори
  • Адміністратор/відповідальна команда
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція з ЄДР була призупинена через 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 10 — Відновлення після вичерпання ліміту запитів

Назва

Відновлення інтеграції після помилки 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
я хочукоректно обробляти всі типи помилок від ЄДР (400, 401, 403, 404, 406, 500, 502)
щобзабезпечити стабільну роботу системи, не втрачати дані та мати можливість відновлення інтеграції

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

Назва

Автоматичне оновлення токена при помилці 401
Актори
  • ЦБД
  • ЄДР
  • Slack
Передумови
  • Запит до ЄДР виконано
  • Отримано 401 Unauthorized
Основний сценарій
  1. ЦБД отримує 401
  2. Визначає, що токен невалідний
  3. НЕ виконує retry
  4. Надсилає Slack alert
  5. Статус інтеграції → 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 12 — Помилка 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 13 — Помилка 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 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


GivenОтримано 404

Then

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

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


GivenОтримано 406

Then

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

And

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


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

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

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

Назва

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

Актори
  • ЦБД
  • ЄДР
Передумови
  • Інтеграція з ЄДР активна
  • Запит до ЄДР виконано
  • ЄДР повертає HTTP 200
  • Список beneficiaries порожній
Основний сценарій
  1. ЦБД отримує відповідь 200
  2. Перевіряє тіло відповіді
  3. Визначає, що список результатів порожній
  4. Не виконує заповнення КБВ
  5. Записує fallback з причиною
Результат
  • Інтеграція зупинена
  • Нові запити до ЄДР не направляються.
  • Команда отримала повідомлення про необхідність внесення коштів.
  • Дані КБВ для нових awards тимчасово не збагачуються.
Acceptance Criteria

1

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

And

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

When

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

Then

КБВ не заповнюються

2


Given

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

Then

записується systemReason = "Суб’єкт не знайдений за кодом ЄДРПОУ"


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

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

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

Назва

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

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

1

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

And

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

When

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

Then

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

2


Given

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

Then

записується systemReason = "Суб’єкт не знайдений за кодом ЄДРПОУ"