Цей документ описує логіку роботи ендпоінтів, які дозволяють отримувати історію змін (версіонування) документів на рівні процедури та її вкладених сутностей (bids, awards, contracts, prolongations).

Як формується історія документів

Історія документів тісно пов'язана зі змінами самої процедури. Будь-яке коригування процедури ініціює збереження її копії до моменту оновлення. Історія документів - це агрегація всіх змін конкретного документа між цими точками збереження.

Життєвий цикл збереження на прикладі:

  1. Створення процедури → історія документів порожня.

  2. Додавання 1-го документа → створюється збереження процедури без документів → історія документів порожня (документ ще не має попередніх версій).

  3. Додавання bid до процедури → створюється збереження процедури з 1-м документом → 1-й документ потрапляє в історію.

  4. Оновлення 1-го документа → створюється збереження процедури з попередньою версією документа → стара версія 1-го документа з'являється в історії.

  5. Додавання 2-го документа → створюється збереження з уже оновленим 1-м документом → оновлений 1-й документ також фіксується в історії.

Формати отримання історії

API надає два підходи до отримання історії документів: для всіх документів сутності одразу та для одного конкретного документа.

Загальна історія (Всі документи сутності)

GET .../documents/history

Повертає історію змін усіх документів, що належать до вказаної сутності (процедури, біда, договору тощо).

  • Формат відповіді (200 OK): JSON-об'єкт (словник).

    • Ключі: id документа.

    • Значення: Масив об'єктів з історичними версіями цього документа.

  • Особливості (параметр with_actual): Ендпоінти групової історії підтримують query-параметр with_actual (приймає значення 1 або 0).

    • with_actual=1: До масиву історії кожного документа додається також об'єкт його останньої (актуальної) версії.

    • with_actual=0 (або без параметра): Повертається лише історія (попередні версії).

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

  • без значення в with_actual - повертає помилку 'query param with_actual: Value must be 0, 1, true, false, no, yes' з кодом 422
  • with_actual=0 - не повертає актуальний об'єкт історії
  • with_actual=false - не повертає актуальний об'єкт історії
  • with_actual=no - не повертає актуальний об'єкт історії
  • with_actual=1 - повертає актуальний об'єкт історії
  • with_actual=true - повертає актуальний об'єкт історії
  • with_actual=yes - повертає актуальний об'єкт історії
  • будь яке значення, яке не дорівнює значенням вище with_actual={any_value} - повертає помилку 'query param with_actual: Value must be 0, 1, true, false, no, yes' з кодом 422


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

{
    "d784b322e3e74c27976d1f0f918541f5": [
        {
            "id": "d784b322e3e74c27976d1f0f918541f5",
            "title": {
                "uk_UA": "Документ 1 ОНОВЛЕНО"
            },
            "description": {
                "uk_UA": "Опис документа 1 ОНОВЛЕНО"
            },
            "url": "https://procedure-sandbox.prozorro.sale/api/documents/public/c79d8bce01694c9998dd87b171a568ce",
            "documentOf": "auction",
            "documentType": "technicalSpecifications",
            "datePublished": "2026-07-17T10:08:02.530000Z",
            "dateModified": "2026-07-17T10:08:31.513000Z",
            "format": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "hash": "md5:82683da8cc7afc1b03fe3b7d2aff569e",
            "_ds_id": "c79d8bce01694c9998dd87b171a568ce",
            "_ds_scope": "public"
        },
        {
            "id": "d784b322e3e74c27976d1f0f918541f5",
            "title": {
                "uk_UA": "Документ1"
            },
            "description": {
                "uk_UA": "Опис документа 1"
            },
            "url": "https://procedure-sandbox.prozorro.sale/api/documents/public/c79d8bce01694c9998dd87b171a568ce",
            "documentOf": "auction",
            "documentType": "technicalSpecifications",
            "datePublished": "2026-07-17T10:08:02.530000Z",
            "dateModified": "2026-07-17T10:08:02.530000Z",
            "format": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "hash": "md5:82683da8cc7afc1b03fe3b7d2aff569e",
            "_ds_id": "c79d8bce01694c9998dd87b171a568ce",
            "_ds_scope": "public"
        }
    ]
}

Історія конкретного документа

GET .../documents/{doc_id}/history


Повертає лінійну історію змін лише одного вказаного документа.


  • Формат відповіді (200 OK): JSON-масив (List). На відміну від загальної історії, відповідь є масивом об'єктів історичних версій без обгортання у словник з ключем ID документа.


Перелік ендпоінтів

(Для всіх запитів обов'язковою є передача токена авторизації або query-параметра acc_token)

Procedure Documents

  • Всі документи: GET /api/procedures/{procedure_id}/documents/history (підтримує with_actual)

  • Один документ: GET /api/procedures/{procedure_id}/documents/{doc_id}/history

Bid Documents

  • Всі документи: GET /api/procedures/{procedure_id}/bids/{bid_id}/documents/history (підтримує with_actual)

  • Один документ: GET /api/procedures/{procedure_id}/bids/{bid_id}/documents/{doc_id}/history

Award Documents

  • Всі документи: GET /api/procedures/{procedure_id}/awards/{award_id}/documents/history (підтримує with_actual)

  • Один документ: GET /api/procedures/{procedure_id}/awards/{award_id}/documents/{doc_id}/history

Contract Documents

  • Всі документи: GET /api/procedures/{procedure_id}/contracts/{contract_id}/documents/history (підтримує with_actual)

  • Один документ: GET /api/procedures/{procedure_id}/contracts/{contract_id}/documents/{doc_id}/history

Prolongation Documents

  • Всі документи: GET /api/procedures/{procedure_id}/prolongations/{prolongation_id}/documents/history (підтримує with_actual)

  • Один документ: GET /api/procedures/{procedure_id}/prolongations/{prolongation_id}/documents/{doc_id}/history

  • No labels