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

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

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

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

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

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

   Технічна назва		Бізнес назва (x-legalName)		Тип	Read only	Обовʼязковість (потребує уточнень)
   		uk_UA	en_US
   beneficiaryInfo				object	true	false
   	beneficialName	ПІБ кінцевого бенефеціарного власника	Full name of the ultimate beneficial owner	string (multilang)	true	true
   	ownershipType	Тип бенефіціарного володіння	Type of beneficial ownership	string (multilang)	true	true
   	ownershipPercentage	Відсоток частки статутного капіталу або відсоток права голосу	Percentage of share of authorized capital or percentage of voting rights:	float (multilang)	true	true
   	address	Адреса	Address	model	true	true
   	generationDate	Дата генерації	Date of generation	string ($dateTime)	true	true

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

1. Майданчик, залучає користувача до участі в аукціоні де звіт з інформацією про КБВ (x_ultimateBeneficiaryInfo) визначений як тип документу
2. Учасник є юридичною особою
3. Учасник подає заявку на участь
4. Майданчик активує заявку на участь
5. ЦБД направляє запит в ЄДР з авторизаційним ключем і даними для пошуку де виконуються умови:
   1. Для процедур де 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 - Спеціальні дозволи на користування надрами
   2. Для award в статусах: pending_waiting, pending_admission, pending 
   3. Для award.bidders.identifier.UA-EDR
   4. Під час створення award (асинхронний запит)
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 для автоматичного отримання даних для формування звіту/документу звіту про КБВ учасника торгів. Взаємодія працює по протоколу 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}]}

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

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