Застарілий спосіб авторизації: Користувач мав змогу авторизуватись в аукціоні по прямому URL-посиланню з можливістю ввести його в адресний рядок браузеру, де вказані його персональні авторизаційні дані. Наприклад:
https://auction.prozorro.sale/ХХХХХ-UA-ХХХХХХХХХХХ?bidder_id=ХХХХХХХХХХ&acc_token=ХХХХХХХХХХ
Де:
- ХХХХХ-UA-ХХХХХХХХХХХ - auction_id - людиночитаємий ідентифікатор аукціону, в якому бере участь користувач;
- bidder_id - унікальний Ідентифікатор учасника, який він отримує в API після того як його закрита цінова пропозиція активована;
- acc_token - авторизаційний токен, який надає йому змогу користувачу авторизуватись в аукціону як Учасник та робити ставки.
Єдиний інтерфейс - це інструмент, за допомогою якого майданчики мали змогу створювати власний інтерфейс аукціону з відображенням інформації по ньому та робити ставки, не використовуючи внутрішній модуль аукціонів. Його відмінністю було те, що Єдиний Інтерфейс надавав змогу відображати інформацію одразу по декільком аукціонам, в яких на протязі 24 годин брав участь конкретний користувач, за допомогою створення спеціальних рум (room), де він міг робити ставки одночасно в декільках аукціонах. Руми використовувались для відображення приватної інформації з правами бідера. Сервер майданчика формує рум та дозволяє робити ставки, а браузер клієнта в свою чергу звертається до фіда (далі - feed).
Цільовим призначенням даного інтерфейсу було його використання в процедурах деревини (TIE), де він слугував обов’язковою вимогою для майданчиків по даному напрямку (на разі, дану вимогу скасовано).
Додатково даний функціонал міг надавати майданчикам (за їх власним бажанням) функціональну перевагу в проходженні торгів учасників - за допомогою створення ботів, що мали змогу самостійно робити ставки замість учасників. Та інші додаткові сервіси для клієнтів.
Візуальний приклад реалізації Єдиного Інтерфейсу майданчиком:
https://drive.google.com/file/d/16Muips6syexWIJdZx2qDkPsvLg2-_MgA/view?usp=sharing
Відео з демо роботи єдиного інтерфейсу на одному з майданчиків:
https://drive.google.com/file/d/1-KGSI5yyioW121GWyj9ExMdfwy34kedr/view?usp=sharing
Ендпойти Єдиного інтерфейсу, які вилучені з системи:
1. [POST] /api/auctions/room - Створення руму:
- Дозволяє створити “кімнату” для учасника, який одночасно бере участь в декількох аукціонах.
- В тілі запиту даного ендпойнту вказується перелік аукціонів, в яких бере участь користувач, з їх параметрами: auction_id, bidder_id та acc_token.
- Кожен з аукціонів вказується у вигляді окремого об’єкту, кількість яких необмежена.
- Після створення руму йому присвоюється окремий ідентифікатор - “room_id” зі значенням, до прикладу “cb8d206af0f9467ebd59993fe4c752af”, що отримується в респонсі даного ендпойтну. Зі статусом 201 Room created.
- Рум створюється в день аукціонів на один день (24 години).
- Реалізація була такою, що додавати аукціони вже в створений рум не було можливості, так як в анлійських аукціонах день в день подавати заявки на участь учасники не можуть, та всі аукціони стартують одночасно.
Приклад запиту даного ендпойнту:
{
"TE001-UA-20191104-54321": {
"bidder_id": "a1f44e85-96ec-4898-9c42-86cb42f5beb1",
"acc_token": "51c13c45-fb24-46c2-a3ac-adf64c05d791",
"tz": "UTC"
},
"TE001-UA-20191104-12345": {
"bidder_id": "a1f44e85-96ec-4898-9c42-86cb42f5beb1",
"acc_token": "51c55c45-fb24-46c2-a3ac-adf64c05d792"
}
}
- [GET] /api/auctions/rooms/{room_id}/feed - Підключення до руму (кімнати):
- Надає можливість підключення до вебсокету, який для створеної кімнати віддає поточний стан для множини аукціонів у випадку їх зміни.
- Стани аукціону, зміни по яким надає можливість отримувати даний ендпойнт: власні ставки,ставки інших учасників, зміна раунду, час початку/завершення ходу учасника, та інше. А після завершення аукціону - також деанонімізація учасників аукціону з їх ставками.
- Частота оновлень інформації в вебсокеті: сокет при підключенні до нього віддає актуальний стан всіх аукціонів. Після чого він надає автоматично оновлення лише в момент фактичного оновлення інформації по будь якому з об’єктів в базі даних.
- До прикладу, якщо в румі з трьох аукціонів оновилась інформація по будь якому 1-му з них, то оновлюється інформація одразу по 3-х аукціонах.
- Даний ендпойнт дає змогу лише читати (readonly) інформацію по аукціонах, та не вносити зміни по ним.
- Фактично ендпойнт повторює інформацію, що можна отримати з JSON по кожному аукціону.
Приклад: wss://auction-staging.prozorro.sale/api/auctions/rooms/0057e70c7d8347debf1cb06c45cb15bd/feed
Інструмент для перегляду: https://websocketking.com/
- [GET] /api/{auction_id}/feed - Підключення до одного об’єкту аукціону:
- Даний ендпойт повторює логіку попереднього /api/auctions/rooms/{room_id}/feed з відмінністю, що надає інформацію лише по одному об’єкту аукціону, а не їх масиву
- Може використовуватись для створення майданчиком інтерфейсу аукціону, по аналогії модулю аукціону.
- Не дає можливості змінювати стани аукціону
- Також відмінністю від румів є те, що частота оновлень в ньому відбувалась раз в одну секунду, та не залежала від фактичних змін об’єкту аукціону.
- [POST] /api/auctions/{auction_id}/bid - Подача ставки:
- За допомогою даного ендпойнту Учасник міг змінювати власну ставку в аукціоні, як в рамках румів, так і одинарного об’єкту аукціону.
- Можливість змінювати ставку обмежена виключно під час власної черги Учасника.
- У випадку спроби подачі ставки в інший проміжок часу - відображалась помилка 400 - Bad request, cannot post bid in current state
- Якщо вказані не вірні авторизаційні дані учасника - 403 Permission error
- Якщо не вірно auction_id - 404 Auction not found
- Приклад тіла запиту ендпойту:
{
"bid": 3000.01
}
- POST] /api/auctions/{auction_id}/bid/cancel - Відміна ставки:
- Аналогічно попередньому ендпойнту - Учасник міг відміняти останні зміни своєї ставки під час конкретного раунду та власної черги.
- Відміна ставки заборонялась у час, відмінний віл власної черги.
- У випадку успішної зміни - 200 Bid was cancelled
- У випадку спроби зміни ставки в інший час - 400 Bad request, cannot cancel bid in current state
- Саме два останні ендпойнти давали можливість взаємодіяти Користувачу з аукціоном та впливати на його стан.
Причини відмови від застарілої авторизації та ендпойнтів Єдиного інтерфейсу:
- Безпека: це створювало не захищене з’єднання, що могло служити витіком приватної інформації, скомпрометувати торги, заволодіти даними учасника, діяти від його імені та ін.
- Навантаження: руми перенавантажували систему та ресурси.Якщо відкривати в нових вкладках браузера, кожна рахується як окрема операція.
Альтернативний спосіб взаємодії з аукціоном без залучення діючого інтерфейсу модулю аукціонів:
- Якщо майданчик програмно перейде за допомогою посилання оновленої авторизації через auth сервер (https://procedure.prozorro.sale/api/auth/auction?token=...)
- То зможе отримати cookies даних користувача
За допомогою останніх є можливість реалізувати власне підключення до аукціону та взаємодіяти з ним
Типи раундів
Мають бути доступні такі типи раундів:
- Пауза
- Послідовний раунд (англійський)
- Голандський раунд
- Одночасний раунд
- Пріорітетний раунд
- Перший раунд
- Розкриття
Опис кожного раунду включає в себе такі дані:
- Назва - умовно-формальна назва раунду
- Системна назва - значення, що має використовуватись в конфігурації для додавання такого раунду
- Опис логіки - стислий опис принципу згідно якого діють учасники на такому кроці
- Подія для завершення - після чого переходимо до наступного раунду
- Напрямок зміни ставок - в який бік має відбуватись зміна ставок учасниками
- Обмеження ставки - які обмеження накладаються на ставку, що може зробити учасник торгів
- База - з яким значенням порівнюється нове значення для накладення обмеження
- Крок - значення, яке має відрізняти нову ставку від Бази
- Тривалість - визначення тривалості періоду
- Принцип формування - стале значення або принцип визначення
- Значення - абсолютне значення або періоду цілком, або змінної, що використовується в принципі формування
- Відображення ставок - дані, що додаються до вже відкритих в МА даних на цьому кроці
- Перелік учасників - чи бачать учасники дані про інших учасників торгів
- Значення (масив) - відображення значень ставок учасників
- Інше - специфічні дані, притаманні унікальним типам раундів
- Пост-дії - що має виконуватися після
- Зміна значень - які дані змінюються порівняно з масивом, що раунд отримав на вхід
- Сортування - чи відбувається сортування (ранжування) учасників по результатах виконання раунду та у який спосіб
- Інше - специфічні дії/параметри/умови тощо, притаманні унікальним типам раундів
- Лог - інформація, яка має потрапляти в публічний лог аукціону по завершенні раунду
Опис типів раундів
- Назва: Пауза
- Системна назва: pause
- Опис логіки: Статично відображається інформація, що вже відкрита на момент початку раунду. Жодних змін не виконується. Не може бути останнім раундом торгів
- Подія для завершення: Час вичерпано
- Напрямок зміни ставок: -
- Обмеження ставки (масив):
- База: -
- Крок: -
- Тривалість:
- Принцип формування: Константа
- Значення: Конфігурація. Ціле, в хвилинах, >0
- Відображення ставки:
- Перелік учасників: -
- Значення ставок (масив): -
- Інше: -
- Пост-дії:
- Зміна значень: -
- Сортування: -
- Інше: -
- Лог: тип раунду; назва раунду; час початку раунду; час закінчення раунду
Приклад: Конфігурація:
- step: pause duration: 3
Дані на вхід: minimalStep: 500 participants:
- id: A price: 68000 amount: 120 order: 2
- id: B price: 65000 amount: 100 order: 3
- id: C price: 70000 amount: 110 order: 1
Дані на виході: minimalStep: 500 participants:
- id: A price: 68000 amount: 120 order: 2
- id: B price: 65000 amount: 100 order: 3
- id: C price: 70000 amount: 110 order: 1
...
- Назва: Послідовний раунд (англійський)
- Системна назва: sequential
- Опис логіки: Всі учасники згідно з отриманою з попереднього раунду послідовністю змінюють свої ставки, після чого відбувається зміна послідовності для наступного раунду шляхом сортування ставок
- Подія для завершення: Всі учасники мали можливість в свою чергу зробити ставку
- Напрямок зміни ставок: Конфігурація. На підвищення / На пониження
- Обмеження ставки (масив):
- База: Конфігурація. Попреденя ставка самого учасника (user); Попередня найбільша/найменша ставка (extremum); Без обмежень (в такому разі значення Крок не враховується) (no); Не підлягає зміні (fixed )
- Крок: Вхідний параметр: Мінімальний крок, визначається при створенні процедури
- Тривалість:
- Принцип формування: Мультиплікація по кількості користувачів
- Значення: Конфігурація. Ціле, в хвилинах, >0
- Відображення ставки:
- Перелік учасників: Конфігурація. Ні / Анонімний / Персоніфікований
- Значення ставок (масив): Конфігурація. Так/Ні - для кожного значення
- Інше: Значення Перелік учасників: "Ні" передбачає, що значення ставок н відображається апріорі
- Пост-дії:
- Зміна значень: Оновлення значень ставок, що змінилися
- Сортування: Так
- Інше: Конфігурація. Пауза між учасниками - Ціле, в хвилинах, >=0
- Лог: тип раунду; назва раунду; час початку раунду; час завершення раунду; час виконання сортування ставок. для кожного учасника: bid.id; час початку черги; час завершення черги; остання цінова пропозиція; час подачі останньої цінової пропозиції
Приклад: Конфігурація: step: sequential
- direction: up
- limitation:
- price:
- base: user
- step: minimalStep
- amount:
- base: fixed
- duration: 3
- show:
- names: anonymous
- bids:
- price: yes
- amount: yes
- pause_between_bids: 0
Дані на вхід: minimalStep: 500 participants:
- id: A price: 68000 amount: 120 order: 2
- id: B price: 65000 amount: 100 order: 3
- id: C price: 70000 amount: 110 order: 1
Дії учасників: Час: 9:30 - 16:30 Учасник А:
- Час: 11:40-11:43
- Ціна: 68,000
Учасник В:
- Час: 11:43-11:46
- Ціна: 70,001
Учасник С:
- Час: 11:46-11:49
- Ціна: 70,500
Дані на виході: participants:
- id: A price: 68000 amount: 120 order: 3
- id: B price: 70001 amount: 100 order: 2
- id: C price: 70500 amount: 110 order: 1
...
- Назва: Голандський раунд
- Системна назва: dutch
- Опис логіки: Один раз за інтервал (згідно конфігурації) система автоматично пораундово змінює (зменшує або збільшує) доступний для учасників розмір ставки. раунд (розмір) зміни визначається як певний відсоток від первинної ціни (стартової ціни аукціону, яку отримав раунд в якості вхідного параметру, якщо голандський раунд є першим; або - ціни, що зформувалась на попередніх раундах, якщо голандський раунд - не перший). Учасник, що першим підтвердив готовність запропонувати доступну в певний момент часу ставку, стає переможцем раунду. Після цього жоден учасник не може зробити ніяких дій зі ставками до завершення раунду. У разі, якщо ніхто не запропонував ставку до завершення раунду, переможець не визначається
- Подія для завершення: Час вичерпано
- Напрямок зміни ставок: Конфігурація. На підвищення / На пониження
- Обмеження ставки (масив):
- База: Поточне автоматично визначене значення ставки на момент здійснення ставки (фактично - погодження з певним значенням ставки; саме значення користувач не вводить)
- Крок: -
- Тривалість:
- Принцип формування: Конфігурація. Константа(const) / Мультиплікація по кількості раундів (calculation)
- Значення: Конфігурація. Константа: Ціле, в хвилинах, >0 - визначає загальну тривалість раунду. Мультиплікація: Ціле, в хвилинах, >0 - тривалість раунду визначиться як наведене значення, помножене на кількість раундів
- Відображення ставки:
- Перелік учасників: Ні
- Значення ставок (масив): Конфігурація. Ставка, на якій було зупинено пораундову зміну ціни: Ні / Анонімний / Персоніфікований
- Інше: Інформація про перебіг пораундової зміни ставок: від початку раунду відображаються усі заплановані раунди з цінами, що будуть доступні в різні часові проміжки, і зазначенням цих часових проміжків. В будь-який момент часу має бути однозначно зрозуміло які цінові пропозиції: а) були доступні від початку раунду, але їх час вже вичерпано; б) доступні в момент спостереження (завжди одна цінова пропозиція); в) будуть доступні в майбутньому
- Пост-дії:
- Зміна значень: 1) Оновлення значень ставок, що змінилися; 2) Встановлення пріорітету (priority): конфігурація, ціле, >0
- Сортування: Встановлення єдиному переможцю значення order: 1, усім іншим - order: 0
- Інше:
- Кількість кроків: Вхідний параметр, має визначатись при створенні процедури
- Кількість кроків за замовчанням: Конфігурація. Ціле, від 1 до 100
- Кількість кроків за замовчанням: Ціле, від 1 до 49 (має враховуватись тільки у випадку, коли в конфігурації для тривалості обрано Мультиплікацію)
- Відсоток кроку за замовченням: 1
- Мінімальна ціна: У разі зниження ціни до значень менше, ніж 1 гривня, для таких кроків ціна визначається = 1 гривня
- Лог: тип раунду; назва раунду; час початку раунду; час завершення раунду; bid.id, що зупинив раунд; час подачі цінової пропозиції (зупинки автоматичної зміни ціни); для кожного учасника, що був зареєстрований: bid.id
Приклад: Конфігурація: step: dutch direction: down length: type: const duration: 420 show: step stopped: anonymus steps: default_number: 80 priority_to_set: 1
Дані на вхід: numberOfSteps: 65 participants:
- id: A price: 68000 amount: 120 order: 2 priority: 0
- id: B price: 65000 amount: 100 order: 3 priority: 0
- id: C price: 70000 amount: 110 order: 1 priority: 0 (фактично всі вхідні параметри не беруться до уваги)
Дії учасників: Час: 9:30 - 16:30 Учасник А:
- Час: 15:28
- Ціна: 348,000
- Результат: ставку відхилено
Учасник В:
- Час: 14:35
- Ціна: 455,000
- Результат: ставку прийнято
Учасник С:
Дані на виході: participants:
- id: A price: 0 amount: 0 order: 0 priority: 0
- id: B price: 455,000 amount: 0 order: 1 priority: 1
- id: C price: 0 amount: 0 order: 0 priority: 0
...
- Назва: Одночасний раунд
- Системна назва: simultaneous
- Опис логіки: Всі учасники, що мають значення priority: 0, одночасно подають свої пропозиції. Учасники можуть змінювати свої пропозиції будь-яку кількість раз під час раунду. Враховується тільки остання затверджена ставка. Учасники не бачать ставок одне одного до завершення раунду
- Подія для завершення: Час вичерпано
- Напрямок зміни ставок: Конфігурація. На підвищення / На пониження
- Обмеження ставки (масив):
- База: Конфігурація. Попреденя ставка самого учасника (user) / Попередня найбільша/найменша ставка (extremum) / Без обмежень (в такому разі значення кроку не враховується) (no) / Не підлягає зміні (fixed)
- Крок: Вхідний параметр
- Тривалість:
- Принцип формування: Константа
- Значення: Конфігурація. Ціле, в хвилинах, >0
- Відображення ставки:
- Перелік учасників: Ні
- Значення ставок (масив): Ні
- Інше: Значення Перелік учасників: Інформація, що не змінюувалась під час кроку, не відображається (тобто якщо учасник не подав ставку - рядок з його ідентифікатором не відображається не залежно від інших налаштувань відображення)
- Пост-дії:
- Зміна значень: Оновлення значень ставок, що змінилися
- Сортування: Так
- Інше:
- Перелік учасників на початку раунду: Конфігурація. Ні / Анонімний / Персоніфікований
- Значення ставок (масив) на початку раунду: Конфігурація. Так/Ні - для кожного значення
- Лог: тип раунду; назва раунду; час початку раунду; час завершення раунду; час виконання сортування ставок& . Lля кожного учасника: bid.id, остання цінова пропозиція, час подачі останньої цінової пропозиції
Приклад: step: simultaneous direction: up limitation: price: base: extremum step: minimalStep duration: 10 show: names: anonymus bids: price: yes
Дані на вхід: participants:
- id: A price: 0 order: 0 priority: 0
- id: B price: 0 order: 0 priority: 0
- id: C price: 70000 order: 1 priority: 1
- id: D price: 0 order: 0 priority: 2
Дії учасників: Учасник А:
15:32 price: 63,000 результат - ставку відхилено
15:38 price: 75,000 результат: ставку прийнято
Учасник В:
- 15:33 price: 88,000 результат: ставку прийнято
Учасник С:
- не може робити ставку
Учасник D:
- не може робити ставку
Дані на виході: participants:
- id: A price: 75000 order: 2 priority: 0
- id: B price: 88000 order: 1 priority: 0
- id: C price: 70000 order: 3 priority: 1
- id: D price: 0 order: 4 priority: 2
...
- Назва: Пріорітетний раунд
- Системна назва: precedence
- Опис логіки: Учасник, який на початку раунду має флаг пріорітету з найменшим значенням, відмінним від нуля (priority: Х),подає свою пропозицію. зазначений учасники може змінювати свої пропозиції будь-яку кількість разів під час раунду. Враховується тільки остання затверджена ставка. Інші учасники не бачать значення пропозиції, що змінюється, до завершення раунду. Усі інші учасники (з пріорітетом 0 або не мінімальним) не роблять ставки
- Подія для завершення: Час вичерпано
- Напрямок зміни ставок: Конфігурація. На підвищення / На пониження
- Обмеження ставки (масив):
- База: Конфігурація. Попреденя ставка самого учасника (user) / Попередня найбільша/найменша ставка (extremum) / Без обмежень (в такому разі значення кроку не враховується) (no) / Не підлягає зміні (fixed)
- Крок: Вхідний параметр
- Тривалість:
- Принцип формування: Константа
- Значення: Конфігурація. Ціле, в хвилинах, >0
- Відображення ставки:
- Перелік учасників: Ні
- Значення ставок (масив): Ні
- Інше: Значення Перелік учасників: Інформація, що не змінюувалась під час кроку, не відображається (тобто якщо учасник не подав ставку - рядок з його ідентифікатором не відображається не залежно від інших налаштувань відображення)
- Пост-дії:
- Зміна значень: Оновлення значень ставок, що змінилися. Встановлення пріорітету (priority) учасника, що робив ставку, в значення priority: 0
- Сортування: Так
- Інше:
- Перелік учасників на початку раунду: Конфігурація. Ні / Анонімний / Персоніфікований
- Значення ставок (масив) на початку раунду: Конфігурація. Так/Ні - для кожного значення
- Лог: тип раунду; назва раунду; час початку раунду; час завершення раунду; час виконання сортування ставок& . Lля кожного учасника: bid.id, остання цінова пропозиція, час подачі останньої цінової пропозиції
Приклад: step: precedence direction: up limitation: price: base: extremum step: minimalStep duration: 5 show: names: anonymus bids: price: yes
Дані на вхід: participants:
- id: A price: 75000 order: 2 priority: 0
- id: B price: 88000 order: 1 priority: 0
- id: C price: 70000 order: 3 priority: 1
- id: D price: 0 order: 0 priority: 2
Дії учасників: Учасник А:
- не може робити ставку
Учасник В:
- не може робити ставку
Учасник С:
- час: 15:49 price: 89,501 результат: ставку прийнято
Учасник D:
- не може робити ставку
Дані на виході: participants:
- id: A price: 75000 order: 3 priority: 0
- id: B price: 88000 order: 2 priority: 0
- id: C price: 89501 order: 1 priority: 0
- id: D price: 0 order: 4 priority: 2
...
- Назва: Розкриття
- Системна назва: final
- Опис логіки: Обов'язковий раунд для будь-якої конфігурації аукціону. Єдина дія - примусове розкриття усіх до того прихованих даних усіх попередніх кроків аукціону, а також - формулювання та оголошення результатів торгів. Оголошення має включати в себе legalName усіх учасників та масиви ставок для кожного учасника
- Подія для завершення: Час вичерпано
- Напрямок зміни ставок: -
- Обмеження ставки (масив):
- База: Ставки не здійснюються
- Крок: -
- Тривалість:
- Принцип формування: Константа
- Значення: 5 секунди (або менше, в залежності від завантаженості системи)
- Відображення ставки:
- Перелік учасників: Персоніфікований
- Значення ставок (масив): Так
- Інше: Розкриття імен і ставок в усіх попередніх раундах
- Пост-дії:
- Зміна значень: -
- Сортування: -
- Інше: Завершення аукціону, передача даних для подальших кроків процедури
- Інше:
- Лог: тип раунду; назва раунду; час початку раунду; час закінчення раунду; повідомлення "Аукціон завершено"
Приклад: Конфігурація:
- step: final
Дані на вхід: minimalStep: 500 participants:
- id: A price: 68000 amount: 120 order: 2
- id: B price: 65000 amount: 100 order: 3
- id: C price: 70000 amount: 110 order: 1