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

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

ТВ

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

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

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

Сервіс ЄДР реалізований як API для автоматичної перевірки наявності чинних договорів з учасниками. Взаємодія працює по протоколу HTTP з використанням авторизації через JWT. Загальна логіка процесу: спочатку через метод авторизації отримуємо access та refresh токени, а потім використовуємо їх для виклику ендпоінту перевірки договору за кодом ЄДРПОУ.

Доступні ендпоінти

Авторизація (отримання токенів)

Метод: POST

Ендпоінт: https://uz-gate.uz.gov.ua/api/v1/GetToken

Приймає на вхід: username та password

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

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

Якщо введено правильно логін і пароль, отримуємо відповідь 200:

Де:

• <access_token> - авторізаційний JWT токен. Діє 300 секунд.
• <refresh_token> - JWT токен оновлення. Діє 1800 секунд.

Якщо логін та / або пароль невірні, отримуємо відповідь 401:

Доступ (логін та пароль) можна отримати у Andrii Salii або Mykyta Sukharevskyi 

Оновлення access_token

Метод: POST

Ендпоінт: https://uz-gate.uz.gov.ua/api/v1/GetToken

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

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

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

Якщо якщо токен валідний та дійсний, отримуємо відповідь 200:

Де:

• <access_token> - новий авторізаційний JWT токен. Діє 300 секунд.
• <refresh_token> - новий JWT токен оновлення. Діє 1800 секунд.

Якщо введено невалідний JWT токен, або токен, термін дії якого сплив, отримуємо відповідь 405: 

Метод перевірки договору

Метод: POST

Ендпоінт: https://uz-gate.uz.gov.ua/api/v1/GetData/ActiveUzTransportAgreement

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

• Обовʼязковий query-параметр: edrpou
• Заголовок: Authorization: Bearer <access_token>

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

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

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

Якщо договір не знайдено:

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

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

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

Зміни в АРІ ЦБД

Необхідно додати валідацію на активацію заяви на участь виключно для процедур RCE, RCD. 

Дану валідацію необхідно додати в ендпоінт:

PATCH​/api​/procedures​/{procedure_id}​/bids​/{bid_id}​/status

Валідація має спрацьовувати при спробі активувати заяву на участь (draft → active). Валідація перевіряє наявність діючого контракту у учасника через сервіс УЗ. Валідація відбувається після перевірки за допомогою ЄДРПОУ учасника (в ЦБД цим значенням є bids.bidders.identifier.id) наявності активного контракту з УЗ. 

• Для перевірки діючого контракту нас цікавить виключно поле "hasContract". Значення інших полів ігноруємо. 
• Валідацію може бути не пройдено виключно якщо чітко зазначено значення поля hasContract як false. 

Додаткове поле в моделі bids

Необхідно розширити модельку bids для процедур УЗ. 

Нове поле - bids.uzAgreementCheck. Тип поля - string.

x-legalNameUa: Результат перевірки договору з УЗ
x-legalNameEn: UZ contract verification result

Можливі значення:

• verified - означає, що заяву на участь було активовано після успішної перевірки через сервіс УЗ.
• not_verified - означає, що заяву на участь було активовано, проте перевірку не було виконано. 

Також необхідно додати словник, в якому будуть міститись значення, що пояснюють кожен статус:

• verified
  • Заяву активовано. Перевірку виконано.
  • Bid activated. Verification completed.
• not_verified
  • Заяву активовано без перевірки.
  • Bid activated without verification.

Особливості поля:

• Поле є автогенерованим
• Поле з'являється в заяві на участь лише після активації заяви на участь
• Міграції відсутні (в старих процедурах не додаємо дане поле)

Успішний сценарій активації заяви на участь:

1. Учасник створює заяву на участь через майданчик, і вона отримує початковий статус draft.

2. Майданчик ініціює зміну статусу заяви з draft на active через метод patch.

3. ЦБД перевіряє тип процедури, і якщо це не RCE або RCD, активація завершується за стандартною логікою без перевірки контракту через сервіс УЗ.

4. Для процедур RCE/RCD система перевіряє наявність діючого токену або виконує POST-запит на авторизацію в сервісі УЗ для отримання access_token.

5. ЦБД виконує GET-запит до ендпоінту ActiveUzTransportAgreement, передаючи код ЄДРПОУ учасника (в модельці учасника це bids.bidders.identifier.id) в параметрах та токен у заголовку

6. При отриманні від сервісу УЗ відповіді 200 OK з параметром "hasContract": true, ЦБД підтверджує наявність договору.

   1. Не перевіряємо дату завершення контракту та не робимо жодної логіки на поле endDate

7. Система додає поле bids.uzAgreementCheck зі значенням verified, та успішно змінює статус заяви на active та повертає майданчику відповідь 200 OK. 

8. Якщо сервіс УЗ повертає статус 400 та "hasContract": false, ЦБД блокує активацію та видає 422 помилку про відсутність договору: "bids.bidders.identifier.id - no active contract found".

9. У разі технічної недоступності сервісу УЗ (статус 500 або таймаут), ЦБД ігнорує валідацію, додає поле bids.uzAgreementCheck зі значенням not_verified та дозволяє активацію заяви, щоб не блокувати процес подання.

Сценарії у випадку помилок при авторизації

Сценарції у випадку помилок при оновленні токена авторизації 

Якщо ЦБД отримує помилки при спробі працювати з рефрешем, в такому випадку ЦБД автоматично має спробувати отримати токени за базовим флоу. І тільки якщо не спрацює базовий флоу - надати майданчику помилку, зазначену в таблиці помилок для авторизації. 

Повторні спроби авторизації мають відбуватися непомітно для користувача. Користувач має лише отримати кінцеву відповідь 

Сценарії у випадку помилок при перевірці контракта