Метою розробки є інтеграція з ЄДР для автоматизації та централізації отримання даних про КБВ (кінцевого бенефеціарного власника) для учасників що є юридичними особами. Даний інформація може бути обовʼязковим/не обовʼязковим для певних процедур (наразі розробка інтеграції відбувається тільки для процедур де є документ з типом x_ultimateBeneficiaryInfo).
Для реалізації цієї інтеграції необхідно виконати дії:
| Технічна назва | Бізнес назва (x-legalName) | Тип | Read only | Обовʼязковість (потребує уточнень) | Коментар | |||
|---|---|---|---|---|---|---|---|---|
| uk_UA | en_US | |||||||
| beneficiaries | Інформація про кінцевого бенефеціарного влсника | Information about the ultimate beneficial owner | list of objects | true | false | |||
reason | string (multilang) | true | false | |||||
beneficiariesGeneralInfo | object | true | false | |||||
| beneficialName | ПІБ кінцевого бенефеціарного власника | Full name of the ultimate beneficial owner | string (multilang) | true | true | В запиті Прізвище це відповідь на один запит, Імʼя та По батькові - відповідь на інший запит | ||
| address | Адреса | Address | model | true | true | |||
beneficiariesType | Тип бенефіціарного володіння | Type of beneficiaries | string (multilang) | true | true | |||
| role | Роль КБВ по відношенню до пов’язаного суб’єкта | string | true | true | Відповідь на запит текстове відображення ролі (roleText) | |||
interest | Відсоток частки статутного капіталу або відсоток права голосу | float | true | true | ||||
indirectInterest | Відсоток частки статутного капіталу або відсоток права голосу у разі непрямого впливу | float | true | true | ||||
otherImpact | Інший характер та міру впливу | |||||||
beneficiaryFalse | Ознака можливої недостовірності інформації про КБВ | |||||||
excluded | Ознака виключення відомостей про КБВ за вказівкою Міністерства юстиції України | |||||||
isMissing | Ознака відсутності КБВ юридичної особи | |||||||
reason | Причина відсутності КБВ юридичної особи | |||||||
| informationDate | Дата отримання даних | Date of information | string ($dateTime) | true | true | |||
| Статус | Опис |
|---|---|
active | Запити до ЄДР виконуються |
payment_required | Отримано 402, запити зупинено |
rate_limit_exceeded | Отримано 429, запити зупинено |
suspended | Загальний статус призупинення |
restored | Інтеграцію відновлено |
Сервіс ЄДР реалізований як API для автоматичного отримання даних для внесення інформації про КБВ учасника торгів що кваліфікується. Взаємодія працює по протоколу HTTP з використанням авторизації через JWT. Загальна логіка процесу: спочатку через метод авторизації отримуємо access та refresh токени, а потім використовуємо їх для виклику ендпоінту отримання даних для заповнення інформації про КБВ за кодом ЄДРПОУ юридичною особи. - Детальніше буде додано після отримання тестового ключа
Дія тестового ключа 6 місяців
Приймає на вхід:
Приклад запиту:
Приклади відповіді:
Якщо code знайдено, а також токен авторизації є валідним:
Якщо code не знайдено:
Якщо сплив термін дії токена авторизації:
Якщо сервіс наразі недоступний:
Також можливий кейс, що АРІ поверне 403 помилку, якщо, наприклад, ЄДР змінить права доступу нашого акаунту.
Коди помилок та відповідей:
Код | Текст | Пояснення |
|---|---|---|
200 | OK | Запит успішно оброблено і повернуто результат |
400 | Bad Request | Запит має помилку або не може бути оброблений. Відповідне повідомлення з поясненнями додане до відповіді. |
401 | Unauthorized | Параметри авторизації не правильні, або не вказані взагалі. |
402 | PaymentRequired | Для виконання запиту необхідна оплата. |
403 | Forbidden | Запит вірний але в обробці відмовлено. Відповідне повідомлення з поясненнями додано до відповіді. |
404 | Not Found | Адреса не правильна або ресурс до якого йде запит не існує. |
406 | Not Acceptable | Дані передані в запиті мають не зрозумілий формат. |
429 | Many Requests | API повертає таку відповідь коли вичерпано обмеження запитів до ресурсу. |
500 | Internal Server Error | Щось зламалось. |
502 | Bad Gateway | Сервіс вимкнено або проходить оновлення. |
Повідомлення з інформацією про помилку.
У разі помилки API повертає відповідь з поясненням, формат - JSON, наприклад:
{"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. |
| HTTP code | Retry | Зупинка інтеграції | Slack | Дія |
|---|---|---|---|---|
| 400 | Ні | Ні | Так | баг у запиті |
| 401 | Так (1 раз) | НІ | Ні | refresh token |
| 402 | Ні | Так | Так | чекати оплату |
| 403 | Ні | Можливо | Так | перевірити доступ |
| 404 | Ні | Можливо | Ні | немає суб'єкта |
| 406 | Ні | Можливо | Так | формат |
| 429 | НІ | Так | Так | ліміт |
| 500 | Так (3 рази) | Ні | Ні | тимчасова помилка |
| 502 | Так (3 рази) | Ні | Ні | сервіс недоступний |
| Як | ЦБД Prozorro.Sale |
| я хочу | автоматично отримувати та зберігати інформацію про кінцевих бенефіціарних власників (КБВ) з ЄДР при створенні award |
| щоб | забезпечити актуальність, централізацію та зменшити залежність від ручного введення даних |
Назва | Отримання та запис КБВ з ЄДР в award |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат | award містить список КБВ (може бути декілька) |
1 | Given | Всі умови виконані |
When | Створюється award | |
Then | Відправляється запит до ЄДР | |
2 | Given | ЄДР повернув валідні дані |
When | Дані проходять валідацію | |
Then | Вони записуються в award.beneficiaries | |
3 | Given | Дані записані |
Then | оновлюються всі dateModified:
|
Назва | Відмова у записі КБВ |
| Актори |
|
| Передумови | Отримано HTTP код: |
| Основний сценарій |
|
| Результат | award без змін |
1 | Given | Дані не відповідають моделі |
When | Виконується валідація | |
Then | Дані не записуються |
Назва | Повторна спроба отримання даних |
| Актори |
|
| Передумови | Отримано HTTP код: |
| Основний сценарій |
|
| Альтернативний сценарій | після 3 невдалих спроб → fallback |
| Результат |
|
1 | Given | Отримано 500/502 |
When | Виконується retry | |
Then | Система повторює запит до 3 разів | |
2 | Given | Всі retry невдалі |
Then | Записується повідомлення: |
Назва | Моніторинг інтеграції з ЄДР |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат |
|
1 | Given | Отримано помилку зі списку |
When | Обробляється відповідь | |
Then | Відправляється повідомлення в Slack |
Назва | Неініціювання запиту до ЄДР |
| Актори |
|
| Передумови | Будь-яка з умов НЕ виконується:
|
| Основний сценарій |
|
| Результат | Жодних запитів до ЄДР |
1 | Given | Умови не виконані |
When | Створюється award | |
Then | запит до ЄДР не виконується |
Назва | Запис кількох бенефіціарів |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат | Збережено всі КБВ |
1 | Given | ЄДР повертає кілька КБВ |
When | Відбувається запис | |
Then | Всі КБВ зберігаються в масиві |
| Як | ЦБД Prozorro.Sale |
| я хочу | зупиняти направлення запитів до ЄДР після першого отримання помилки 402 або 429 |
| щоб | не створювати зайве навантаження на сервіс, не витрачати ліміти та уникати повторних неуспішних запитів до моменту відновлення доступу/поповнення коштів. |
| додатково | Після внесення коштів або відновлення ліміту система має відновити направлення запитів до ЄДР. |
Назва | Автоматичне призупинення інтеграції з ЄДР при помилці 402 Payment Required |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат |
|
1 | Given | ЦБД отримала від ЄДР відповідь 402 |
When | Система обробляє відповідь | |
Then | Інтеграція з ЄДР переходить у статус призупинення. | |
2 | Given | Інтеграція має статус призупинення через |
When | Створюється новий award, який відповідає умовам інтеграції | |
Then | ЦБД не направляє запит до ЄДР. | |
3 | Given | Отримано 402 |
| When | Система фіксує помилку | |
Then | Повідомлення надсилається в Slack канал. |
Назва | Автоматичне призупинення інтеграції з ЄДР при помилці 429 Many Requests |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат |
|
1 | Given | ЦБД отримала відповідь 429 |
When | Система обробляє відповідь | |
Then | Направлення нових запитів до ЄДР зупиняється. | |
2 | Given | Інтеграція призупинена через |
When | Створюється новий award | |
Then | ЦБД не направляє запит до ЄДР | |
3 | Given | Отримано 429 |
| When | Система обробляє помилку | |
Then | Повідомлення надсилається в Slack канал. |
Назва | Ручне або автоматичне відновлення інтеграції з ЄДР після внесення коштів |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат |
|
1 | Given | Інтеграція призупинена через 402 |
| And | Кошти внесено | |
When | Адміністратор активує інтеграцію | |
Then | Статус інтеграції змінюється на active. | |
2 | Given | Інтеграція активна після відновлення |
When | Створюється новий award | |
Then | ЦБД направляє запит до ЄДР | |
3 | Given | ЄДР після відновлення повертає 200 |
| When | ЦБД отримує валідні дані | |
Then | Дані записуються в |
Назва | Відновлення інтеграції після помилки 429 |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Результат |
|
1 | Given | Інтеграція призупинена через 429 |
When | Ліміт запитів відновлено | |
And | Адміністратор активує інтеграцію | |
Then | ЦБД знову направляє запити до ЄДР | |
2 | Given | Інтеграція активована після |
When | Створюється award | |
Then | Запит до ЄДР виконується |
| Як | ЦБД Prozorro.Sale |
| я хочу | коректно обробляти всі типи помилок від ЄДР (400, 401, 403, 404, 406, 500, 502) |
| щоб | забезпечити стабільну роботу системи, не втрачати дані та мати можливість відновлення інтеграції |
Назва | Автоматичне оновлення токена при помилці 401 |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Альтернативний сценарій | Refresh token невалідний → перейти до помилки критичного рівня |
| Результат | Інтеграція відновлюється без втручання людини |
1 | Given | Отримано 401 |
When | Токен протермінований | |
Then | Система виконує refresh token | |
2 | Given | Токен оновлено |
Then | Запит повторюється 1 раз | |
3 | Given | повторний запит успішний |
Then | дані записуються в award |
Назва | Обробка некоректного запиту до ЄДР |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Рішення | Виправлення формату запиту (dev fix) |
| Результат |
|
1 | Given | Отримано 400 |
When | Обробляється помилка | |
Then | Retry не виконується | |
And | Slack отримує повідомлення |
Назва | Обробка відсутності прав доступу |
| Актори |
|
| Передумови |
|
| Основний сценарій |
|
| Рішення |
|
| Результат | Інтеграція не працює до виправлення |
1 | Given | Отримано 403 |
Then | Retry не виконується | |
And | Slack отримує повідомлення |
Назва | Обробка відсутності суб’єкта в ЄДР |
| Актори |
|
| Передумови | ЄДРПОУ не знайдено |
| Основний сценарій |
|
| Результат |
|
1 | Given | Отримано 404 |
Then | Retry не виконується | |
And | Записує beneficiaries тільки поле reason:
|
Назва | Обробка помилки формату даних |
| Актори |
|
| Передумови | Некоректний формат request/response |
| Основний сценарій |
|
| Рішення |
|
| Результат |
|
1 | Given | Отримано 406 |
Then | Retry не виконується | |
And | Slack отримує повідомлення |