Tutorial

Exploring basic rules

Let’s try exploring the /tenders endpoint:

$ http http://api-sandbox.openprocurement.org/api/0/tenders
GET /api/0/tenders HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [],
    "next_page": {
        "offset": "2014-11-08T00:09:27.097664",
        "path": "/api/0/tenders?offset=2014-11-08T00%3A09%3A27.097664",
        "uri": "http://api-sandbox.openprocurement.org/api/0/tenders?offset=2014-11-08T00%3A09%3A27.097664"
    }
}

Just invoking it reveals empty set.

Now let’s attempt creating some tender:

$ http POST http://api-sandbox.openprocurement.org/api/0/tenders
POST /api/0/tenders HTTP/1.1



HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json; charset=UTF-8

{
    "errors": [
        {
            "description": "Content-Type header should be one of ['application/json']",
            "location": "header",
            "name": "Content-Type"
        }
    ],
    "status": "error"
}

Error states that only accepted Content-Type is application/json.

Let’s satisfy the Content-type requirement:

$ http -j POST http://api-sandbox.openprocurement.org/api/0/tenders
POST /api/0/tenders HTTP/1.1
Content-Type: application/json; charset=utf-8



HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=UTF-8

{
    "errors": [
        {
            "description": "No JSON object could be decoded",
            "location": "body",
            "name": "data"
        }
    ],
    "status": "error"
}

Error states that no data found in JSON body.

Creating tender

Let’s provide the data attribute in the body submitted:

$ http -j POST http://api-sandbox.openprocurement.org/api/0/tenders data:={}
POST /api/0/tenders HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "data": {}
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/f66b5a7d00504245b26961bda8d90ba6

{
    "data": {
        "id": "f66b5a7d00504245b26961bda8d90ba6",
        "modified": "2014-11-08T00:09:28.530198",
        "status": "enquiries",
        "tenderID": "UA-f66b5a7d00504245b26961bda8d90ba6"
    }
}

Success! Now we can see that new object was created. Response code is 201 and Location response header reports the location of object created. The body of response reveals the information about tender created, its internal id (that matches the Location segment), its official tenderID and modified datestamp stating the moment in time when tender was last modified. Note that tender is created with enquiries status.

Let’s access the URL of object created (the Location header of the response):

$ http http://api-sandbox.openprocurement.org/api/0/tenders/f66b5a7d00504245b26961bda8d90ba6
GET /api/0/tenders/f66b5a7d00504245b26961bda8d90ba6 HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": {
        "id": "f66b5a7d00504245b26961bda8d90ba6",
        "modified": "2014-11-08T00:09:28.530198",
        "status": "enquiries",
        "tenderID": "UA-f66b5a7d00504245b26961bda8d90ba6"
    }
}

We can see the same response we got after creating tender.

Let’s see what listing of tenders reveals us:

$ http http://api-sandbox.openprocurement.org/api/0/tenders
GET /api/0/tenders HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "id": "f66b5a7d00504245b26961bda8d90ba6",
            "modified": "2014-11-08T00:09:28.530198"
        }
    ],
    "next_page": {
        "offset": "2014-11-08T00:09:29.540811",
        "path": "/api/0/tenders?offset=2014-11-08T00%3A09%3A29.540811",
        "uri": "http://api-sandbox.openprocurement.org/api/0/tenders?offset=2014-11-08T00%3A09%3A29.540811"
    }
}

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

Let’s try creating tender with more data, passing the procuringEntity of a tender:

$ http -j POST http://api-sandbox.openprocurement.org/api/0/tenders data:=@./school-tender.json
POST /api/0/tenders HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "data": {
        "procuringEntity": {
            "address": {
                "countryName": "Україна",
                "locality": "м. Вінниця",
                "postalCode": "21027",
                "region": "м. Вінниця",
                "streetAddress": "вул. Стахурського. 22"
            },
            "id": {
                "name": "Заклад \"Загальноосвітня школа І-ІІІ ступенів № 10 Вінницької міської ради\"",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "21725150",
                "uri": "http://sch10.edu.vn.ua/"
            }
        }
    }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5

{
    "data": {
        "id": "b65397298b2e4d9b987adf576d13b9f5",
        "modified": "2014-11-08T00:09:30.047639",
        "procuringEntity": {
            "address": {
                "countryName": "Україна",
                "locality": "м. Вінниця",
                "postalCode": "21027",
                "region": "м. Вінниця",
                "streetAddress": "вул. Стахурського. 22"
            },
            "id": {
                "name": "Заклад \"Загальноосвітня школа І-ІІІ ступенів № 10 Вінницької міської ради\"",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "21725150",
                "uri": "http://sch10.edu.vn.ua/"
            }
        },
        "status": "enquiries",
        "tenderID": "UA-b65397298b2e4d9b987adf576d13b9f5"
    }
}

And again we have 201 Created response code, Location header and body wth extra id, tenderID, and modified properties.

Let’s check what tender registry contains:

$ http http://api-sandbox.openprocurement.org/api/0/tenders
GET /api/0/tenders HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "id": "f66b5a7d00504245b26961bda8d90ba6",
            "modified": "2014-11-08T00:09:28.530198"
        },
        {
            "id": "b65397298b2e4d9b987adf576d13b9f5",
            "modified": "2014-11-08T00:09:30.047639"
        }
    ],
    "next_page": {
        "offset": "2014-11-08T00:09:30.560672",
        "path": "/api/0/tenders?offset=2014-11-08T00%3A09%3A30.560672",
        "uri": "http://api-sandbox.openprocurement.org/api/0/tenders?offset=2014-11-08T00%3A09%3A30.560672"
    }
}

And indeed we have 2 tenders now.

Modifying tender

Let’s update tender by providing it with all other essential properties:

$ http -j PATCH http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5 data:=@./school-tender-patch.json
PATCH /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "data": {
        "enquiryPeriod": {
            "endDate": "2015-05-29T00:00:00"
        },
        "itemsToBeProcured": [
            {
                "additionalClassification": [
                    {
                        "description": "Послуги шкільних їдалень",
                        "id": "55.51.10.300",
                        "scheme": "ДКПП"
                    }
                ],
                "description": "Послуги шкільних їдалень",
                "primaryClassification": {
                    "description": "Послуги з харчування у школах",
                    "id": "55523100-3",
                    "scheme": "CPV"
                },
                "quantity": 5,
                "unitOfMeasure": "item"
            }
        ],
        "tenderPeriod": {
            "endDate": "2015-06-07T10:00:00",
            "startDate": "2014-11-03T00:00:00"
        },
        "totalValue": {
            "amount": 50000,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": {
        "enquiryPeriod": {
            "endDate": "2015-05-29T00:00:00.000000",
            "startDate": null
        },
        "id": "b65397298b2e4d9b987adf576d13b9f5",
        "itemsToBeProcured": [
            {
                "additionalClassification": [
                    {
                        "description": "Послуги шкільних їдалень",
                        "id": "55.51.10.300",
                        "scheme": "ДКПП",
                        "uri": null
                    }
                ],
                "description": "Послуги шкільних їдалень",
                "primaryClassification": {
                    "description": "Послуги з харчування у школах",
                    "id": "55523100-3",
                    "scheme": "CPV",
                    "uri": null
                },
                "quantity": 5,
                "unitOfMeasure": "item",
                "valuePerUnit": null
            }
        ],
        "modified": "2014-11-08T00:09:31.090792",
        "procuringEntity": {
            "address": {
                "countryName": "Україна",
                "locality": "м. Вінниця",
                "postalCode": "21027",
                "region": "м. Вінниця",
                "streetAddress": "вул. Стахурського. 22"
            },
            "id": {
                "name": "Заклад \"Загальноосвітня школа І-ІІІ ступенів № 10 Вінницької міської ради\"",
                "scheme": "https://ns.openprocurement.org/ua/edrpou",
                "uid": "21725150",
                "uri": "http://sch10.edu.vn.ua/"
            }
        },
        "status": "enquiries",
        "tenderID": "UA-b65397298b2e4d9b987adf576d13b9f5",
        "tenderPeriod": {
            "endDate": "2015-06-07T10:00:00.000000",
            "startDate": "2014-11-03T00:00:00.000000"
        },
        "totalValue": {
            "amount": 50000.0,
            "currency": "UAH",
            "valueAddedTaxIncluded": true
        }
    }
}

We see the added properies merged with existing data of tender. Additionally the modified property updated to reflect the last modification datestamp.

Checking the listing again reflects the new modification date:

$ http http://api-sandbox.openprocurement.org/api/0/tenders
GET /api/0/tenders HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "id": "f66b5a7d00504245b26961bda8d90ba6",
            "modified": "2014-11-08T00:09:28.530198"
        },
        {
            "id": "b65397298b2e4d9b987adf576d13b9f5",
            "modified": "2014-11-08T00:09:31.090792"
        }
    ],
    "next_page": {
        "offset": "2014-11-08T00:09:31.625001",
        "path": "/api/0/tenders?offset=2014-11-08T00%3A09%3A31.625001",
        "uri": "http://api-sandbox.openprocurement.org/api/0/tenders?offset=2014-11-08T00%3A09%3A31.625001"
    }
}

Uploading documentation

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

$ http --form POST http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents file@./Notice.pdf
POST /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents HTTP/1.1
Content-Type: multipart/form-data; boundary=058e8dc505a44d46a498c9a3783a343b



+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/bab5d3c784314800aee9aa7c0b01730c

{
    "data": {
        "datePublished": "2014-11-08T00:09:32.514615",
        "format": "text/plain",
        "id": "bab5d3c784314800aee9aa7c0b01730c",
        "modified": "2014-11-08T00:09:32.514648",
        "title": "Notice.pdf",
        "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/bab5d3c784314800aee9aa7c0b01730c?download=e0061dc88a16413c805aa14f84554dfc"
    }
}

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

$ http http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents
GET /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "datePublished": "2014-11-08T00:09:32.514615",
            "format": "text/plain",
            "id": "bab5d3c784314800aee9aa7c0b01730c",
            "modified": "2014-11-08T00:09:32.514648",
            "title": "Notice.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/bab5d3c784314800aee9aa7c0b01730c?download=e0061dc88a16413c805aa14f84554dfc"
        }
    ]
}

The single array element describes the document uploaded. We can upload more documents:

$ http --form POST http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents file@./AwardCriteria.pdf
POST /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents HTTP/1.1
Content-Type: multipart/form-data; boundary=8370df1c77e8428186db3c0f9985d650



+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12

{
    "data": {
        "datePublished": "2014-11-08T00:09:33.912790",
        "format": "text/plain",
        "id": "9f0828ca0769401bb6965fdf8f363a12",
        "modified": "2014-11-08T00:09:33.912822",
        "title": "AwardCriteria.pdf",
        "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12?download=ded38f8ffd7e4fd0bfbbe33dcaff0e1c"
    }
}

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

$ http http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents
GET /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "datePublished": "2014-11-08T00:09:32.514615",
            "format": "text/plain",
            "id": "bab5d3c784314800aee9aa7c0b01730c",
            "modified": "2014-11-08T00:09:32.514648",
            "title": "Notice.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/bab5d3c784314800aee9aa7c0b01730c?download=e0061dc88a16413c805aa14f84554dfc"
        },
        {
            "datePublished": "2014-11-08T00:09:33.912790",
            "format": "text/plain",
            "id": "9f0828ca0769401bb6965fdf8f363a12",
            "modified": "2014-11-08T00:09:33.912822",
            "title": "AwardCriteria.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12?download=ded38f8ffd7e4fd0bfbbe33dcaff0e1c"
        }
    ]
}

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

$ http --form PUT http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12 file@./AwardCriteria-v2.pdf
PUT /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12 HTTP/1.1
Content-Type: multipart/form-data; boundary=54978b08d4104fa29fc79a6df8340b74



+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": {
        "datePublished": "2014-11-08T00:09:33.912790",
        "format": "text/plain",
        "id": "9f0828ca0769401bb6965fdf8f363a12",
        "modified": "2014-11-08T00:09:35.351952",
        "title": "AwardCriteria-v2.pdf",
        "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12?download=b0769b0c634943f9a1c56df1fee175ed"
    }
}

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

$ http http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents
GET /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "datePublished": "2014-11-08T00:09:32.514615",
            "format": "text/plain",
            "id": "bab5d3c784314800aee9aa7c0b01730c",
            "modified": "2014-11-08T00:09:32.514648",
            "title": "Notice.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/bab5d3c784314800aee9aa7c0b01730c?download=e0061dc88a16413c805aa14f84554dfc"
        },
        {
            "datePublished": "2014-11-08T00:09:33.912790",
            "format": "text/plain",
            "id": "9f0828ca0769401bb6965fdf8f363a12",
            "modified": "2014-11-08T00:09:35.351952",
            "title": "AwardCriteria-v2.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/documents/9f0828ca0769401bb6965fdf8f363a12?download=b0769b0c634943f9a1c56df1fee175ed"
        }
    ]
}

Registering bid

Bidder can register a bid:

$ http -j POST http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders data:={}
POST /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "data": {}
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8

{
    "data": {
        "date": "2014-11-08T00:09:36.418180",
        "id": "8b10e0c38c0747739515b420123d94a8"
    }
}

And upload proposal document:

$ http --form POST http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents file@./Proposal.pdf
POST /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents HTTP/1.1
Content-Type: multipart/form-data; boundary=10cb8f4bbf7240a4a3cf8ff0c5aefd5e



+-----------------------------------------+
| NOTE: binary data not shown in terminal |
+-----------------------------------------+

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents/16a9eab495de4f1ebb747a0804384422

{
    "data": {
        "datePublished": "2014-11-08T00:09:37.274444",
        "format": "text/plain",
        "id": "16a9eab495de4f1ebb747a0804384422",
        "modified": "2014-11-08T00:09:37.274477",
        "title": "Proposal.pdf",
        "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents/16a9eab495de4f1ebb747a0804384422?download=b18c49f26d7b4e5a988f8955552b12fd"
    }
}

It is possible to check documents uploaded:

$ http http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents
GET /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents HTTP/1.1



HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "data": [
        {
            "datePublished": "2014-11-08T00:09:37.274444",
            "format": "text/plain",
            "id": "16a9eab495de4f1ebb747a0804384422",
            "modified": "2014-11-08T00:09:37.274477",
            "title": "Proposal.pdf",
            "url": "http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/bidders/8b10e0c38c0747739515b420123d94a8/documents/16a9eab495de4f1ebb747a0804384422?download=b18c49f26d7b4e5a988f8955552b12fd"
        }
    ]
}

Confirming qualification

Qualification comission registers its decision via following call:

$ http -j POST http://api-sandbox.openprocurement.org/api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/awards data:={"awardStatus":"pending"}
POST /api/0/tenders/b65397298b2e4d9b987adf576d13b9f5/awards HTTP/1.1
Content-Type: application/json; charset=utf-8

{
    "data": {
        "awardStatus": "pending"
    }
}

HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8

{
    "data": {
        "awardDate": "2014-11-08T00:09:38.405176",
        "awardID": "013c5278db3d4ef7a3fa1452cbd0ab69",
        "awardStatus": "pending"
    }
}