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 

   excluded

   Ознака виключення відомостей про КБВ за вказівкою Міністерства юстиції України   

   isMissing

   Ознака відсутності КБВ юридичної особи  

   reason

    Причина відсутності КБВ юридичної особи string (multilang)truefalse 

   systemReason

   Системна причина відсутності данихSystemic reason for missing data  

   informationDate

   Дата отримання данихDate of informationstring ($dateTime)truetrue 

   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

   Ознака можливої недостовірності інформації про КБВ 

Технічні вимоги до автоматичного збагачення 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

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

Business flow

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

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

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

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

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

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

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

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

• Інтеграція тригериться тільки при створенні award в модель даних beneficiariesGeneralInfo
• Запит асинхронний
• Дані записуються тільки якщо валідні
• Запис — атомарний (все або нічого)
• Можливі декілька КБВ
• Retry (3 рази) тільки для:
  • 500
  • 502
• Slack alert тільки для:
  • 400, 402, 403, 409, 429
• Fallback текст при недоступності ЄДР
• Інтеграція тригериться тільки при створенні award
• Запит асинхронний
• Дані записуються тільки якщо валідні
• Запис — атомарний (все або нічого)
• Можливі декілька КБВ
• Retry (3 рази) тільки для:
  • 500
  • 502
• Slack alert тільки для:
  • 4xx + 429
• Fallback текст при недоступності ЄДР
• У разі отримання першої відповіді від ЄДР з HTTP статусом 402 або 429 ЦБД має призупинити направлення всіх наступних запитів до сервісу ЄДР до моменту ручного або автоматичного відновлення інтеграції після внесення коштів / відновлення ліміту.
• Система повинна диференційовано обробляти помилки ЄДР:
  • технічні помилки (500, 502) → retry (Якщо не вдається отримати відповідь виводимо в поле reason systemReason текст "Не вдалось отримати інформацію з сервісу")
  • авторизаційні (401) → refresh token
  • бізнес/доступ (402, 403, 406, 429) → зупинка або alert
  • помилки даних (400) → без retry, з логуванням
  • помилки даних (404) → без retry (Якщо не вдається отримати відповідь виводимо в поле reason systemReason текст "Суб'єкт не знайдено в ЄДР")
    Система не повинна виконувати безкінечні повторні запити.

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

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

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

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

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

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

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

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

Інтеграція

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

Тригер

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

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

Поведінка

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

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

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

...