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

ТВ

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

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

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

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

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

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

2. Оновлення access_token

3. Метод отримання унікального ідентифікатора

   1. Метод: POST

   2. Ендпоінт: https://targetServer/1.0/subjects?code=ХХХХХХХХ, де code - код ЄДРПОУ учасника

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

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

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

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

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

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

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

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

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

   1. Метод: POST

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

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

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

      2. Заголовок: Authorization: Bearer <access_token>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Необхідно додати валідацію на активацію заяви на участь виключно для процедур 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 та дозволяє активацію заяви, щоб не блокувати процес подання.

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

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

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

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

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