Правила роботи з обʼєктами ЦБД (API)

Для взаємодії Майданчика з ЦБД рекомендуємо використовувати Swagger Prozorro.Sale

У цьому документі розглядаємо загальні правила роботи з API, що допоможуть правильно взаємодіяти з об'єктами ЦБД.

Публікація обʼєкта (POST)

Щоб опублікувати об'єкт у ЦБД, потрібно надіслати API-запит із правильною структурою body, заповнивши всі обов’язкові поля.

Якщо хоча б одне обов'язкове поле відсутнє, ЦБД поверне помилку:

Для публікації невистачає одного обовʼязкового поля:

Не вистачає декількох обовʼязкових полів:

Додавання об'єкта у вкладений масив

Якщо потрібно додати новий елемент до вкладеного масиву (наприклад, items[] у Процедурі), необхідно використовувати POST, а не PATCH.

Наприклад, в раніше опублікованій Процедурі необхідно додати в items[] ще один item

Потрібно використати запит:

Цей запит додає новий item без зміни інших полів Процедури чи існуючих об'єктів у items[]

НЕ рекомендується:

Використовувати PATCH, якщо в тілі запиту передаються всі поля Процедури (зокрема, ті, що не змінюються).

Інші приклади використання:

Організатору необхідно до раніше опублікованої процедури додати ще один document в documents[]:
Учасник публікує свою заяву на участь, чим, на рівні ЦБД, змінює bids[] тим, що додає в нього ще один обʼєкт bid
Публікація Запитання (на рівні ЦБД - додати ще один обʼєкт question до questions[]
та інші схожі за логікою дії

Правило:

Якщо потрібно ДОДАТИ до обʼєкта типу list[] ще один підобʼєкт - використовуємо POST

Редагування обʼєкта (PATCH)

Якщо виникає потреба змінити значення в полях раніше опублікованого обʼєкта, необхідно використовувати PATCH

Основні принципи використання PATCH:

Передавайте лише ті поля, які змінюються.
Якщо змінюється вкладений об'єкт, передавайте його повністю (включаючи всі вкладені поля, навіть якщо їх значення не змінюється).
Не передавайте весь об'єкт Процедури, якщо змінюється лише окреме поле або вкладений об'єкт.

Приклад 1:

В опублікованій процедурі необхідно редагувати ТІЛЬКИ guarantee, необхідно передавати всі вкладені в guarantee поля: currency та amount

curl --location --request PATCH 'https://procedure-dev.prozorro.sale/api/procedures/67ac75cc33f701d712c6d315?acc_token=5d0f4461-353e-4a61-a5c6-19fcced1e908' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
"guarantee": {
"currency": "UAH",
"amount": 2000
}
}

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

При використанні PATCH для редагування вкладених об'єктів завжди передавайте весь вкладений об'єкт зі всіма його полями, навіть якщо змінюється лише одне з них.

Для деталізації прикладу, варто звернути увагу, що в зазначеному випадку може НЕ мінятись guarantee.currency, а тільки guarantee.amount, але так як використовується PATCH запит всієї процедури передавати в запиті необхідно guarantee{} та всі вкладені в нього поля. Якщо передати guarantee{} та лише поле, яке змінюється - guarantee.amount, то ЦБД поверне валідаційну помилку:

Приклад 2: Редагування вкладеного обʼєкта

Для деяких полів типу list[] розроблено окремі endpoints, які дозволяють вносити зміни у вкладені обʼєкти.

Організатору в раніше опублікованій процедурі необхідно ЗМІНИТИ в items[] поля для якогось конкретного item, який вже присутній в процедурі.

Правильним рішенням буде використати:

Цей запит - це дія над конкретним обʼєктом item, передавати в запиті на редагування потрібно тільки поля і моделі item, в які вносяться зміни.

curl --location --request PATCH 'https://procedure-dev.prozorro.sale/api/procedures/67ac9c5833f701d712c6d935/items/82551f5e71c4431a82e7b65674f90381?acc_token=def1fb8d-84f2-4c14-9e88-dac8a5931702' \
--header 'Content-Type: application/json' \
--header 'Authorization: *****' \
--data '{
"description": {
"uk_UA": "Опис першого айтема РЕДАГУЮ"
},
"address": {
"addressID": {
"id": "4600000000",
"scheme": "koatuu"
},
"streetAddress": {
"uk_UA": "вул.РЕДАГУЮ, 222"
},
"locality": {
"uk_UA": "Дніпро"
},
"region": {
"uk_UA": "Дніпропетровська область"
},
"countryName": {
"uk_UA": "Україна"
}
}
}'

В даному прикладі потреба відредагувати була для поля items[x].description та items[x].address.streetAddress. Але в запиті необхідно передати весь обʼєкт address, бо він є вкладеним у items[x]

Редагування окремого елемента в масиві

Якщо потрібно відредагувати конкретний item у масиві items[], не потрібно передавати весь масив. Достатньо передати лише той елемент масиву, який змінюється, зі зміненими полями.

Приклади використання:

Редагування окремого item у items[]
Оновлення полів у document в documents[]
Редагування конкретного bid у bids[]
та інші

Правила:

PATCH - Якщо потрібно змінити тільки окремі поля в обʼєкті без впливу на інші поля
При редагуванні значень в полях обʼєкта, в PATCH запиті необхідно передавати тільки поля і вкладені обʼєкти в яких необхідно змінити значення в полях і НЕ передавати поля в яких не відбувається змін
Якщо передати в PATCH запиті поле в якому не змінилось значення від попереднього, то ЦБД прийме це за зміну в полі + в обʼєкті оновиться dateModified
Якщо необхідно редагувати певні поля у вкладеному обʼєкті, то необхідно передавати всі поля вкладеного обʼєкта, навіть ті, в яких не відбувається змін значень. Приклад

Видалення обʼєкта

Прямого видалення обʼєта в системі не передбачено, тому методи DELETE недоступні.

Якщо виникає необхідність в існуючому обʼєкті видалити значення в не обовʼязковому полі, неохідно скористатись PATCH запитом, де передати всі поля обʼєкта, окрім того, який потрібно видалити.

Загальне правило:

Щоб видалити значення необов'язкового поля, потрібно:
Відправити PATCH-запит,
Передати всі поля, крім того, яке потрібно видалити.

Якщо відправити поле з порожнім значенням ("", null), система може не обробити це як видалення, а просто зберегти поле з новим значенням.

Space shortcuts

Page tree