Tutorial

When customer needs to change current broker this customer should provide new preferred broker with transfer key for an object (tender, bid, complaint, etc.). Then new broker should create Transfer object and send request with Transfer id and transfer key (received from customer) in order to change object’s owner.

Examples for Tender

Tender ownership change

Let’s view transfer example for tender.

Tender creation

At first let’s create a tender:

POST /api/2.3/tenders?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 2347
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "tenderPeriod": {
      "endDate": "2016-07-18T19:00:53.269636"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35
    },
    "enquiryPeriod": {
      "endDate": "2016-07-11T19:00:53.269636"
    },
    "procurementMethodType": "belowThreshold",
    "value": {
      "currency": "UAH",
      "amount": 500
    },
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "kind": "general",
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ"
      }
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "id": "44617100-9",
          "description": "Cartons"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "countryName": "Україна",
          "postalCode": "79000",
          "region": "м. Київ",
          "streetAddress": "вул. Банкова 1",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-07-06T19:00:53.269636",
          "endDate": "2016-07-09T19:00:53.269636"
        },
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ]
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/12d2efec3691480ca952e13390e8076b
{
  "access": {
    "transfer": "2e92410f70a842cf9cb448608f15f71e",
    "token": "b002699cdc054a91a8bcb2f4b7d7b633"
  },
  "data": {
    "procurementMethod": "open",
    "status": "active.enquiries",
    "tenderID": "UA-2016-07-04-000001",
    "tenderPeriod": {
      "startDate": "2016-07-11T19:00:53.269636+03:00",
      "endDate": "2016-07-18T19:00:53.269636+03:00"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35.0,
      "valueAddedTaxIncluded": true
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-07-06T19:00:53.269636+03:00",
          "endDate": "2016-07-09T19:00:53.269636+03:00"
        },
        "id": "331fe5c7ee96407eb0c883bd0fe45b1a",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "procurementMethodType": "belowThreshold",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "submissionMethod": "electronicAuction",
    "next_check": "2016-07-11T19:00:53.269636+03:00",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "kind": "general",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "enquiryPeriod": {
      "startDate": "2016-07-04T19:00:54.536131+03:00",
      "endDate": "2016-07-11T19:00:53.269636+03:00"
    },
    "owner": "broker",
    "dateModified": "2016-07-04T19:00:54.541025+03:00",
    "id": "12d2efec3691480ca952e13390e8076b",
    "awardCriteria": "lowestCost"
  }
}

broker is current tender’s owner.

Note that response’s access section contains a transfer key which is used to change tender ownership.

After tender’s registration in CDB broker has to provide its customer with transfer key.

Transfer creation

Broker that is going to become new tender owner should create a Transfer.

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyMTo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "d5a764c13c16403cb19fbb3690562498",
    "token": "4ae34ee951af40cda75780ba61c58172"
  },
  "data": {
    "date": "2016-07-04T19:00:54.613149+03:00",
    "id": "a5a9d0af94cdebf91d8ea39b8702410a"
  }
}

Transfer object contains new access token and new transfer token for the object that will be transferred to new broker.

Transfer can be retrieved by id:

GET /api/2.3/transfers/a5a9d0af94cdebf91d8ea39b8702410a HTTP/1.0
Authorization: Basic YnJva2VyMTo=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-07-04T19:00:54.613149+03:00",
    "id": "a5a9d0af94cdebf91d8ea39b8702410a"
  }
}

Changing tender’s owner

Pay attention that only broker with appropriate accreditation level can become new owner. Otherwise broker will be forbidden from this action.

To change tender’s ownership new broker should send POST request to appropriate /tenders/id/ with data section containing id of Transfer and transfer token received from customer:

POST /api/2.3/tenders/12d2efec3691480ca952e13390e8076b/ownership HTTP/1.0
Authorization: Basic YnJva2VyMTo=
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "2e92410f70a842cf9cb448608f15f71e",
    "id": "a5a9d0af94cdebf91d8ea39b8702410a"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "procurementMethod": "open",
    "status": "active.enquiries",
    "tenderID": "UA-2016-07-04-000001",
    "tenderPeriod": {
      "startDate": "2016-07-11T19:00:53.269636+03:00",
      "endDate": "2016-07-18T19:00:53.269636+03:00"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35.0,
      "valueAddedTaxIncluded": true
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-07-06T19:00:53.269636+03:00",
          "endDate": "2016-07-09T19:00:53.269636+03:00"
        },
        "id": "331fe5c7ee96407eb0c883bd0fe45b1a",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "procurementMethodType": "belowThreshold",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "submissionMethod": "electronicAuction",
    "numberOfBids": 0,
    "next_check": "2016-07-11T19:00:53.269636+03:00",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "kind": "general",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "enquiryPeriod": {
      "startDate": "2016-07-04T19:00:54.536131+03:00",
      "endDate": "2016-07-11T19:00:53.269636+03:00"
    },
    "owner": "broker1",
    "dateModified": "2016-07-04T19:00:54.821413+03:00",
    "id": "12d2efec3691480ca952e13390e8076b",
    "awardCriteria": "lowestCost"
  }
}

Updated owner value indicates that ownership is successfully changed.

Note that new broker has to provide its customer with new transfer key (generated in Transfer object).

After Transfer is applied it stores tender path in usedFor property:

GET /api/2.3/transfers/a5a9d0af94cdebf91d8ea39b8702410a HTTP/1.0
Authorization: Basic YnJva2VyMTo=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-07-04T19:00:54.613149+03:00",
    "id": "a5a9d0af94cdebf91d8ea39b8702410a",
    "usedFor": "/tenders/12d2efec3691480ca952e13390e8076b"
  }
}

‘Used’ Transfer can’t be applied to any other object.

Let’s try to change the tender using token received on Transfer creation:

PATCH /api/2.3/tenders/12d2efec3691480ca952e13390e8076b?acc_token=4ae34ee951af40cda75780ba61c58172 HTTP/1.0
Authorization: Basic YnJva2VyMTo=
Content-Length: 62
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "description": "broker1 now can change the tender"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "procurementMethod": "open",
    "status": "active.enquiries",
    "tenderID": "UA-2016-07-04-000001",
    "tenderPeriod": {
      "startDate": "2016-07-11T19:00:53.269636+03:00",
      "endDate": "2016-07-18T19:00:53.269636+03:00"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35.0,
      "valueAddedTaxIncluded": true
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-07-06T19:00:53.269636+03:00",
          "endDate": "2016-07-09T19:00:53.269636+03:00"
        },
        "id": "331fe5c7ee96407eb0c883bd0fe45b1a",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "procurementMethodType": "belowThreshold",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "submissionMethod": "electronicAuction",
    "awardCriteria": "lowestCost",
    "next_check": "2016-07-11T19:00:53.269636+03:00",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "kind": "general",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "enquiryPeriod": {
      "startDate": "2016-07-04T19:00:54.536131+03:00",
      "endDate": "2016-07-11T19:00:53.269636+03:00"
    },
    "owner": "broker1",
    "dateModified": "2016-07-04T19:00:55.047163+03:00",
    "id": "12d2efec3691480ca952e13390e8076b",
    "description": "broker1 now can change the tender"
  }
}

Bid ownership change

Let’s submit a bid via current broker:

POST /api/2.3/tenders/12d2efec3691480ca952e13390e8076b/bids HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 843
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "value": {
      "amount": 500
    },
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "countryName": "Україна",
          "postalCode": "01220",
          "region": "м. Київ",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "locality": "м. Київ"
        }
      }
    ]
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/12d2efec3691480ca952e13390e8076b/bids/caddc3ab74fb47aba406db4b10acb5c0
{
  "access": {
    "transfer": "c90d3632e4f6439a98439cdb9787d246",
    "token": "2967e61e6dff46e693bf4f30d6c8ccf0"
  },
  "data": {
    "date": "2016-07-04T19:00:55.244506+03:00",
    "id": "caddc3ab74fb47aba406db4b10acb5c0",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "postalCode": "01220",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        }
      }
    ]
  }
}

Response contains access section with a transfer key that can be used to change bid ownership.

Current broker has to provide its customer with transfer key for the bid. Then customer can pass it to new broker.

Transfer creation

Note that each Transfer can be applied only once. New broker (that is going to become new bid owner) should create separate Transfer for each owner change:

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "ad80ea5feded4474b48a3d66892ebe0a",
    "token": "ed50a8a9a72d463098fa14724c91c348"
  },
  "data": {
    "date": "2016-07-04T19:00:55.291937+03:00",
    "id": "a5a9d0af94cdebf91d8ea39b8702449a"
  }
}

Transfer object contains new access token and new transfer key for the object that will be transferred to new broker.

Changing bid’s owner

Pay attention that only broker with appropriate accreditation level can become new owner. Otherwise broker will be forbidden from this action.

New broker should send POST request to appropriate /tenders/id/bids/id with data section containing id of Transfer and transfer key for the bid received from customer:

POST /api/2.3/tenders/12d2efec3691480ca952e13390e8076b/bids/caddc3ab74fb47aba406db4b10acb5c0/ownership HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "c90d3632e4f6439a98439cdb9787d246",
    "id": "a5a9d0af94cdebf91d8ea39b8702449a"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-07-04T19:00:55.244506+03:00",
    "id": "caddc3ab74fb47aba406db4b10acb5c0",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "postalCode": "01220",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        }
      }
    ]
  }
}

Now new broker became bid owner. Check whether new owner is able to change the bid:

PATCH /api/2.3/tenders/12d2efec3691480ca952e13390e8076b/bids/caddc3ab74fb47aba406db4b10acb5c0?acc_token=ed50a8a9a72d463098fa14724c91c348 HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Content-Length: 36
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "value": {
      "amount": 450
    }
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-07-04T19:00:55.643914+03:00",
    "id": "caddc3ab74fb47aba406db4b10acb5c0",
    "value": {
      "currency": "UAH",
      "amount": 450.0,
      "valueAddedTaxIncluded": true
    },
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "postalCode": "01220",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        }
      }
    ]
  }
}

New broker should provide its customer with new transfer key (received within Transfer object).

Check whether Transfer object has successfully stored bid path in usedFor property:

GET /api/2.3/transfers/a5a9d0af94cdebf91d8ea39b8702449a HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-07-04T19:00:55.291937+03:00",
    "id": "a5a9d0af94cdebf91d8ea39b8702449a",
    "usedFor": "/tenders/12d2efec3691480ca952e13390e8076b/bids/caddc3ab74fb47aba406db4b10acb5c0"
  }
}

Complaint ownership change

Let’s submit a complaint via current broker:

POST /api/2.3/tenders/d9755e9ef15448ec8f9de71353a12692/complaints HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Content-Length: 899
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "status": "claim",
    "title": "complaint title",
    "description": "complaint description",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ"
      }
    }
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/d9755e9ef15448ec8f9de71353a12692/complaints/194e085f4f3d4d88bdbb6550a937f4d8
{
  "access": {
    "transfer": "8523230826f74b52a60c0086eacb918f",
    "token": "6d338a4067a64e758ff3d99e7da247be"
  },
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "dateSubmitted": "2016-09-12T14:02:32.342316+03:00",
    "complaintID": "UA-2016-09-12-000001.1",
    "date": "2016-09-12T14:02:32.342296+03:00",
    "type": "claim",
    "id": "194e085f4f3d4d88bdbb6550a937f4d8"
  }
}

Response contains access section with a transfer key that can be used to change complaint ownership.

Current broker has to provide its customer with transfer key for the complaint. Then customer can pass it to new broker.

Transfer creation

Note that each Transfer can be applied only once. New broker (that is going to become new complaint owner) should create separate Transfer for each owner change:

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "10bac5472a98405081927ae5e5b17dd8",
    "token": "c240ed9eb96a4871b054d66e5f61c887"
  },
  "data": {
    "date": "2016-09-12T14:02:32.420315+03:00",
    "id": "51af2ddd862b84438f51c08d2502ad20"
  }
}

Transfer object contains new access token and new transfer key for the object that will be transferred to new broker.

Changing complaint’s owner

Pay attention that only broker with appropriate accreditation level can become new owner. Otherwise broker will be forbidden from this action.

New broker should send POST request to appropriate /tenders/id/complaints/id with data section containing id of Transfer and transfer key for the complaint received from customer:

POST /api/2.3/tenders/d9755e9ef15448ec8f9de71353a12692/complaints/194e085f4f3d4d88bdbb6550a937f4d8/ownership HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "8523230826f74b52a60c0086eacb918f",
    "id": "51af2ddd862b84438f51c08d2502ad20"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "dateSubmitted": "2016-09-12T14:02:32.342316+03:00",
    "complaintID": "UA-2016-09-12-000001.1",
    "date": "2016-09-12T14:02:32.342296+03:00",
    "type": "claim",
    "id": "194e085f4f3d4d88bdbb6550a937f4d8"
  }
}

Now new broker became complaint owner. Check whether new owner is able to change the complaint:

PATCH /api/2.3/tenders/d9755e9ef15448ec8f9de71353a12692/complaints/194e085f4f3d4d88bdbb6550a937f4d8?acc_token=c240ed9eb96a4871b054d66e5f61c887 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 75
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "status": "cancelled",
    "cancellationReason": "Important reason"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "cancelled",
    "description": "complaint description",
    "title": "complaint title",
    "cancellationReason": "Important reason",
    "dateCanceled": "2016-09-12T14:02:32.783062+03:00",
    "dateSubmitted": "2016-09-12T14:02:32.342316+03:00",
    "complaintID": "UA-2016-09-12-000001.1",
    "date": "2016-09-12T14:02:32.787637+03:00",
    "type": "claim",
    "id": "194e085f4f3d4d88bdbb6550a937f4d8"
  }
}

New broker should provide its customer with new transfer key (received within Transfer object).

Check whether Transfer object has successfully stored complaint path in usedFor property:

GET /api/2.3/transfers/51af2ddd862b84438f51c08d2502ad20 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-09-12T14:02:32.579921+03:00",
    "id": "51af2ddd862b84438f51c08d2502ad20",
    "usedFor": "/tenders/d9755e9ef15448ec8f9de71353a12692/complaints/194e085f4f3d4d88bdbb6550a937f4d8"
  }
}

Award complaint ownership change

Let’s submit a award complaint via current broker:

POST /api/2.3/tenders/19243d1faf904243941a9eb1a517e7c7/awards/5b8aed9a411c49c0b81e02ba17adea56/complaints?acc_token=b37f411b662d495ebd9821b5fee390c6 HTTP/1.0
Authorization: Basic YnJva2VyMjo=
Content-Length: 899
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "status": "claim",
    "title": "complaint title",
    "description": "complaint description",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ"
      }
    }
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/19243d1faf904243941a9eb1a517e7c7/awards/5b8aed9a411c49c0b81e02ba17adea56/complaints/53d2ff9160924d24ab323cc3163129ca
{
  "access": {
    "transfer": "8aca5cf1d889494abf375bf2a29d56fb",
    "token": "373b86f03f3c4d4a94386f918c8a4707"
  },
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "dateSubmitted": "2016-09-12T14:16:25.910153+03:00",
    "complaintID": "UA-2016-09-12-000001.2",
    "date": "2016-09-12T14:16:25.910121+03:00",
    "type": "claim",
    "id": "53d2ff9160924d24ab323cc3163129ca"
  }
}

Response contains access section with a transfer key that can be used to change complaint ownership.

Current broker has to provide its customer with transfer key for the complaint. Then customer can pass it to new broker.

Transfer creation

Note that each Transfer can be applied only once. New broker (that is going to become new complaint owner) should create separate Transfer for each owner change:

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "da64f946abef4fb7b8fb8b8171836a1f",
    "token": "d08a65388caa4df0abe28ce6df54c1f9"
  },
  "data": {
    "date": "2016-09-12T14:16:26.014667+03:00",
    "id": "51af2ddd862b84438f51c08d2502f204"
  }
}

Transfer object contains new access token and new transfer key for the object that will be transferred to new broker.

Changing complaint’s owner

Pay attention that only broker with appropriate accreditation level can become new owner. Otherwise broker will be forbidden from this action.

New broker should send POST request to appropriate /tenders/id/awards/id/complaints/id with data section containing id of Transfer and transfer key for the complaint received from customer:

POST /api/2.3/tenders/19243d1faf904243941a9eb1a517e7c7/awards/5b8aed9a411c49c0b81e02ba17adea56/complaints/53d2ff9160924d24ab323cc3163129ca/ownership HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "8aca5cf1d889494abf375bf2a29d56fb",
    "id": "51af2ddd862b84438f51c08d2502f204"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "dateSubmitted": "2016-09-12T14:16:25.910153+03:00",
    "complaintID": "UA-2016-09-12-000001.2",
    "date": "2016-09-12T14:16:25.910121+03:00",
    "type": "claim",
    "id": "53d2ff9160924d24ab323cc3163129ca"
  }
}

Now new broker became award complaint owner. Check whether new owner is able to change the award complaint:

PATCH /api/2.3/tenders/19243d1faf904243941a9eb1a517e7c7/awards/5b8aed9a411c49c0b81e02ba17adea56/complaints/53d2ff9160924d24ab323cc3163129ca?acc_token=d08a65388caa4df0abe28ce6df54c1f9 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 75
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "status": "cancelled",
    "cancellationReason": "Important reason"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "cancelled",
    "description": "complaint description",
    "title": "complaint title",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "cancellationReason": "Important reason",
    "dateCanceled": "2016-09-12T14:16:26.365057+03:00",
    "dateSubmitted": "2016-09-12T14:16:25.910153+03:00",
    "complaintID": "UA-2016-09-12-000001.2",
    "date": "2016-09-12T14:16:26.369934+03:00",
    "type": "claim",
    "id": "53d2ff9160924d24ab323cc3163129ca"
  }
}

New broker should provide its customer with new transfer key (received within Transfer object).

Check whether Transfer object has successfully stored complaint path in usedFor property:

GET /api/2.3/transfers/51af2ddd862b84438f51c08d2502f204 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-09-12T14:16:26.180862+03:00",
    "id": "51af2ddd862b84438f51c08d2502f204",
    "usedFor": "/tenders/19243d1faf904243941a9eb1a517e7c7/awards/5b8aed9a411c49c0b81e02ba17adea56/complaints/53d2ff9160924d24ab323cc3163129ca"
  }
}

Examples for Contract

Contract ownership change

Let’s view transfer example for contract transfer.

Transfer creation

First of all, you must know ID of the contract that you want to transfer.

Broker that is going to become new contract owner should create a Transfer.

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "a2680255671d4e0493bae6f976753b75",
    "token": "030fc8faf17d418b89308db5de67c3b3"
  },
  "data": {
    "date": "2016-12-09T16:02:33.262299+02:00",
    "id": "d57d310d2682fda164916e314f035b71"
  }
}

Transfer object contains new access token and new transfer token for the object that will be transferred to new broker.

Changing contract’s owner

In order to change contract’s ownership new broker should send POST request to appropriate /contracts/id/ with data section containing id of Transfer and transfer token received from customer:

POST /api/2.3/contracts/81c446f1a0e44a0e97f7c90a41f27593/ownership HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "4f86672cd6c14f24ba920afdf8b2a513",
    "id": "d57d310d2682fda164916e314f035b71"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "active",
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-03-20T18:47:47.136678+02:00",
          "endDate": "2016-03-23T18:47:47.136678+02:00"
        },
        "id": "c6c6e8ed4b1542e4bf13d3f98ec5ab59",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "suppliers": [
      {
        "contactPoint": {
          "email": "aagt@gmail.com",
          "telephone": "+380 (322) 91-69-30",
          "name": "Андрій Олексюк"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00137226",
          "uri": "http://www.sc.gov.ua/"
        },
        "name": "ДКП «Книга»",
        "address": {
          "postalCode": "79013",
          "countryName": "Україна",
          "streetAddress": "вул. Островського, 34",
          "region": "м. Львів",
          "locality": "м. Львів"
        }
      }
    ],
    "contractNumber": "contract #13111",
    "period": {
      "startDate": "2016-03-18T18:47:47.155143+02:00",
      "endDate": "2017-03-18T18:47:47.155143+02:00"
    },
    "value": {
      "currency": "UAH",
      "amount": 238.0,
      "valueAddedTaxIncluded": true
    },
    "id": "81c446f1a0e44a0e97f7c90a41f27593",
    "owner": "broker3",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "contractID": "UA-2016-03-18-000001-1",
    "dateSigned": "2016-03-18T18:48:05.762961+02:00",
    "awardID": "8481d7eb01694c25b18658036c236c5d",
    "dateModified": "2016-12-09T16:02:33.454074+02:00",
    "tender_id": "fb795ca46f8f4fa784018d3aeb009e88"
  }
}

Updated owner value indicates that ownership is successfully changed.

Note that new broker has to provide its customer with new transfer key (generated in Transfer object).

After Transfer is applied it stores contract path in usedFor property.

GET /api/2.3/transfers/d57d310d2682fda164916e314f035b71 HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-12-09T16:02:33.373230+02:00",
    "id": "d57d310d2682fda164916e314f035b71",
    "usedFor": "/contracts/81c446f1a0e44a0e97f7c90a41f27593"
  }
}

Let’s try to change the contract using token received on Transfer creation:

PATCH /api/2.3/contracts/81c446f1a0e44a0e97f7c90a41f27593?acc_token=030fc8faf17d418b89308db5de67c3b3 HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 64
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "description": "broker3 now can change the contract"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "active",
    "description": "broker3 now can change the contract",
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-03-20T18:47:47.136678+02:00",
          "endDate": "2016-03-23T18:47:47.136678+02:00"
        },
        "id": "c6c6e8ed4b1542e4bf13d3f98ec5ab59",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "suppliers": [
      {
        "contactPoint": {
          "email": "aagt@gmail.com",
          "telephone": "+380 (322) 91-69-30",
          "name": "Андрій Олексюк"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00137226",
          "uri": "http://www.sc.gov.ua/"
        },
        "name": "ДКП «Книга»",
        "address": {
          "postalCode": "79013",
          "countryName": "Україна",
          "streetAddress": "вул. Островського, 34",
          "region": "м. Львів",
          "locality": "м. Львів"
        }
      }
    ],
    "contractNumber": "contract #13111",
    "period": {
      "startDate": "2016-03-18T18:47:47.155143+02:00",
      "endDate": "2017-03-18T18:47:47.155143+02:00"
    },
    "value": {
      "currency": "UAH",
      "amount": 238.0,
      "valueAddedTaxIncluded": true
    },
    "id": "81c446f1a0e44a0e97f7c90a41f27593",
    "owner": "broker3",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "contractID": "UA-2016-03-18-000001-1",
    "dateSigned": "2016-03-18T18:48:05.762961+02:00",
    "awardID": "8481d7eb01694c25b18658036c236c5d",
    "dateModified": "2016-12-09T16:02:33.599999+02:00",
    "tender_id": "fb795ca46f8f4fa784018d3aeb009e88"
  }
}

Contract credentials change

In order to get rights for future contract editing, you need to generate Transfer object and then apply this Transfer using the endpoint POST: /contracts/{id}/ownership, where id stands for contract ID.

Create new transfer

Let`s generate Transfer.

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "203e2ecb4aa245328f4a1027f636b894",
    "token": "72056473dd7342f38716fbdadc758172"
  },
  "data": {
    "date": "2016-12-09T16:02:33.696057+02:00",
    "id": "d57d310d2682fda164916e314f035fa3"
  }
}

Transfer object contains new access.token that can be used for further contract modification and new transfer token.

Changing contract’s credentials

In order to generate new contract’s credentials broker should send POST request to appropriate endpoint /contracts/{id}/ownership with data section containing id of new Transfer generated previously and tender_token.

POST /api/2.3/contracts/81c446f1a0e44a0e97f7c90a41f27593/ownership HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 104
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "tender_token": "72d29f2d595e4893930f06eeb603c07e",
    "id": "d57d310d2682fda164916e314f035fa3"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "active",
    "description": "broker3 now can change the contract",
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-03-20T18:47:47.136678+02:00",
          "endDate": "2016-03-23T18:47:47.136678+02:00"
        },
        "id": "c6c6e8ed4b1542e4bf13d3f98ec5ab59",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "suppliers": [
      {
        "contactPoint": {
          "email": "aagt@gmail.com",
          "telephone": "+380 (322) 91-69-30",
          "name": "Андрій Олексюк"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00137226",
          "uri": "http://www.sc.gov.ua/"
        },
        "name": "ДКП «Книга»",
        "address": {
          "postalCode": "79013",
          "countryName": "Україна",
          "streetAddress": "вул. Островського, 34",
          "region": "м. Львів",
          "locality": "м. Львів"
        }
      }
    ],
    "contractNumber": "contract #13111",
    "period": {
      "startDate": "2016-03-18T18:47:47.155143+02:00",
      "endDate": "2017-03-18T18:47:47.155143+02:00"
    },
    "value": {
      "currency": "UAH",
      "amount": 238.0,
      "valueAddedTaxIncluded": true
    },
    "id": "81c446f1a0e44a0e97f7c90a41f27593",
    "owner": "broker3",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "contractID": "UA-2016-03-18-000001-1",
    "dateSigned": "2016-03-18T18:48:05.762961+02:00",
    "awardID": "8481d7eb01694c25b18658036c236c5d",
    "dateModified": "2016-12-09T16:02:33.883437+02:00",
    "tender_id": "fb795ca46f8f4fa784018d3aeb009e88"
  }
}

After Transfer is applied it stores contract path in usedFor property and can`t be used for other object.

GET /api/2.3/transfers/d57d310d2682fda164916e314f035fa3 HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "date": "2016-12-09T16:02:33.794873+02:00",
    "id": "d57d310d2682fda164916e314f035fa3",
    "usedFor": "/contracts/81c446f1a0e44a0e97f7c90a41f27593"
  }
}

Let’s change the contract using token received on Transfer creation:

PATCH /api/2.3/contracts/81c446f1a0e44a0e97f7c90a41f27593?acc_token=72056473dd7342f38716fbdadc758172 HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 50
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "description": "new credentials works"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "active",
    "description": "new credentials works",
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "postalCode": "79000",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-03-20T18:47:47.136678+02:00",
          "endDate": "2016-03-23T18:47:47.136678+02:00"
        },
        "id": "c6c6e8ed4b1542e4bf13d3f98ec5ab59",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "suppliers": [
      {
        "contactPoint": {
          "email": "aagt@gmail.com",
          "telephone": "+380 (322) 91-69-30",
          "name": "Андрій Олексюк"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00137226",
          "uri": "http://www.sc.gov.ua/"
        },
        "name": "ДКП «Книга»",
        "address": {
          "postalCode": "79013",
          "countryName": "Україна",
          "streetAddress": "вул. Островського, 34",
          "region": "м. Львів",
          "locality": "м. Львів"
        }
      }
    ],
    "contractNumber": "contract #13111",
    "period": {
      "startDate": "2016-03-18T18:47:47.155143+02:00",
      "endDate": "2017-03-18T18:47:47.155143+02:00"
    },
    "value": {
      "currency": "UAH",
      "amount": 238.0,
      "valueAddedTaxIncluded": true
    },
    "id": "81c446f1a0e44a0e97f7c90a41f27593",
    "owner": "broker3",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "contractID": "UA-2016-03-18-000001-1",
    "dateSigned": "2016-03-18T18:48:05.762961+02:00",
    "awardID": "8481d7eb01694c25b18658036c236c5d",
    "dateModified": "2016-12-09T16:02:34.056818+02:00",
    "tender_id": "fb795ca46f8f4fa784018d3aeb009e88"
  }
}

Examples for OpenEU procedure

Bid qualification complaint ownership change

OpenEU procedure contains bid qualification (pre-qualification) stage that allows complaints.

We will use this OpenEU procedure tender as an example:

POST /api/2.3/tenders?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 2471
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "tenderPeriod": {
      "endDate": "2016-12-01T12:16:01.504061"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "id": "44617100-9",
          "description": "Cartons"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "countryName": "Україна",
          "postalCode": "79000",
          "region": "м. Київ",
          "streetAddress": "вул. Банкова 1",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-11-02T12:16:01.504061",
          "endDate": "2016-11-05T12:16:01.504061"
        },
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "title_en": "Cases for state awards",
    "value": {
      "currency": "UAH",
      "amount": 500
    },
    "procurementMethodType": "aboveThresholdEU",
    "procuringEntity": {
      "kind": "general",
      "name": "Державне управління справами",
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "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"
      }
    }
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/a48337f6bad64080a9f69f830514e059
{
  "access": {
    "transfer": "d12134ab8951482986fd19ab55ce7799",
    "token": "45f54fdc44944f948dc6361acee0dcb1"
  },
  "data": {
    "procurementMethod": "open",
    "status": "active.tendering",
    "tenderID": "UA-2016-10-31-000001",
    "tenderPeriod": {
      "startDate": "2016-10-31T12:16:09.967388+02:00",
      "endDate": "2016-12-01T12:16:01.504061+02:00"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35.0,
      "valueAddedTaxIncluded": true
    },
    "auctionPeriod": {
      "shouldStartAfter": "2017-01-06T00:00:00+02:00"
    },
    "complaintPeriod": {
      "startDate": "2016-10-31T12:16:09.967388+02:00",
      "endDate": "2016-11-27T00:00:00+02:00"
    },
    "title_en": "Cases for state awards",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "submissionMethod": "electronicAuction",
    "date": "2016-10-31T12:16:10.059425+02:00",
    "dateModified": "2016-10-31T12:16:10.065053+02:00",
    "procurementMethodType": "aboveThresholdEU",
    "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"
    },
    "enquiryPeriod": {
      "startDate": "2016-10-31T12:16:09.967388+02:00",
      "clarificationsUntil": "2016-11-24T12:16:01.504061+02:00",
      "endDate": "2016-11-21T12:16:01.504061+02:00"
    },
    "owner": "broker",
    "next_check": "2016-12-01T12:16:01.504061+02:00",
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "countryName": "Україна",
          "postalCode": "79000",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2016-11-02T12:16:01.504061+02:00",
          "endDate": "2016-11-05T12:16:01.504061+02:00"
        },
        "id": "e90fed8f9eec4a2c884adef8c224db89",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "id": "a48337f6bad64080a9f69f830514e059",
    "awardCriteria": "lowestCost"
  }
}

Response contains tender ID and access section with Tender token.

Submit a Bid

Let’s submit a bid for qualification:

POST /api/2.3/tenders/a48337f6bad64080a9f69f830514e059/bids HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 888
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "selfEligible": true,
    "selfQualified": true,
    "value": {
      "amount": 500
    },
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "countryName": "Україна",
          "postalCode": "01220",
          "region": "м. Київ",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "locality": "м. Київ"
        }
      }
    ]
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/a48337f6bad64080a9f69f830514e059/bids/55f611dd2f7c498891e3ceb7306f26d6
{
  "access": {
    "transfer": "e01de596a11e4b519005c3ba26c3bdc1",
    "token": "b2c4014e306943508f0a4fdc4c3e4a33"
  },
  "data": {
    "status": "pending",
    "selfEligible": true,
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "selfQualified": true,
    "tenderers": [
      {
        "contactPoint": {
          "name": "Державне управління справами",
          "telephone": "0440000000"
        },
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037256",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Державне управління справами",
        "address": {
          "postalCode": "01220",
          "countryName": "Україна",
          "streetAddress": "вул. Банкова, 11, корпус 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        }
      }
    ],
    "date": "2016-10-31T12:16:10.278984+02:00",
    "id": "55f611dd2f7c498891e3ceb7306f26d6"
  }
}

Response contains access section with a token key that can be used to create bid qualification complaint.

Submit a Complaint

Let’s create a bid qualification complaint:

POST /api/2.3/tenders/a48337f6bad64080a9f69f830514e059/qualifications/5bd908eda4a748828dd60cee85cbd7c4/complaints?acc_token=993c19ad89134b169998806725748742 HTTP/1.0
Authorization: Basic YnJva2VyNDo=
Content-Length: 899
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "status": "claim",
    "title": "complaint title",
    "description": "complaint description",
    "author": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "address": {
        "countryName": "Україна",
        "postalCode": "01220",
        "region": "м. Київ",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "locality": "м. Київ"
      }
    }
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/tenders/a48337f6bad64080a9f69f830514e059/qualifications/5bd908eda4a748828dd60cee85cbd7c4/complaints/9e9406f48a104502bce4f28a96ebec3f
{
  "access": {
    "transfer": "e2bc2a76f0414b65b34b3ef567413119",
    "token": "0f00f7c74124485580009bf37485109e"
  },
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "dateSubmitted": "2016-10-31T12:16:11.454427+02:00",
    "complaintID": "UA-2016-10-31-000001.1",
    "date": "2016-10-31T12:16:11.454410+02:00",
    "type": "claim",
    "id": "9e9406f48a104502bce4f28a96ebec3f"
  }
}

From response we take complaint id from data section and complaint transfer key from access section.

Changing complaint’s owner

Broker that is going to become new qualification complaint owner should create a Transfer.

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyNDo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "76539baec6414b02a2d7cf2bec55870d",
    "token": "e91eb2c19fc244b5a78e7b6c5bdfa81c"
  },
  "data": {
    "date": "2016-11-01T11:01:23.877124+02:00",
    "id": "413ef5e46cf4d07822bb1bb7ae0690d7"
  }
}

Transfer object contains new access token and new transfer key for the object that will be transferred to new broker.

New broker should send POST request to the appropriate /tenders/id/qualifications/id/complaints/id with data section containing id of Transfer and transfer key for the complaint received from customer:

POST /api/2.3/tenders/a48337f6bad64080a9f69f830514e059/qualifications/5bd908eda4a748828dd60cee85cbd7c4/complaints/9e9406f48a104502bce4f28a96ebec3f/ownership HTTP/1.0
Authorization: Basic YnJva2VyNDo=
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "e2bc2a76f0414b65b34b3ef567413119",
    "id": "89ad466830531e713214d0715500080a"
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "status": "claim",
    "description": "complaint description",
    "title": "complaint title",
    "dateSubmitted": "2016-10-31T12:16:11.454427+02:00",
    "complaintID": "UA-2016-10-31-000001.1",
    "date": "2016-10-31T12:16:11.454410+02:00",
    "type": "claim",
    "id": "9e9406f48a104502bce4f28a96ebec3f"
  }
}

Examples for Сompetitive Dialogue procedure

Stage1 procedure

Changing owner of tender in stage 1 is similar to Open UA or Open EU tenders procedure.

Stage2 procedure

To change second stage tender owner, we need transfer token received during getting access to second stage tender. Get token for second stage <http://openprocurementtendercompetitivedialogue.readthedocs.io/en/latest/tutorial.html#get-token-for-second-stage>

Transfer creation

Broker that is going to become new tender owner should create a Transfer.

POST /api/2.3/transfers HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 12
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {}
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
{
  "access": {
    "transfer": "7cb4384b8649499bac5d3a3a6493e808",
    "token": "7383c92f33ce461dbf5e4acec9c6ab30"
  },
  "data": {
    "date": "2017-02-07T12:00:20.239540+02:00",
    "id": "e89c01f817fb9640daa2244a7c0393e3"
  }
}

Transfer object contains new access token and new transfer token for the tender that will be transferred to new broker.

Changing tender’s stage2 owner

Pay attention that only broker with appropriate accreditation level can become new owner. Otherwise broker will be forbidden from this action.

To change tender’s ownership new broker should send POST request to appropriate /tenders/<tender_id>/ownership with data section containing id of Transfer and transfer token received from previous PATCH request to tender/<tender_id>/credentials?acc_token=<acc_token>.

POST /api/2.3/tenders/d2344d0c92f44741b5d0772abb62bf64/ownership HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 100
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "transfer": "a94cad539be54d208d905ddc12e410f8",
    "id": "e89c01f817fb9640daa2244a7c0393e3"
  }
}

Updated owner value indicates that ownership is successfully changed.

Note that new broker has to provide its customer with new transfer key (generated in Transfer object).

Let’s try to change the tender using token received on Transfer creation:

PATCH /api/2.3/tenders/9ae09ba13fb249bd8a06b6c9a464e858?acc_token=b192d9037fd74b06959de83775054a7b HTTP/1.0
Authorization: Basic YnJva2VyMzo=
Content-Length: 75
Content-Type: application/json
Host: api-sandbox.openprocurement.org
DATA:
{
  "data": {
    "tenderPeriod": {
      "endDate": "2017-03-09T11:54:43.387388+02:00"
    }
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "procurementMethod": "selective",
    "status": "draft.stage2",
    "dialogueID": "5a86dbd0cd51490b93f0e4618569a360",
    "tenderID": "UA-2017-02-07-000001",
    "tenderPeriod": {
      "startDate": "2017-02-07T11:54:43.132121+02:00",
      "endDate": "2017-03-09T11:54:43.387388+02:00"
    },
    "title": "футляри до державних нагород",
    "minimalStep": {
      "currency": "UAH",
      "amount": 35.0,
      "valueAddedTaxIncluded": true
    },
    "enquiryPeriod": {
      "startDate": "2017-02-07T11:54:43.132121+02:00",
      "clarificationsUntil": "2017-03-02T11:54:43.387388+02:00",
      "endDate": "2017-02-27T11:54:43.387388+02:00"
    },
    "complaintPeriod": {
      "startDate": "2017-02-07T11:54:43.132121+02:00",
      "endDate": "2017-03-05T00:00:00+02:00"
    },
    "procurementMethodType": "competitiveDialogueUA.stage2",
    "value": {
      "currency": "UAH",
      "amount": 500.0,
      "valueAddedTaxIncluded": true
    },
    "submissionMethod": "electronicAuction",
    "shortlistedFirms": [
      {
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037257",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Test org name 1"
      },
      {
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037257",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Test org name 2"
      },
      {
        "identifier": {
          "scheme": "UA-EDR",
          "id": "00037257",
          "uri": "http://www.dus.gov.ua/"
        },
        "name": "Test org name 3"
      }
    ],
    "date": "2017-02-07T11:54:43.145126+02:00",
    "procuringEntity": {
      "contactPoint": {
        "name": "Державне управління справами",
        "telephone": "0440000000"
      },
      "identifier": {
        "scheme": "UA-EDR",
        "id": "00037256",
        "uri": "http://www.dus.gov.ua/"
      },
      "name": "Державне управління справами",
      "kind": "general",
      "address": {
        "postalCode": "01220",
        "countryName": "Україна",
        "streetAddress": "вул. Банкова, 11, корпус 1",
        "region": "м. Київ",
        "locality": "м. Київ"
      }
    },
    "items": [
      {
        "description": "футляри до державних нагород",
        "classification": {
          "scheme": "CPV",
          "description": "Cartons",
          "id": "44617100-9"
        },
        "description_en": "Cases for state awards",
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "17.21.1",
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ],
        "deliveryAddress": {
          "countryName": "Україна",
          "postalCode": "79000",
          "streetAddress": "вул. Банкова 1",
          "region": "м. Київ",
          "locality": "м. Київ"
        },
        "deliveryDate": {
          "startDate": "2017-02-09T11:54:29.524556+02:00",
          "endDate": "2017-02-12T11:54:29.524556+02:00"
        },
        "id": "9896ef0443f845e1b98445afbbac1574",
        "unit": {
          "code": "44617100-9",
          "name": "item"
        },
        "quantity": 5
      }
    ],
    "owner": "broker3",
    "dateModified": "2017-02-07T11:54:43.455702+02:00",
    "id": "9ae09ba13fb249bd8a06b6c9a464e858",
    "awardCriteria": "lowestCost"
  }
}