Page History

...

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

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

1. Додати до базової моделі award необовʼязкову до заповнення поле beneficiaries моделю даних beneficiariesGeneralInfo (модель даних наведено нижче)
2. Налаштувати інтеграцію з ЄДР де після відпраки відправки запиту заповнюється модель beneficiariesGeneralInfo
3. При внесенні інформації змінюємо award.dateModified, dateModified (procedure) та systemDateModifiedsystemDateModified
4. Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)Модель даних beneficiariesGeneralInfo
   Технічна назваБізнес назва (x-legalName)ТипRead onlyОбовʼязковість (потребує уточнень)Коментарuk_UAen_USbeneficiaries
   Інформація про кінцевого бенефеціарного влсникаInformation about the ultimate beneficial owner
   list of objectstruefalse 

   reason

     string (multilang)truefalse 

   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 даними КБВ з ЄДР

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

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

...

• 500
• 502

...

• 4xx + 429

...

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

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

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

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

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

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

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

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

Поле в award

beneficiaries: [beneficiariesGeneralInfo ]

Правила

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

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

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 спроб → beneficiaries.status = error
6. API_TOKEN зберігається:
   - у захищеному конфігураційному середовищі
   - не логуються
   - не передається у відкритому вигляді
7. Порожній результат (200 без даних) НЕ є помилкою API, але вимагає fallback
8. Асинхронність має пріоритет над статусом award — відповідь завжди обробляється
9. Timeout прирівнюється до технічної помилки (500/502)

Обмеження

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

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

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

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

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

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

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

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

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

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

1. Обробка 401

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

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

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

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

2. Обробка 404

   1. Отримано 404
   2. зміна  beneficiaries.status з processing на error

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

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

• 400
• 402
• 403
• 406
• 429
• auth_error

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

Тригер

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

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

Поведінка

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

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

1. Після 402

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

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

   3. статус → active

2. Після 429

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

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

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

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

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

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

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

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

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

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

Логування

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

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

Timeout

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

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

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

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

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

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

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

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

Acceptance Criteria

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

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

...

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

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

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

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

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

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

2. Оновлення access_token

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

   1. Метод: POST

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

   3. Приймає на вхід:

      • Обовʼязковий query-параметр: code

   4. Приклад запиту:

   5. Приклади відповіді:

      1. Якщо code знайдено, а також токен авторизації є валідним:

      2. Якщо code не знайдено:

      3. Якщо сплив термін дії токена авторизації:

      4. Якщо сервіс наразі недоступний:

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

Помилки

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

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

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

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

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

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

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

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

...

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

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}

...

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

...

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

...

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

...

award без змін

Acceptance Criteria

...

1

...

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

...

When

...

Then

...

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

...

2

...

Then

...

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

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

...

Назва

...

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

...

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

...

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

...

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

Acceptance Criteria

...

1

...

When

...

Then

...

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

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

...

Назва

...

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

...

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

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

...

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

...

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

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}

...

1. ЄДР повертає список КБВ
2. ЦБД мапить кожен запис
3. Формує list of objects
4. Записує в award.beneficiaries[]

...

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

Acceptance Criteria

...

1

...

When

...

Then

...

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

...

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

...

Назва

...

• ЦБД
• ЄДР
• Адміністратор/відповідальна команда
• 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

...

1

...

When

...

Then

...

2

...

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

...

When

...

Then

...

3

...

Then

...

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

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

Acceptance Criteria

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

...

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

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

Acceptance Criteria

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

...

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

USE CASE 17 — Timeout від ЄДР

Acceptance Criteria

...

...

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

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

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

Acceptance Criteria

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

...

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

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

Acceptance Criteria

1

...

When

...

Then

...

And

...

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

...

Назва

...

• ЦБД
• ЄДР
• Slack

...

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

...

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

...

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

...

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

Acceptance Criteria

1

...

Then

...

And

...

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

...

Назва

...

• ЦБД
• ЄДР
• Slack

...

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

...

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

...

• award без КБВ

Acceptance Criteria

...

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

Acceptance Criteria

...

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

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

Acceptance Criteria

...

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

Acceptance Criteria

Acceptance Criteria

1

...

Then

...

And

...

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

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

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

...

Назва

...

• ЦБД
• ЄДР
• Slack

...

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

...

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

...

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

...

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

Acceptance Criteria

...