Page History

Table of Contents

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

• ТВ
• Специфікація ЄДР

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

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

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

1. Додати до базової моделі award необовʼязкову до заповнення модель поле beneficiaries моделю даних beneficiaryInfo beneficiariesGeneralInfo (модель даних наведено нижче)
2. Налаштувати інтеграцію з ЄДР де після відпраки відправки запиту заповнюється модель beneficiaryInfo beneficiariesGeneralInfo
3. При внесенні інформації змінюємо award.dateModified, dateModified (procedure) та systemDateModifiedsystemDateModified
4. Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)Модель даних beneficiaryInfo
   Технічна назваБізнес назва (x-legalName)ТипRead onlyОбовʼязковість (потребує уточнень)uk_UAen_USbeneficiaryInfo  objecttruefalsebeneficialNameПІБ кінцевого бенефеціарного власникаFull name of the ultimate beneficial ownerstring (multilang)truetrueownershipTypeТип бенефіціарного володінняType of beneficial ownershipstring (multilang)truetrueownershipPercentageВідсоток частки статутного капіталу або відсоток права голосуPercentage of share of authorized capital or percentage of voting rights:float (multilang)truetrueaddressАдресаAddressmodeltruetruegenerationDateДата генераціїDate of generationstring ($dateTime)truetrue

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

Business flow

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

...

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

Особливості:

1. Тип поля beneficiaryInfo в award - list of objects
2. Запит на ЄДР може віддати дані про декількох КБВ
3. Потрібно передбачити що повторний запит відправляється в разі отримання відповіді 500 або 502 
4. Чи потрібно виводити якийсь текст якщо нам не вдалось отримати відповідь ? - запитання до Ксенії
5. Нам потрібно фіксувати повідомленням в Slack канал якщо отримуємо відповіді:
   1. 400
   2. 401
   3. 402
   4. 403
   5. 404
   6. 406
   7. 429

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

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

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

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

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

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

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

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

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

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

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

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

   1. Метод: POST

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

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

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

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

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

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

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

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

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

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

...

Помилки

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

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

...

{"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. може містити: кілька КБВ або визначення причини відсутності даних (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, але без даних)

Acceptance Criteria

...

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

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

Acceptance Criteria

...

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

USE CASE 17 — Timeout від ЄДР

Acceptance Criteria

...

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

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

Acceptance Criteria

...

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

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

Acceptance Criteria

...

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

Acceptance Criteria

...

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

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

Acceptance Criteria

...

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

Acceptance Criteria

...