Інтеграція з API УЗ - перевірка діючого контракту

ТЗ ТУТ

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

Метою розробки є автоматизація перевірки наявності чинного договору між учасником та АТ «Укрзалізниця». Перевірка є обов’язковою умовою для допуску учасників до процедур RCE / RCD. Перевірка повинна виконуватись в момент активації заяви на участь. 

Як працює сервіс УЗ

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

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

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

Метод: POST

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

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

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

curl --location 'https://uz-gate.uz.gov.ua/api/v1/GetToken' \ --header 'Content-Type: application/json' \ --header 'Cookie: cookiesession1=678B288343E2CBCF425AAD86B6CC7980' \ --data '{ "username":"***", "password":"***" }'

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

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

200

{

  "access_token": "<access_token>",

  "refresh_token": "<refresh_token>"

}

Де:

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

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

401

{

"message":"Response status code does not indicate success: 401 (Unauthorized)."

}

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

Оновлення access_token

Метод: POST

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

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

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

curl --location 'https://uz-gate.uz.gov.ua/api/v1/GetToken' \ --header 'Content-Type: application/json' \ --header 'Cookie: cookiesession1=678B288343E2CBCF425AAD86B6CC7980' \ --data '{ "refresh_token": "***" }'

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

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

200

{

  "access_token": "<access_token>",

  "refresh_token": "<refresh_token>"

}

Де:

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

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

400

{

"message": "Response status code does not indicate success: 400 (Bad Request)."

}

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

Метод: POST

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

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

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

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

curl --location 'https://uz-gate.uz.gov.ua/api/v1/GetData/ActiveUzTransportAgreement?edrpou=42398934%0A' \ --header 'Authorization: Bearer ***' \ --header 'Cookie: cookiesession1=678B288343E2CBCF425AAD86B6CC7980' \ --data ''

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

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

200

{

    "edrpou": "42398934",

    "name": "",

    "hasContract": true,

    "contract": {

        "contractCode": "1680",

        "endDate": "31.12.3000"

    }

}

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

400

{

    “edrpou”: “42398834\n”,

    “name”: “”,

    “hasContract”: false,

    “contract”: null

}

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

401

{

    “message”: “Invalid bearer token”

}

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

500

{

    “message”: “Something went wrong. Please try again later.”

}

Також можливий кейс, що АРІ поверне 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. Можливі значення:

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

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

Відповідь від АРІ УЗ Дії ЦБД
Помилка 401 (невірний логін чи пароль)
  1. Додає поле bids.uzAgreementCheck зі значенням not_verified
  2. Змінює статус на active без подальших перевірок
  3. Згенерувати ALERT та надіслати його в канал в слек
Помилка 500, 502, 503 тощо
  1. Повторно пробує отримати токен (автоматично, без необхідності ще раз відправляти запит на активацію (3 рази: через 1 секунду, через 3 секунди та через 5 секунд)
  2. При повторній помилці - додає поле bids.uzAgreementCheck зі значенням not_verified
  3. Змінює статус на active без подальших перевірок

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

Відповідь від АРІ УЗ Дії ЦБД
Помилка 401 або 405 (невалідний токен або сплив термін дії токена) Автоматично виконується спроба логіну через логін та пароль
Помилка 500, 502, 503 тощо Автоматично виконується спроба логіну через логін та пароль

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

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

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

Відповідь від АРІ УЗ Дії ЦБД

400 Bad Request + "hasContract": false

 Блокує зміну статусу на active. Віддає помилку 422 про відсутність договору - "bids.bidders.identifier.id - no active contract found". Заява на участь залишається в статусі draft. 

400 Bad Request (але без поля hasContract)

 Пропускає валідацію. Додає поле bids.uzAgreementCheck зі значенням not_verified. Міняє статус заяви на active.

401 Unauthorized

Запускається цикл переавторизації: 

  1. Спробувати оновити токен через refresh_token
  2. Якщо спроба не вдалась - спробувати отримати новий токен через логін та пароль
  3. Якщо авторизація успішна - повторно виконати перевірку
  4. Якщо авторизація неуспішна - один зі сценаріїв у випадку помилок при авторизації

500 / Timeout

 Пропускає валідацію. Додає поле bids.uzAgreementCheck зі значенням not_verified. Міняє статус заяви на active.

Будь-яка інша відповідь

 Пропускає валідацію. Додає поле bids.uzAgreementCheck зі значенням not_verified. Міняє статус заяви на active.
Edited by Philip