Інтеграція з ЄДР

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

ТВ

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

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

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

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

   	dateTime
   name	multilang
   %	float

Бізнес логіка

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. Якщо сервіс наразі недоступний: 

4. Метод отримання звіту

   1. Метод: POST

   2. Ендпоінт: https://targetServer/2.0/get-documents/ID, де ID - унікальний ідентифікатор

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

      1. Обовʼязковий query-параметр: ID

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

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

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

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

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

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

5. Метод отримання даних для формування звіту
   1. Метод: POST
   2. Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника
   3. Приймає на вхід:
      1. Обовʼязковий query-параметр: code

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Зміни в АРІ ЦБД - Опис буде додано після погодження