Tutorial

Exploring basic rules

Let’s try exploring the /agreements endpoint:

GET /api/2.5/agreements HTTP/1.0
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "next_page": {
    "path": "/api/2.5/agreements?offset=",
    "uri": "http://lb-api-sandbox.prozorro.gov.ua/api/2.5/agreements?offset=",
    "offset": ""
  },
  "data": []
}

Just invoking it reveals an empty set.

Agreement is transferred from the tender system by an automated process.

Creating agreement

Let’s say that we have conducted tender and it has complete status. When the tender is completed, agreement (that has been created in the tender system) is transferred to the agreement system automatically.

Brokers (eMalls) can’t create agreements in the agreement system.

Getting agreement

Agreement in the tender system

GET /api/2.5/tenders/3b7af763f1e2441080bbb1c6bdb75005/agreements/eb35d61e7cde4a008003f5cd17ddb0c7 HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "active",
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "date": "2019-10-25T01:00:00+03:00",
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7"
  }
}

Agreement id is the same in both tender and agreement system.

Let’s access the URL of the created object inside agreement system:

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7 HTTP/1.0
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "active",
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
    "numberOfContracts": 3,
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      },
      "contactPoint": {
        "name_en": "State administration",
        "name": "Державне управління справами",
        "availableLanguage": "uk",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "legalName_en": "dus.gov.ua",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name_en": "State administration"
    },
    "owner": "broker",
    "dateModified": "2019-10-25T01:00:00+03:00",
    "tender_id": "3b7af763f1e2441080bbb1c6bdb75005"
  }
}

Getting access

In order to get rights for future agreement editing, you need to use this view PATCH: /agreements/{id}/credentials?acc_token={tender_token} with the API key of the eMall (broker), where tender was generated.

In the PATCH: /agreements/{id}/credentials?acc_token={tender_token}:

  • id stands for agreement id,
  • tender_token is tender’s token (is used for agreement token generation).

Response will contain access.token for the agreement that can be used for further agreement modification.

PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/credentials?acc_token=113d359719654baa8660704cc68f4d21 HTTP/1.0
Authorization: Bearer broker
Content-Length: 0
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "a9a0150a69cf4d248e9408dac484ea31",
    "token": "76b0c07026994e7089d5f9716acfc3e7"
  },
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "active",
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
    "numberOfContracts": 3,
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      },
      "contactPoint": {
        "name_en": "State administration",
        "name": "Державне управління справами",
        "availableLanguage": "uk",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "legalName_en": "dus.gov.ua",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name_en": "State administration"
    },
    "owner": "broker",
    "dateModified": "2019-10-25T01:00:00+03:00",
    "tender_id": "3b7af763f1e2441080bbb1c6bdb75005"
  }
}

Let’s view agreements.

GET /api/2.5/agreements HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "next_page": {
    "path": "/api/2.5/agreements?offset=2019-10-25T01%3A00%3A00%2B03%3A00",
    "uri": "http://lb-api-sandbox.prozorro.gov.ua/api/2.5/agreements?offset=2019-10-25T01%3A00%3A00%2B03%3A00",
    "offset": "2019-10-25T01:00:00+03:00"
  },
  "data": [
    {
      "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
      "dateModified": "2019-10-25T01:00:00+03:00"
    }
  ]
}

We do see the internal id of a agreement (that can be used to construct full URL by prepending http://api-sandbox.openprocurement.org/api/0/agreements/) and its dateModified datestamp.

Modifying agreement

Essential agreement terms can be modified by the submission of a new change object to the Agreement.changes container. Change can be one of this types ChangeTaxRate in cfaua, ChangeItemPriceVariation in cfaua, ChangePartyWithdrawal in cfaua or ChangeThirdParty in cfaua

All changes are processed by the endpoint /agreement/{id}/changes.

Submitting a change

Let’s add new change to the agreement:

POST /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 244
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "rationale": "Опис причини змін егріменту"
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "pending",
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "rationale": "Опис причини змін егріменту",
    "date": "2019-10-25T01:00:00+03:00",
    "id": "563cc544379744ed9b023a88ff6e415b"
  }
}

Note that you should provide value in rationaleType field. This field is required.

You can view the change:

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes/563cc544379744ed9b023a88ff6e415b HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "pending",
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "rationale": "Опис причини змін егріменту",
    "date": "2019-10-25T01:00:00+03:00",
    "id": "563cc544379744ed9b023a88ff6e415b"
  }
}

Change can be modified while it is in the pending status:

PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes/563cc544379744ed9b023a88ff6e415b?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 255
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "rationale": "Друга і третя поставка має бути розфасована"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "pending",
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "rationale": "Друга і третя поставка має бути розфасована",
    "date": "2019-10-25T01:00:00+03:00",
    "id": "563cc544379744ed9b023a88ff6e415b"
  }
}

Uploading change document

Document can be added only while change is in the pending status.

Document has to be added in two stages:

  • you should upload document
POST /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 156
Content-Type: multipart/form-data; boundary=---BOUNDARY
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
-----BOUNDARY
Content-Disposition: form-data; name="file"; filename="agreement_changes.doc"
Content-Type: application/msword

content
-----BOUNDARY--


Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://lb-api-sandbox.prozorro.gov.ua/api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/b8f02cdfc2cc43c2a6a5f014d524afc6
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement_changes.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
    "format": "application/msword",
    "documentOf": "agreement",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}
  • you should set document properties "documentOf": "change" and "relatedItem": "{change.id}" in order to bind the uploaded document to the change:
PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/b8f02cdfc2cc43c2a6a5f014d524afc6?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 85
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "documentOf": "change",
    "relatedItem": "563cc544379744ed9b023a88ff6e415b"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement_changes.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
    "format": "application/msword",
    "documentOf": "change",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
    "relatedItem": "563cc544379744ed9b023a88ff6e415b",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}

Updating agreement properties

Now you can update agreement properties which belong to the change.

PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes/563cc544379744ed9b023a88ff6e415b?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 95
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "modifications": [
      {
        "itemId": "caa9e0207afd49d48ca553e562787699",
        "factor": 0.1605
      }
    ]
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "pending",
    "modifications": [
      {
        "itemId": "caa9e0207afd49d48ca553e562787699",
        "factor": 0.1605
      }
    ],
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "rationale": "Друга і третя поставка має бути розфасована",
    "date": "2019-10-25T01:00:00+03:00",
    "id": "563cc544379744ed9b023a88ff6e415b"
  }
}

In case of multiple Item you are allowed to change in modifications each factor.

Agreement preview

Also, while change is in the pending status, you can see agreement as change would be applied. You need to use this view GET: /agreements/{id}/preview?acc_token={agreement_token}.

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/preview?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "active",
    "documents": [
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_changes.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
        "format": "application/msword",
        "documentOf": "change",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
        "relatedItem": "563cc544379744ed9b023a88ff6e415b",
        "dateModified": "2019-10-25T01:00:00+03:00"
      }
    ],
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
    "numberOfContracts": 3,
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      },
      "contactPoint": {
        "name_en": "State administration",
        "name": "Державне управління справами",
        "availableLanguage": "uk",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "legalName_en": "dus.gov.ua",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name_en": "State administration"
    },
    "owner": "broker",
    "changes": [
      {
        "status": "pending",
        "modifications": [
          {
            "itemId": "caa9e0207afd49d48ca553e562787699",
            "factor": 0.1605
          }
        ],
        "rationaleType": "taxRate",
        "rationale_en": "Agreement change cause",
        "rationale": "Друга і третя поставка має бути розфасована",
        "date": "2019-10-25T01:00:00+03:00",
        "id": "563cc544379744ed9b023a88ff6e415b"
      }
    ],
    "dateModified": "2019-10-25T01:00:00+03:00",
    "tender_id": "3b7af763f1e2441080bbb1c6bdb75005"
  }
}

As you can see, value.amount on contracts unitPrices are changed due modification is applied. So if this modification is what you need, you can apply change.

Applying the change

Change can be applied by switching to the active status.

In order to apply active status dateSigned field must be set.

After this change can’t be modified anymore.

PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes/563cc544379744ed9b023a88ff6e415b?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 73
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "status": "active",
    "dateSigned": "2019-10-25T01:00:00+03:00"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "active",
    "modifications": [
      {
        "itemId": "caa9e0207afd49d48ca553e562787699",
        "factor": 0.1605
      }
    ],
    "rationaleType": "taxRate",
    "rationale_en": "Agreement change cause",
    "dateSigned": "2019-10-25T01:00:00+03:00",
    "rationale": "Друга і третя поставка має бути розфасована",
    "date": "2019-10-25T01:00:00+03:00",
    "id": "563cc544379744ed9b023a88ff6e415b"
  }
}

dateSigned field validation:

  • for the first agreement change date should be after agreement.dateSigned;
  • for all next change objects date should be after the previous change.dateSigned.

You can view all changes:

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/changes HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": [
    {
      "status": "active",
      "modifications": [
        {
          "itemId": "caa9e0207afd49d48ca553e562787699",
          "factor": 0.1605
        }
      ],
      "rationaleType": "taxRate",
      "rationale_en": "Agreement change cause",
      "dateSigned": "2019-10-25T01:00:00+03:00",
      "rationale": "Друга і третя поставка має бути розфасована",
      "date": "2019-10-25T01:00:00+03:00",
      "id": "563cc544379744ed9b023a88ff6e415b"
    }
  ]
}

All changes are also listed on the agreement view.

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7 HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "active",
    "documents": [
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_changes.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
        "format": "application/msword",
        "documentOf": "change",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
        "relatedItem": "563cc544379744ed9b023a88ff6e415b",
        "dateModified": "2019-10-25T01:00:00+03:00"
      }
    ],
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
    "numberOfContracts": 3,
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      },
      "contactPoint": {
        "name_en": "State administration",
        "name": "Державне управління справами",
        "availableLanguage": "uk",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "legalName_en": "dus.gov.ua",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name_en": "State administration"
    },
    "owner": "broker",
    "changes": [
      {
        "status": "active",
        "modifications": [
          {
            "itemId": "caa9e0207afd49d48ca553e562787699",
            "factor": 0.1605
          }
        ],
        "rationaleType": "taxRate",
        "rationale_en": "Agreement change cause",
        "dateSigned": "2019-10-25T01:00:00+03:00",
        "rationale": "Друга і третя поставка має бути розфасована",
        "date": "2019-10-25T01:00:00+03:00",
        "id": "563cc544379744ed9b023a88ff6e415b"
      }
    ],
    "dateModified": "2019-10-25T01:00:00+03:00",
    "tender_id": "3b7af763f1e2441080bbb1c6bdb75005"
  }
}

Uploading documentation

Procuring entity can upload PDF files into the created agreement. Uploading should follow the upload rules.

POST /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 148
Content-Type: multipart/form-data; boundary=---BOUNDARY
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
-----BOUNDARY
Content-Disposition: form-data; name="file"; filename="agreement.doc"
Content-Type: application/msword

content
-----BOUNDARY--


Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://lb-api-sandbox.prozorro.gov.ua/api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/06b952bff38e4fc1ac0c02e300258b31
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/b9e59cc37f3b4ea482720fdcd52663fd?KeyID=a8968c46&Signature=tB3dzahvI1nyoMMK1C4j%252BTtfGcfWnAHbVpNVgsAbLzeG0c6Yxg88SXWtNpFEd88xSlrC2XmDD8u7JyxyWWu8Aw%253D%253D",
    "format": "application/msword",
    "documentOf": "agreement",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "id": "06b952bff38e4fc1ac0c02e300258b31",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}

201 Created response code and Location header confirm document creation. We can additionally query the documents collection API endpoint to confirm the action:

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": [
    {
      "hash": "md5:00000000000000000000000000000000",
      "title": "agreement.doc",
      "url": "http://public-docs-sandbox.prozorro.gov.ua/get/b9e59cc37f3b4ea482720fdcd52663fd?KeyID=a8968c46&Signature=tB3dzahvI1nyoMMK1C4j%252BTtfGcfWnAHbVpNVgsAbLzeG0c6Yxg88SXWtNpFEd88xSlrC2XmDD8u7JyxyWWu8Aw%253D%253D",
      "format": "application/msword",
      "documentOf": "agreement",
      "datePublished": "2019-10-25T01:00:00+03:00",
      "id": "06b952bff38e4fc1ac0c02e300258b31",
      "dateModified": "2019-10-25T01:00:00+03:00"
    },
    {
      "hash": "md5:00000000000000000000000000000000",
      "title": "agreement_changes.doc",
      "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
      "format": "application/msword",
      "documentOf": "change",
      "datePublished": "2019-10-25T01:00:00+03:00",
      "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
      "relatedItem": "563cc544379744ed9b023a88ff6e415b",
      "dateModified": "2019-10-25T01:00:00+03:00"
    }
  ]
}

And again we can confirm that there are two documents uploaded.

POST /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 172
Content-Type: multipart/form-data; boundary=---BOUNDARY
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
-----BOUNDARY
Content-Disposition: form-data; name="file"; filename="agreement_additional_docs.doc"
Content-Type: application/msword

additional info
-----BOUNDARY--


Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://lb-api-sandbox.prozorro.gov.ua/api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/29c3149772784d53925c9e7a92100127
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement_additional_docs.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/969a6a3afa2f4ab4bb509b879677b524?KeyID=a8968c46&Signature=jlyxJA4vfD9CFkAuK7tRqSwSDowOqG93YM9JBLMijslAGYKlj1YVEVJa4Vh6ocN%252BwRaNoVS2cW1pjHMw89g3Cw%253D%253D",
    "format": "application/msword",
    "documentOf": "agreement",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "id": "29c3149772784d53925c9e7a92100127",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}

In case we made an error, we can reupload the document over the older version:

PUT /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/29c3149772784d53925c9e7a92100127?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 181
Content-Type: multipart/form-data; boundary=---BOUNDARY
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
-----BOUNDARY
Content-Disposition: form-data; name="file"; filename="agreement_additional_docs.doc"
Content-Type: application/msword

extended additional info
-----BOUNDARY--


Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement_additional_docs.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/c07ec373bb544ebd9a72d671c047f8e2?KeyID=a8968c46&Signature=%252Bz1cAt5Xysyr6pqW5eT1tRGwShFPsqzsdvecZRqEYpp7INNmpI68BtHdNLA9M6yH9dIgAJF967e8AGr6gkE9Aw%253D%253D",
    "format": "application/msword",
    "documentOf": "agreement",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "id": "29c3149772784d53925c9e7a92100127",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}

And we can see that it is overriding the original version:

GET /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7/documents/29c3149772784d53925c9e7a92100127?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Host: lb-api-sandbox.prozorro.gov.ua

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "hash": "md5:00000000000000000000000000000000",
    "title": "agreement_additional_docs.doc",
    "url": "http://public-docs-sandbox.prozorro.gov.ua/get/c07ec373bb544ebd9a72d671c047f8e2?KeyID=a8968c46&Signature=%252Bz1cAt5Xysyr6pqW5eT1tRGwShFPsqzsdvecZRqEYpp7INNmpI68BtHdNLA9M6yH9dIgAJF967e8AGr6gkE9Aw%253D%253D",
    "format": "application/msword",
    "documentOf": "agreement",
    "datePublished": "2019-10-25T01:00:00+03:00",
    "previousVersions": [
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_additional_docs.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/969a6a3afa2f4ab4bb509b879677b524?KeyID=a8968c46&Signature=jlyxJA4vfD9CFkAuK7tRqSwSDowOqG93YM9JBLMijslAGYKlj1YVEVJa4Vh6ocN%252BwRaNoVS2cW1pjHMw89g3Cw%253D%253D",
        "format": "application/msword",
        "documentOf": "agreement",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "29c3149772784d53925c9e7a92100127",
        "dateModified": "2019-10-25T01:00:00+03:00"
      }
    ],
    "id": "29c3149772784d53925c9e7a92100127",
    "dateModified": "2019-10-25T01:00:00+03:00"
  }
}

Completing agreement

Agreement can be completed by switching to terminated status. Let’s perform these actions in single request:

PATCH /api/2.5/agreements/eb35d61e7cde4a008003f5cd17ddb0c7?acc_token=76b0c07026994e7089d5f9716acfc3e7 HTTP/1.0
Authorization: Bearer broker
Content-Length: 34
Content-Type: application/json
Host: lb-api-sandbox.prozorro.gov.ua
DATA:
{
  "data": {
    "status": "terminated"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "agreementID": "UA-2019-10-25-000001-3a5c4330ac6643cc8ed442175cc20dba1",
    "status": "terminated",
    "documents": [
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_changes.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/a51bbc22366e41c6b012eeb99b212994?KeyID=a8968c46&Signature=6dYoov%252BfN7fg0%252BkmGHAQPvWlPvpf%2Fj1WIfx5e1YWZhoA7APSP60DFNJ5upL34Ckd3f9JCbUJrK2aR00ums%252BPAA%253D%253D",
        "format": "application/msword",
        "documentOf": "change",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "b8f02cdfc2cc43c2a6a5f014d524afc6",
        "relatedItem": "563cc544379744ed9b023a88ff6e415b",
        "dateModified": "2019-10-25T01:00:00+03:00"
      },
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/b9e59cc37f3b4ea482720fdcd52663fd?KeyID=a8968c46&Signature=tB3dzahvI1nyoMMK1C4j%252BTtfGcfWnAHbVpNVgsAbLzeG0c6Yxg88SXWtNpFEd88xSlrC2XmDD8u7JyxyWWu8Aw%253D%253D",
        "format": "application/msword",
        "documentOf": "agreement",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "06b952bff38e4fc1ac0c02e300258b31",
        "dateModified": "2019-10-25T01:00:00+03:00"
      },
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_additional_docs.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/969a6a3afa2f4ab4bb509b879677b524?KeyID=a8968c46&Signature=jlyxJA4vfD9CFkAuK7tRqSwSDowOqG93YM9JBLMijslAGYKlj1YVEVJa4Vh6ocN%252BwRaNoVS2cW1pjHMw89g3Cw%253D%253D",
        "format": "application/msword",
        "documentOf": "agreement",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "29c3149772784d53925c9e7a92100127",
        "dateModified": "2019-10-25T01:00:00+03:00"
      },
      {
        "hash": "md5:00000000000000000000000000000000",
        "title": "agreement_additional_docs.doc",
        "url": "http://public-docs-sandbox.prozorro.gov.ua/get/c07ec373bb544ebd9a72d671c047f8e2?KeyID=a8968c46&Signature=%252Bz1cAt5Xysyr6pqW5eT1tRGwShFPsqzsdvecZRqEYpp7INNmpI68BtHdNLA9M6yH9dIgAJF967e8AGr6gkE9Aw%253D%253D",
        "format": "application/msword",
        "documentOf": "agreement",
        "datePublished": "2019-10-25T01:00:00+03:00",
        "id": "29c3149772784d53925c9e7a92100127",
        "dateModified": "2019-10-25T01:00:00+03:00"
      }
    ],
    "contracts": [
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f875346eda7843a3b3b9fefc28f5662c",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "103a7285c17e4a3a92938b08b51b44c7",
        "id": "edd47e59d168470e9f2ed55517c9fee1"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "f552af0c653d4d6a9ece8b678225ca20",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "a5916ee001574ac2a1491c63d8c9e6d6",
        "id": "ee201e03da3140a9929ff4670a73b7de"
      },
      {
        "status": "active",
        "unitPrices": [
          {
            "value": {
              "currency": "UAH",
              "amount": 14.93,
              "valueAddedTaxIncluded": true
            },
            "relatedItem": "caa9e0207afd49d48ca553e562787699"
          }
        ],
        "suppliers": [
          {
            "scale": "micro",
            "name": "Державне управління справами",
            "address": {
              "postalCode": "01220",
              "countryName": "Україна",
              "streetAddress": "вул. Банкова, 11, корпус 1",
              "region": "м. Київ",
              "locality": "м. Київ"
            },
            "name_en": "State administration",
            "identifier": {
              "scheme": "UA-EDR",
              "legalName_en": "dus.gov.ua",
              "id": "00037256",
              "uri": "http://www.dus.gov.ua/"
            },
            "contactPoint": {
              "name_en": "State administration",
              "name": "Державне управління справами",
              "telephone": "0440000000"
            }
          }
        ],
        "bidID": "8f15d54cd54a4ea2a61c9d56f0c444da",
        "date": "2019-10-25T01:00:00+03:00",
        "awardID": "76208648f4a94148b4168b2d16218c72",
        "id": "cbb0e93a778548938332f1b4f6bea6f7"
      }
    ],
    "items": [
      {
        "relatedLot": "2b33a80c73cb4c39957170a963adfe52",
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "ДК021",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2018-06-27T13:39:09.362837+03:00",
          "endDate": "2018-06-30T13:39:09.362837+03:00"
        },
        "id": "caa9e0207afd49d48ca553e562787699",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5.0
      }
    ],
    "id": "eb35d61e7cde4a008003f5cd17ddb0c7",
    "numberOfContracts": 3,
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      },
      "contactPoint": {
        "name_en": "State administration",
        "name": "Державне управління справами",
        "availableLanguage": "uk",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "legalName_en": "dus.gov.ua",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name_en": "State administration"
    },
    "owner": "broker",
    "changes": [
      {
        "status": "active",
        "modifications": [
          {
            "itemId": "caa9e0207afd49d48ca553e562787699",
            "factor": 0.1605
          }
        ],
        "rationaleType": "taxRate",
        "rationale_en": "Agreement change cause",
        "dateSigned": "2019-10-25T01:00:00+03:00",
        "rationale": "Друга і третя поставка має бути розфасована",
        "date": "2019-10-25T01:00:00+03:00",
        "id": "563cc544379744ed9b023a88ff6e415b"
      }
    ],
    "dateModified": "2019-10-25T01:00:00+03:00",
    "tender_id": "3b7af763f1e2441080bbb1c6bdb75005"
  }
}

If agreement is unsuccessful reasons for termination terminationDetails should be specified.

Any future modification to the agreement are not allowed.

It may be useful to see top requirements: Test Cases for III level of accreditation and Test Cases for IV level of accreditation.