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

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

ТВ

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

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

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

1. Додати до базової моделі award необовʼязкову до заповнення модель даних beneficiaryInfo (модель даних наведено нижче)
2. Налаштувати інтеграцію з ЄДР де:
   1. В момент створення award в процедурі для статусів: pending_waiting, pending_admission pending та тим моделі award.bidders.identifier.UA-EDR
   2. Направляється асинхронний запит на сервіс ЄДР
   3. Отримується відповідь на запит
      1. Відповідь містить дані → Отримані дані вносяться в створену модель даних
      2. Відповідь не містить даних → Поля залишаються пустими
   4. При внесенні інформації змінюємо award.dateModified
   5. Майданчики відображають дану інформацію організатору в його кабінеті. Відображення в інших місцях не є обовʼязковою (портал, кабінети учасників)
3. Відповідь може містити 1 і більше відповідей 
4. Модель даних beneficiaryInfo
   

   	dateTime
   name	multilang
   %	float

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

1. Майданчик, залучає користувача до участі в аукціоні де звіт з інформацією про КБВ (x_ultimateBeneficiaryInfo) визначений як тип документу
2. Учасник є юридичною особою
3. Учасник подає заявку на участь
4. Майданчик активує заявку на участь
5. Учасник кваліфікується в аукціоні
6. Варіант 1.
   1. ЦБД направляє запит в ЄДР з авторизаційним ключем і даними для пошуку
   2. ЦБД отримує дані з ЄДР
   3. ЦБД вносить дані в award учасника
      1. Якщо в отриманій відповіді містяться дані, які можна внести в award → ЦБД додає їх
      2. Якщо в отриманій відповіді містяться дані, які можна внести в award → ЦБД додає їх
7. Варіант 2.
   1. Організатор активує елемент "Отримати КБВ з ЄДР"
   2. Майданчик надсилає запит на ЦБД
   3. ЦБД надсилає запит в ЄДР з авторизаційним ключем і даними для пошуку
   4. ЦБД отримує відповідь 
   5. ЦБД пересилає відповідь майданчику
   6. Майданчик заповнює поля і передає їх в ЦБД
   7. Майданчик обовʼязково відображає поля організатору в його кабінеті
   8. Майданчик може відображати дані на порталі та в кабінетах учасників 
8. ЦБД перевіряє чи є документ з типом в заявці якщо витяг ЄДР - x_tenderersRegisterExtract, якщо заява в довільній формі - x_ultimateBeneficiaryInfo - наразі цих типів документів немає в SUE/SUD
   1. Якщо в bid немає документа з визначеним типом:
      1. ЦБД надсилає івент до системи з технічним id користувача та кодом ЄДРПОУ користувача та owner
      2. Система фіксує івент і фіксує отримані дані
      3. Перевіряє чи документ з типом в 
      4. Система надсилає запит до ЄДР з авторизаційним ключем і даними для пошуку
      5. ЄДР повертає відповідь на запит:
         1. в форматі переліку полів для формування звіту
            1. Система  опрацьовую отриману інформацію
            2. Система формує звіт
         2. в форматі звіту 
         3. помилка (перелік можливих зазначено нижче)
      6. Система додає сформований звіт до документ сервісу з привʼязкою до технічного id учасника 
      7. Варіанти наступних дій:
         1. 1.Варіант  
            1. Система додає інформацію в transfer блок bid
            2. Майданчик отримує токен до документа і надає користувачу відповідно до технічного id bid виконувати дії над документом
            3. Учасник бачить звіт в своєму кабінеті
         2. 2.Варіант Система підвантажує дані в bid самостійно - не виглядає як релевантний кейс
            1. Майданчик забирає в разі потреби викачує документ
   2. Якщо в bid наявний документ з визначеним типом:
      1. ЦБД не надсилає івент до системи

Проблемні питання:

1. Використання існуючого документ сервісу. Відповідно до загальної логіки роботи з документ сервісом і документів які завантажені в procedure/bid/award/contract зі сторони Адміністратора ми не зможемо завантажувати документи від учасника тощо, відповідно вони не зможуть з ним працювати якщо не скачають і заново не завантажать в біда а тоді буде дублювання інформації. 
2. Для процедур де цей документ є обовʼязковим, учасники не зможуть активувати біда без наявності цих документів, відповідно логіка повинна відпрацювати на етапі створення bid учасника в статусі draft.
3. Питання юридичної можливості вносити зміни в bid якщо ми будемо вносити зміни в учасника а не через схему майданчик надсилає нам запит і у відповідь отримує звіт ?
4. Питання відповідно до того що нам треба закрити можливість створювати декілька запитів від одного учасника 
   1. Технічне рішення яке може закрити дану можливість
      1. Фіксація технічного id учасника та owner, яке використовувалось для надсилання запиту
      2. Аналіз кількості запитів та/або блокування наступних запитів на формування звітів (order = 1 )
5. Питання який саме звіт/документ хочемо отримувати ? (Наразі є варіанти:
   1. Відомості (витяг) з Єдиного державного реєстру юридичних осіб, фізичних осіб-підприємців та громадських формувань з підписом технічного адміністратора - Підходить для ЮО та ФОП (але для ФОП немає сенсу якщо потрібна інформація про КБВ) 
   2. Відомості (витяг) з Єдиного державного реєстру юридичних осіб, фізичних осіб-підприємців та громадських формувань без підписа технічного адміністратора- Підходить для ЮО та ФОП (але для ФОП немає сенсу якщо потрібна інформація про КБВ) 
   3. Інформація про кінцевого бенефіціарного власника юридичної особи - документ сформований учасником на імʼя директора ЕТМ
   4. Структура власності майданчика  - документ сформований учасником 

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

Сервіс ЄДР реалізований як 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}]}

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

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

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