Welcome to openprocurement.planning.api’s documentation!

Please report any problems or suggestions for improvement either via the mailing list or the issue tracker.

Contents:

Overview

The Open Procurement API is the only interface to Open Procurement database that is core unit of Open Procurement infrastructure.

This documentation covers procurement plan.

Procurement plan

Після затвердження бюджету/фінансового плану організації, ця інформація заноситься в систему у вигляді структурованої інформації. Річний план закупівель деталізується до п’ятого знаку класифікатора ДК 016:2010, третього знаку ДК 021:2015 та коду КЕКВ (якщо закупівля здійснюється за кошти державного бюджету). Поступово ця інформація деталізується Змовником через внесення змін до річного плану, у яких зазначається місяць початку процедури і предмет закупівлі.

На основі змін до річного плану, Замовник може створювати оголошення закупівлі у статусі “Планується” із детальним описом предмету закупівлі, технічних умов і кваліфікаційних критеріїв. Цей пункт є не обов’язковим і використовуватиметься замовниками за бажанням.

Для внесення річного плану і змін до нього Замовник може використовувати будь-який Майданчик, приєднаний до системи Prozorro і авторизований для обслуговування замовників.

Tutorial

Plan creation

Creating plan procurement

Let’s create a plan:

POST /api/2.3/plans?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 2454
Content-Type: application/json
Host: api-sandbox.openprocurement.org

{
  "data": {
    "classification": {
      "scheme": "ДК021",
      "description": "Seeds",
      "id": "03111000-2"
    },
    "items": [
      {
        "description": "Насіння гірчиці",
        "classification": {
          "scheme": "ДК021",
          "description": "Mustard seeds",
          "id": "03111600-8"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.92",
            "description": "Насіння гірчиці"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-06T17:41:39.677983"
        },
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 1000
      },
      {
        "description": "Насіння соняшнику",
        "classification": {
          "scheme": "ДК021",
          "description": "Sunflower seeds",
          "id": "03111300-5"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.95",
            "description": "Насіння соняшнику"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-07T17:41:39.677983"
        },
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 2000
      },
      {
        "description": "Насіння бавовнику",
        "classification": {
          "scheme": "ДК021",
          "description": "Cotton seeds",
          "id": "03111400-6"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.84",
            "description": "Насіння бавовнику"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-08T17:41:39.677983"
        },
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 3000
      }
    ],
    "budget": {
      "amountNet": 12222,
      "description": "budget_description",
      "project": {
        "name": "proj_name",
        "id": "123"
      },
      "currency": "UAH",
      "amount": 10000,
      "id": "12303111000-2"
    },
    "additionalClassifications": [
      {
        "scheme": "КЕКВ",
        "id": "1",
        "description": "-"
      }
    ],
    "procuringEntity": {
      "identifier": {
        "scheme": "UA-EDR",
        "id": "111983",
        "legalName": "ДП Державне Управління Справами"
      },
      "name": "ДУС"
    },
    "tender": {
      "procurementMethod": "open",
      "procurementMethodType": "belowThreshold",
      "tenderPeriod": {
        "startDate": "2017-06-28T17:41:39.677983"
      }
    }
  }
}

Response: 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://api-sandbox.openprocurement.org/api/2.3/plans/52862ec099ff4debbf9f26a0980f27f3
{
  "access": {
    "token": "fc9c0f555bf24dffa2b855ed618bc81c"
  },
  "data": {
    "classification": {
      "scheme": "ДК021",
      "description": "Seeds",
      "id": "03111000-2"
    },
    "items": [
      {
        "description": "Насіння гірчиці",
        "classification": {
          "scheme": "ДК021",
          "description": "Mustard seeds",
          "id": "03111600-8"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.92",
            "description": "Насіння гірчиці"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-06T17:41:39.677983+03:00"
        },
        "id": "f8173e5bf8754aec89a47a624b3cefd1",
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 1000
      },
      {
        "description": "Насіння соняшнику",
        "classification": {
          "scheme": "ДК021",
          "description": "Sunflower seeds",
          "id": "03111300-5"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.95",
            "description": "Насіння соняшнику"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-07T17:41:39.677983+03:00"
        },
        "id": "3b0208637aa44a99b388a9b540533a1c",
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 2000
      },
      {
        "description": "Насіння бавовнику",
        "classification": {
          "scheme": "ДК021",
          "description": "Cotton seeds",
          "id": "03111400-6"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.11.84",
            "description": "Насіння бавовнику"
          }
        ],
        "deliveryDate": {
          "endDate": "2017-07-08T17:41:39.677983+03:00"
        },
        "id": "7266c3c7b95246718021ab671207335e",
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 3000
      }
    ],
    "planID": "UA-P-2017-06-21-000001",
    "budget": {
      "amountNet": 12222.0,
      "description": "budget_description",
      "project": {
        "id": "123",
        "name": "proj_name"
      },
      "currency": "UAH",
      "amount": 10000.0,
      "id": "12303111000-2"
    },
    "datePublished": "2017-06-21T17:41:40.564867+03:00",
    "tender": {
      "procurementMethod": "open",
      "procurementMethodType": "belowThreshold",
      "tenderPeriod": {
        "startDate": "2017-06-28T17:41:39.677983+03:00"
      }
    },
    "additionalClassifications": [
      {
        "scheme": "КЕКВ",
        "id": "1",
        "description": "-"
      }
    ],
    "procuringEntity": {
      "identifier": {
        "scheme": "UA-EDR",
        "id": "111983",
        "legalName": "ДП Державне Управління Справами"
      },
      "name": "ДУС"
    },
    "owner": "broker",
    "dateModified": "2017-06-21T17:41:40.588719+03:00",
    "id": "52862ec099ff4debbf9f26a0980f27f3"
  }
}

We have 201 Created response code, Location header and body with extra id, planID, and dateModified properties.

Let’s check what plan registry contains:

GET /api/2.3/plans HTTP/1.0
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "next_page": {
    "path": "/api/2.3/plans?offset=",
    "uri": "http://api-sandbox.openprocurement.org/api/2.3/plans?offset=",
    "offset": ""
  },
  "data": []
}

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

Modifying plan

Let’s update plan by supplementing it with all other essential properties:

PATCH /api/2.3/plans/52862ec099ff4debbf9f26a0980f27f3?acc_token=fc9c0f555bf24dffa2b855ed618bc81c HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 652
Content-Type: application/json
Host: api-sandbox.openprocurement.org

{
  "data": {
    "items": [
      {
        "description": "Насіння овочевих культур",
        "classification": {
          "scheme": "ДК021",
          "description": "Vegetable seeds",
          "id": "03111700-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.13.6",
            "description": "Насіння овочевих культур"
          }
        ],
        "deliveryDate": {
          "endDate": "2016-06-01T23:06:30.023018+03:00"
        },
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 5000
      }
    ]
  }
}

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "data": {
    "classification": {
      "scheme": "ДК021",
      "description": "Seeds",
      "id": "03111000-2"
    },
    "items": [
      {
        "description": "Насіння овочевих культур",
        "classification": {
          "scheme": "ДК021",
          "description": "Vegetable seeds",
          "id": "03111700-9"
        },
        "additionalClassifications": [
          {
            "scheme": "ДКПП",
            "id": "01.13.6",
            "description": "Насіння овочевих культур"
          }
        ],
        "deliveryDate": {
          "endDate": "2016-06-01T23:06:30.023018+03:00"
        },
        "id": "f8173e5bf8754aec89a47a624b3cefd1",
        "unit": {
          "code": "KGM",
          "name": "кг"
        },
        "quantity": 5000
      }
    ],
    "planID": "UA-P-2017-06-21-000001",
    "budget": {
      "amountNet": 12222.0,
      "description": "budget_description",
      "project": {
        "id": "123",
        "name": "proj_name"
      },
      "currency": "UAH",
      "amount": 10000.0,
      "id": "12303111000-2"
    },
    "datePublished": "2017-06-21T17:41:40.564867+03:00",
    "tender": {
      "procurementMethod": "open",
      "procurementMethodType": "belowThreshold",
      "tenderPeriod": {
        "startDate": "2017-06-28T17:41:39.677983+03:00"
      }
    },
    "additionalClassifications": [
      {
        "scheme": "КЕКВ",
        "id": "1",
        "description": "-"
      }
    ],
    "procuringEntity": {
      "identifier": {
        "scheme": "UA-EDR",
        "id": "111983",
        "legalName": "ДП Державне Управління Справами"
      },
      "name": "ДУС"
    },
    "owner": "broker",
    "dateModified": "2017-06-21T17:41:40.747307+03:00",
    "id": "52862ec099ff4debbf9f26a0980f27f3"
  }
}

We see the added properies have merged with existing plan data. Additionally, the dateModified property was updated to reflect the last modification datestamp.

Checking the listing again reflects the new modification date:

GET /api/2.3/plans HTTP/1.0
Host: api-sandbox.openprocurement.org

Response: 200 OK
Content-Type: application/json; charset=UTF-8
{
  "next_page": {
    "path": "/api/2.3/plans?offset=2017-06-21T17%3A41%3A40.588719%2B03%3A00",
    "uri": "http://api-sandbox.openprocurement.org/api/2.3/plans?offset=2017-06-21T17%3A41%3A40.588719%2B03%3A00",
    "offset": "2017-06-21T17:41:40.588719+03:00"
  },
  "data": [
    {
      "id": "52862ec099ff4debbf9f26a0980f27f3",
      "dateModified": "2017-06-21T17:41:40.588719+03:00"
    }
  ]
}

Data Standard

Data standard is modelled along the Open Contracting Standard with extensions in areas that were not covered by it.

Contract

Schema

id:

uid, auto-generated

OpenContracting Description: The identifier for this contract.
awardID:

string, required

OpenContracting Description: The Award.id against which this contract is being issued.
contractID:

string, auto-generated, read-only
title:

string, required

OpenContracting Description: Contract title
description:

string

OpenContracting Description: Contract description
items:

List of Item objects, auto-generated, read-only

OpenContracting Description: The goods, services, and any intangible outcomes in this contract. Note: If the items are the same as the award do not repeat.
suppliers:

List of Organization objects, auto-generated, read-only
status:

string, required

OpenContracting Description: The current status of the contract.

Possible values are:

  • pending - this contract has been proposed, but is not yet in force. It may be awaiting signature.
  • active - this contract has been signed by all the parties, and is now legally in force.
  • cancelled - this contract has been cancelled prior to being signed.
  • terminated - this contract was signed and in force, and has now come to a close. This may be due to a successful completion of the contract, or may be early termination due to some non-completion issue.
period:

Period

OpenContracting Description: The start and end date for the contract.
value:

Value object, auto-generated, read-only

OpenContracting Description: The total value of this contract.
dateSigned:

string, Date, auto-generated

OpenContracting Description: The date the contract was signed. In the case of multiple signatures, the date of the last signature.
documents:

List of Document objects

OpenContracting Description: All documents and attachments related to the contract, including any notices.

Contract workflow

digraph G { A [ label="pending*" ] B [ label="active"] C [ label="cancelled"] A -> B; A -> C; }

* marks initial state

Item

Schema

id:

string, auto-generated
description:

string, multilingual, required

OpenContracting Description: A description of the goods, services to be provided.
classification:

Classification

OpenContracting Description: The primary classification for the item. See the itemClassificationScheme to identify preferred classification lists, including CPV and GSIN.

It is mandatory for classification.scheme to be CPV. The classification.id should be valid CPV code.
additionalClassifications:
 

List of Classification objects

OpenContracting Description: An array of additional classifications for the item. See the itemClassificationScheme codelist for common options to use in OCDS. This may also be used to present codes from an internal classification scheme.

It is mandatory to have at least one item with ДКПП as scheme.
unit:

Unit

OpenContracting Description: Description of the unit which the good comes in e.g. hours, kilograms. Made up of a unit name, and the value of a single unit.
quantity:

integer

OpenContracting Description: The number of units required
deliveryDate:

Period

Period during which the item should be delivered.
deliveryAddress:
 

Address

Address, where the item should be delivered.
deliveryLocation:
 

dictionary

Geographical coordinates of delivery location. Element consist of the following items:

latitude:string, required
longitude:string, required
elevation:string, optional, usually not used

deliveryLocation usually takes precedence over deliveryAddress if both are present.
relatedLot:

string

Id of related Lot.

Classification

Schema

scheme:

string

OpenContracting Description: A classification should be drawn from an existing scheme or list of codes. This field is used to indicate the scheme/codelist from which the classification is drawn. For line item classifications, this value should represent a known Item Classification Scheme wherever possible.
id:

string

OpenContracting Description: The classification code drawn from the selected scheme.
description:

string

OpenContracting Description: A textual description or title for the code.
uri:

uri

OpenContracting Description: A URI to identify the code. In the event individual URIs are not available for items in the identifier scheme this value should be left blank.

Unit

Schema

code:

string, required

UN/CEFACT Recommendation 20 unit code.
name:

string

OpenContracting Description: Name of the unit

Document

Schema

id:

string, autogenerated
documentType:

string

Possible values for Tender

  • notice - Tender notice

    The formal notice that gives details of a tender. This may be a link to a downloadable document, to a web page, or to an official gazette in which the notice is contained.

  • technicalSpecifications - Technical Specifications

    Detailed technical information about goods or services to be provided.

  • shortlistedFirms - Shortlisted Firms

  • riskProvisions - Provisions for management of risks and liabilities

  • billOfQuantity - Bill Of Quantity

  • conflictOfInterest - Conflicts of interest uncovered

  • debarments - Debarments issued

Possible values for Award

  • notice - Award Notice

    The formal notice that gives details of the contract award. This may be a link to a downloadable document, to a web page, or to an official gazette in which the notice is contained.

  • evaluationReports - Evaluation report

    Report on the evaluation of the proposals and the application of the evaluation criteria, including the justification fo the award.

  • complaints - Complaints and decisions

Possible values for Contract

  • notice - Contract notice

    The formal notice that gives details of a contract being signed and valid to start implementation. This may be a link to a downloadable document, to a web page, or to an official gazette in which the notice is contained.

  • contractSigned - Signed Contract

  • contractArrangements - Arrangements for ending contract

  • contractSchedule - Schedules and milestones

  • contractAnnexe - Annexes to the Contract

  • contractGuarantees - Guarantees

  • subContract - Subcontracts
title:

string, multilingual

OpenContracting Description: The document title.
description:

string, multilingual

OpenContracting Description: A short description of the document. In the event the document is not accessible online, the description field can be used to describe arrangements for obtaining a copy of the document.
format:

string

OpenContracting Description: The format of the document taken from the IANA Media Types code list, with the addition of one extra value for ‘offline/print’, used when this document entry is being used to describe the offline publication of a document.
url:

string, autogenerated

OpenContracting Description: Direct link to the document or attachment.
datePublished:

string, Date

OpenContracting Description: The date on which the document was first published.
dateModified:

string, Date

OpenContracting Description: Date that the document was last modified
language:

string

OpenContracting Description: Specifies the language of the linked document using either two-digit ISO 639-1, or extended BCP47 language tags.
documentOf:

string

Possible values are:

  • tender
  • item
  • lot
relatedItem:

string

Id of related Lot or Item.

Tender

Schema

title:

string, multilingual

The name of the tender, displayed in listings. You can include the following items:

  • tender code (in procuring organization management system)
  • periodicity of the tender (annual, quarterly, etc.)
  • item being procured
  • some other info
description:

string, multilingual

Detailed description of tender.
tenderID:

string, auto-generated, read-only

The tender identifier to refer tender to in “paper” documentation.

OpenContracting Description: TenderID should always be the same as the OCID. It is included to make the flattened data structure more convenient.
procuringEntity:
 

Organization, required

Organization conducting the tender.

OpenContracting Description: The entity managing the procurement, which may be different from the buyer who is paying / using the items being procured.
value:

Value, required

Total available tender budget.

OpenContracting Description: The total estimated value of the procurement.
items:

list of Item objects, required

List that contains single item being procured.

OpenContracting Description: The goods and services to be purchased, broken into line items wherever possible. Items should not be duplicated, but a quantity of 2 specified instead.
documents:

List of Document objects

OpenContracting Description: All documents and attachments related to the tender.
awards:

List of Award objects

All qualifications (disqualifications and awards).
contracts:

List of Contract objects

OpenContracting Description: The date or period on which an award is anticipated to be made.
status:

string

active:Active tender (default)
complete:Completed tender
cancelled:Cancelled tender
unsuccessful:Unsuccessful tender

Status of the Tender.
cancellations:

List of Cancellation objects.

Contains 1 object with active status in case of cancelled Tender.

The Cancellation object describes the reason of tender cancellation contains accompanying documents if any.
procurementMethod:
 

string, auto-generated

limited:Default.

Procurement Method of the Tender.
procurementMethodRationale:
 

string, multilingual

Procurement Method Rationale of tender.
procurementMethodType:
 

string

reporting:reporting procedure indentifier
negotiation:negotiation procedure indentifier
negotiation.quick:
 negotiation.quick procedure indentifier
dateModified:

string, Date
owner:

string, auto-generated

Tender workflow

digraph G { A [ label="active*" ] B [ label="complete"] C [ label="cancelled"] A -> B; A -> C; }

* marks initial state

API Reference

Indices and tables