Welcome to openregistry.assets.claimrights` documentation!

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

Contents:

Overview

openregistry.assets.claimrights contains the description of the Registry Data Base.

Features

  • claimRights state for the indebtedness to banks which represent credit obligations.
  • Specific structures which are items & debt are included.

Conventions

API accepts JSON or form-encoded content in requests. It returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.

All API POST and PUT requests expect a top-level object with a single element in it named data. Successful responses will mirror this format. The data element should itself be an object, containing the parameters for the request.

If the request was successful, we will get a response code of 201 indicating the object was created. That response will have a data field at its top level, which will contain complete information on the new auction, including its ID.

If something went wrong during the request, we’ll get a different status code and the JSON returned will have an errors field at the top level containing a list of problems. We look at the first one and print out its message.


Project status

The project has pre alpha status.

The source repository for this project is on GitHub: https://github.com/openprocurement/openprocurement.api

API stability

API is relatively stable. The changes in the API are communicated via Open Procurement API maillist.

Change log

0.1

Not Released

  • Set up general build, testing, deployment, and ci framework.
  • Creating/modifying asset

Next steps

You might find it helpful to look at the Tutorial, or the Command Reference.

Data Standard

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

Claim Right

Schema

id:

string, auto-generated, read-only

assetID:

string, auto-generated, read-only

The claim right identifier to refer it to in the paper documentation.

OpenContracting Description: AssetID is included to make the flattened data structure more convenient.

date:

string, auto-generated, read-only

The date of claim right creation/undoing.

dateModified:

string, auto-generated, read-only

OpenContracting Description: Date when claim right was last modified.

mode:

optional

The additional parameter with a value test.

status:

string, required, claimRights Workflow

The claim right status within the Registry.

value:

Value, required

Estimated value of the claim right.

relatedLot:

string, required in active status

ID of the related Lot.

assetType:

string, required

The assetType to be used here is claimRights.

title:

string, multilingual

  • Ukrainian by default (required) - Ukrainian title
  • title_en (English) - English title
  • title_ru (Russian) - Russian title

Oprionally can be mentioned in English/Russian.

description:

string, multilingual, optional

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

  • Ukrainian by default - Ukrainian decription
  • decription_en (English) - English decription
  • decription_ru (Russian) - Russian decription
documents:

OpenContracting Description: All related documents and attachments.

assetCustodian:

Organization, required

The entity managing current claim right.

classification:

Classification, required

The primary classification for claim right.

It is required for classification.scheme to be CAV. The classification.id should be valid CAV code.

additionalClassifications:
 

List of Classification objects, optioanl

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.

The possible additional classifiers are CPVS and koatuu.

unit:

Unit, required

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, required

OpenContracting Description: The number of units required.

location:

dictionary

Geographical coordinates of the location. Element consists of the following items:

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

Item

List of assets specified within the claim right.

debt:

Debt, optional

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

Value

Schema

amount:

float, required

Should be positive.

currency:

string, required

OpenContracting Description: The currency in 3-letter ISO 4217 format.

valueAddedTaxIncluded:
 

bool, required

Debt

Schema

agreementNumber:
 

string

Number of the agreement signed.

dateSigned:

string

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

debtorType:

string

Possible values are naturalPerson and legalPerson.

value:

debtValue

indebtedness, UAH

debtCurrencyValue:
 

debtCurrencyValue

debtValue

Schema

currency:

string

OpenContracting Description: The currency in 3-letter ISO 4217 format.

The only possible value is UAH.

amount:

float

The aggregate amount of indebtedness calculated in UAH.

debtCurrencyValue

Schema

currency:

string

OpenContracting Description: The currency in 3-letter ISO 4217 format.

Debt currency.

amount:

float

The aggregate amount of indebtedness calculated in the currency of debt.

Item

Schema

id:

string, auto-generated

description:

string, multilingual, required

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

Brief description of the claim right.

classification:

Classification

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

It is required for classification.scheme to be CAV. The classification.id should be valid CAV 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.

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:

decimal

OpenContracting Description: The number of units required

address:

Address

Address of location

location:

dictionary

Geographical coordinates of the location. Element consists of the following items:

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

location usually takes precedence over address if both are present.

Organization

Schema

name:

string, multilingual

Name of the organization.

identifier:

Identifier

The primary identifier for this organization.

additionalIdentifiers:
 

List of Identifier objects

address:

Address, required

contactPoint:

ContactPoint, required

Identifier

Schema

scheme:

string

OpenContracting Description: Organization identifiers be drawn from an existing identification scheme. This field is used to indicate the scheme or codelist in which the identifier will be found. This value should be drawn from the Organization Identifier Scheme.

id:

string, required

OpenContracting Description: The identifier of the organization in the selected scheme.

The allowed codes are the ones found in “Organisation Registration Agency” codelist of IATI Standard with addition of UA-EDR code for organizations registered in Ukraine (EDRPOU and IPN).

legalName:

string, multilingual

OpenContracting Description: The legally registered name of the organization.

Full legal name (e.g. Nadra Bank).

uri:

uri

OpenContracting Description: A URI to identify the organization, such as those provided by Open Corporates or some other relevant URI provider. This is not for listing the website of the organization: that can be done through the url field of the Organization contact point.

Address

Schema

streetAddress:

string

OpenContracting Description: The street address. For example, 1600 Amphitheatre Pkwy.

locality:

string

OpenContracting Description: The locality. For example, Mountain View.

region:

string

OpenContracting Description: The region. For example, CA.

postalCode:

string

OpenContracting Description: The postal code. For example, 94043.

countryName:

string, multilingual, required

OpenContracting Description: The country name. For example, United States.

ContactPoint

Schema

name:

string, multilingual, required

OpenContracting Description: The name of the contact person, department, or contact point, for correspondence relating to this contracting process.

email:

email

OpenContracting Description: The e-mail address of the contact point/person.

telephone:

string

OpenContracting Description: The telephone number of the contact point/person. This should include the international dialling code.

faxNumber:

string

OpenContracting Description: The fax number of the contact point/person. This should include the international dialling code.

url:

URL

OpenContracting Description: A web address for the contact point/person.

Either email or telephone field has to be provided.

Document

Schema

id:

string, auto-generated

documentType:

string

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, auto-generated

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

relatedItem:

string

Id of related Lot or Item.

claimRights Workflow

digraph G {
        node [style=filled, color=lightgrey];
        edge[style=dashed];
        "draft" -> "pending";
        edge[style=dashed]
        "pending" -> "deleted";
        edge[style=solid];
        "pending" -> "verification";
        edge[style=solid];
        "verification" -> "pending";
        edge[style=solid];
        "verification" -> "active";
        edge[style=solid];
        "active" -> "pending";
        edge[style=solid];
        "active" -> "complete";
}

Legend

  • dashed line - user action
  • solid line - action is done automatically

Tutorial

Exploring basic rules

Let’s try exploring the claimRights endpoint:

GET /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "next_page": {
    "path": "/api/0.1/assets?offset=", 
    "uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets?offset=", 
    "offset": ""
  }, 
  "data": []
}

Just invoking it reveals empty set.

Now let’s attempt creating some claimRights:

POST /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 4
Content-Type: application/x-www-form-urlencoded
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 415 Unsupported Media Type
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "status": "error", 
  "errors": [
    {
      "description": "Content-Type header should be one of ['application/json']", 
      "location": "header", 
      "name": "Content-Type"
    }
  ]
}

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

Let’s satisfy the Content-type requirement:

POST /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 4
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "status": "error", 
  "errors": [
    {
      "description": "Expecting value: line 1 column 1 (char 0)", 
      "location": "body", 
      "name": "data"
    }
  ]
}

Error states that no data has been found in JSON body.

Creating asset

Let’s create claim right with the minimal (only required) data set:

POST /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 3673
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
  "data": {
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "id": "39513200-3", 
      "description": "Земельні ділянки"
    }, 
    "title": "Земля для космодрому", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "id": "39513200-3", 
          "description": "Cartons"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "countryName": "Україна", 
          "postalCode": "79000", 
          "region": "м. Київ", 
          "streetAddress": "вул. Банкова 1", 
          "locality": "м. Київ"
        }, 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "id": "39513200-3", 
          "description": "Cartons"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "countryName": "Україна", 
          "postalCode": "79000", 
          "region": "м. Київ", 
          "streetAddress": "вул. Банкова 1", 
          "locality": "м. Київ"
        }, 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100
    }, 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "address": {
      "countryName": "Україна", 
      "postalCode": "79000", 
      "region": "м. Київ", 
      "streetAddress": "вул. Банкова 1", 
      "locality": "м. Київ"
    }, 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100
      }, 
      "value": {
        "currency": "UAH", 
        "amount": 1
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "debtorType": "legalPerson"
    }, 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "quantity": 5
  }
}

Response: 201 Created
Content-Type: application/json
Location: http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets/6aa3093c0b00447abefcacf9a11da277
X-Content-Type-Options: nosniff
{
  "access": {
    "token": "431a00c918cd47d48d6f37d62f631c37"
  }, 
  "data": {
    "status": "draft", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000001", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "d778f751485b4bd79f285fc6e8fa90c1", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ada801c8e60b41e3a3164b2ab42aff15", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:03.842028+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:03.835865+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6aa3093c0b00447abefcacf9a11da277", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}
PATCH /api/0.1/assets/6aa3093c0b00447abefcacf9a11da277?acc_token=431a00c918cd47d48d6f37d62f631c37 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 31
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
  "data": {
    "status": "pending"
  }
}

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "pending", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000001", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "d778f751485b4bd79f285fc6e8fa90c1", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ada801c8e60b41e3a3164b2ab42aff15", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:03.936033+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:03.935835+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6aa3093c0b00447abefcacf9a11da277", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

Success! Now we can see that new object was created. Response code is 201 and Location response header reports the location of the created object. The body of response reveals the information about the created claim right: its internal id (that matches the Location segment), its official assetID and dateModified datestamp stating the moment in time when it was last modified. Pay attention to the assetType. Note that the object is created with pending status.

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

GET /api/0.1/assets/6aa3093c0b00447abefcacf9a11da277 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "pending", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000001", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "d778f751485b4bd79f285fc6e8fa90c1", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ada801c8e60b41e3a3164b2ab42aff15", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:03.936033+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:03.935835+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6aa3093c0b00447abefcacf9a11da277", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

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

Let’s see what listing of claim rights reveals us:

GET /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "next_page": {
    "path": "/api/0.1/assets?offset=", 
    "uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets?offset=", 
    "offset": ""
  }, 
  "data": []
}

We do see the internal id of the claim right and its dateModified datestamp.

The previous claim right contained only required fields. Let’s try creating another one with more data (status created):

POST /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 3673
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
  "data": {
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "id": "39513200-3", 
      "description": "Земельні ділянки"
    }, 
    "title": "Земля для космодрому", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "id": "39513200-3", 
          "description": "Cartons"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "countryName": "Україна", 
          "postalCode": "79000", 
          "region": "м. Київ", 
          "streetAddress": "вул. Банкова 1", 
          "locality": "м. Київ"
        }, 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "id": "39513200-3", 
          "description": "Cartons"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "countryName": "Україна", 
          "postalCode": "79000", 
          "region": "м. Київ", 
          "streetAddress": "вул. Банкова 1", 
          "locality": "м. Київ"
        }, 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100
    }, 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "address": {
      "countryName": "Україна", 
      "postalCode": "79000", 
      "region": "м. Київ", 
      "streetAddress": "вул. Банкова 1", 
      "locality": "м. Київ"
    }, 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100
      }, 
      "value": {
        "currency": "UAH", 
        "amount": 1
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "debtorType": "legalPerson"
    }, 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "quantity": 5
  }
}

Response: 201 Created
Content-Type: application/json
Location: http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets/6f32878c0ec44d8e992cf5365fa919ee
X-Content-Type-Options: nosniff
{
  "access": {
    "token": "1bfd7fe16c4d496ea7f780aa35ad53af"
  }, 
  "data": {
    "status": "draft", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000002", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "a290d61cb5304a1cba4ca8652c31d915", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "7bfe30e3c1ce4c53991e2540f6b5845d", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:04.131200+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:04.127806+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6f32878c0ec44d8e992cf5365fa919ee", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

And again we have 201 Created response code, Location header and body with extra id, assetID, and dateModified properties.

Let’s check what asset registry contains:

GET /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "next_page": {
    "path": "/api/0.1/assets?offset=2018-01-09T18%3A31%3A03.936033%2B02%3A00", 
    "uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets?offset=2018-01-09T18%3A31%3A03.936033%2B02%3A00", 
    "offset": "2018-01-09T18:31:03.936033+02:00"
  }, 
  "data": [
    {
      "id": "6aa3093c0b00447abefcacf9a11da277", 
      "dateModified": "2018-01-09T18:31:03.936033+02:00"
    }
  ]
}

And indeed we have 2 objects now.

Modifying Claim Right

Let’s update claim right description:

PATCH /api/0.1/assets/6aa3093c0b00447abefcacf9a11da277?acc_token=431a00c918cd47d48d6f37d62f631c37 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 347
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
  "data": {
    "description": "Земельні ділянки із великими покладами благородних металів"
  }
}

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "pending", 
    "assetType": "claimRights", 
    "description": "Земельні ділянки із великими покладами благородних металів", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000001", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "d778f751485b4bd79f285fc6e8fa90c1", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ada801c8e60b41e3a3164b2ab42aff15", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:04.262976+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:03.935835+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6aa3093c0b00447abefcacf9a11da277", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

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

Checking the listing again reflects the new modification date:

GET /api/0.1/assets?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "next_page": {
    "path": "/api/0.1/assets?offset=2018-01-09T18%3A31%3A03.936033%2B02%3A00", 
    "uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/assets?offset=2018-01-09T18%3A31%3A03.936033%2B02%3A00", 
    "offset": "2018-01-09T18:31:03.936033+02:00"
  }, 
  "data": [
    {
      "id": "6aa3093c0b00447abefcacf9a11da277", 
      "dateModified": "2018-01-09T18:31:03.936033+02:00"
    }
  ]
}

Deleting Claim Right

Let’s delete it:

PATCH /api/0.1/assets/6aa3093c0b00447abefcacf9a11da277?acc_token=431a00c918cd47d48d6f37d62f631c37 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 31
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
  "data": {
    "status": "deleted"
  }
}

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "deleted", 
    "assetType": "claimRights", 
    "description": "Земельні ділянки із великими покладами благородних металів", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000001", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "d778f751485b4bd79f285fc6e8fa90c1", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ada801c8e60b41e3a3164b2ab42aff15", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:04.355377+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:04.355162+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "6aa3093c0b00447abefcacf9a11da277", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

Integration with lots

Assume we attached assets to lot:

GET /api/0.1/assets/68dcee4e1af44aa493c6a040a924c03f HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "active", 
    "relatedLot": "960b16754d55425db2d6d5063b7df083", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000004", 
    "assetType": "claimRights", 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:05.506163+02:00", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "35e00aa638364d06a829a616854dca25", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "8fa1341b52a840539d5093471193adaa", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:05.505967+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "68dcee4e1af44aa493c6a040a924c03f", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

Let`s change lot status to recomposed.

When bot finds such a lot, it turns status of the assets being attached to that lot to pending.

GET /api/0.1/assets/68dcee4e1af44aa493c6a040a924c03f HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "pending", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000004", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "35e00aa638364d06a829a616854dca25", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "8fa1341b52a840539d5093471193adaa", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:05.592916+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:05.592681+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "68dcee4e1af44aa493c6a040a924c03f", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}
GET /api/0.1/assets/b1845029a72a4077aeff912604721ee7 HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "active", 
    "relatedLot": "9939b607995a4c799969c97222957f24", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000003", 
    "assetType": "claimRights", 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:04.788157+02:00", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ecc9f4ec8b524f51a21c2736724f7848", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "5262128ff2d344a9b720227e724840db", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:04.787961+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "b1845029a72a4077aeff912604721ee7", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}
GET /api/0.1/assets/b1845029a72a4077aeff912604721ee7 HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "pending", 
    "assetType": "claimRights", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000003", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ecc9f4ec8b524f51a21c2736724f7848", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "5262128ff2d344a9b720227e724840db", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:04.904205+02:00", 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:04.903875+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "b1845029a72a4077aeff912604721ee7", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}
GET /api/0.1/assets/b1845029a72a4077aeff912604721ee7 HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Host: lb.api-sandbox.registry.ea.openprocurement.net

Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
  "data": {
    "status": "complete", 
    "relatedLot": "b5ca6aa850694154b6a5f6db4e65f5da", 
    "classification": {
      "scheme": "CAV", 
      "description": "Земельні ділянки", 
      "id": "39513200-3"
    }, 
    "title": "Земля для космодрому", 
    "assetID": "UA-AR-DGF-2018-01-09-000003", 
    "assetType": "claimRights", 
    "value": {
      "currency": "UAH", 
      "amount": 100.0, 
      "valueAddedTaxIncluded": true
    }, 
    "dateModified": "2018-01-09T18:31:05.192219+02:00", 
    "items": [
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "ecc9f4ec8b524f51a21c2736724f7848", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }, 
      {
        "description": "футляри до державних нагород", 
        "classification": {
          "scheme": "CAV", 
          "description": "Cartons", 
          "id": "39513200-3"
        }, 
        "additionalClassifications": [
          {
            "scheme": "ДКПП", 
            "id": "17.21.1", 
            "description": "папір і картон гофровані, паперова й картонна тара"
          }
        ], 
        "address": {
          "postalCode": "79000", 
          "countryName": "Україна", 
          "streetAddress": "вул. Банкова 1", 
          "region": "м. Київ", 
          "locality": "м. Київ"
        }, 
        "id": "5262128ff2d344a9b720227e724840db", 
        "unit": {
          "code": "44617100-9", 
          "name": "item"
        }, 
        "quantity": 5
      }
    ], 
    "owner": "broker", 
    "assetCustodian": {
      "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": "м. Київ"
      }
    }, 
    "address": {
      "postalCode": "79000", 
      "countryName": "Україна", 
      "streetAddress": "вул. Банкова 1", 
      "region": "м. Київ", 
      "locality": "м. Київ"
    }, 
    "date": "2018-01-09T18:31:05.191861+02:00", 
    "debt": {
      "agreementNumber": "42", 
      "debtCurrencyValue": {
        "currency": "USD", 
        "amount": 100.0
      }, 
      "dateSigned": "2017-08-16T12:30:17.615196+03:00", 
      "value": {
        "currency": "UAH", 
        "amount": 1.0
      }, 
      "debtorType": "legalPerson"
    }, 
    "id": "b1845029a72a4077aeff912604721ee7", 
    "unit": {
      "code": "39513200-3", 
      "name": "item"
    }, 
    "quantity": 5
  }
}

Authentication

Some of the API requests (especially the ones that are read-only GET requests) do not require any authenication. The other ones, that modify data into the database, require broker authentication via API key. Additionally, owner tokens are issued to facilitate multiple actor roles upon object creation.

API keys

API key is username to use with Basic Authenication scheme.

Owner tokens

Getting token

The token is issued when object is created in the database:

You can see the access with token in response. Its value can be used to modify objects further under “Owner role”.

Using token

You can pass access token in the following ways:

  1. acc_token URL query string parameter
  2. X-Access-Token HTTP request header
  3. access.token in the body of POST/PUT/PATCH request

See the example of the action with token passed as URL query string:

API in cluster mode

There is a cluster of several servers that synchronize data between each other. Client should always work with the same server to ensure consistency between separate requests to the CDB. That is why cookie is required while sending POST/PUT/PATCH/DELETE requests. Cookies provide server stickiness. You can get such cookie via GET request and then use it for POST/PUT/PATCH/DELETE.

If during operations the server requested by cookie went down or is unavailable, client will receive status code 412 of request and new cookie to use. Request should be repeated with new cookie.

Options

In addition to providing fields and their values in a request, you may also specify options to control how your request is interpreted and how the response is generated. For GET requests, options are specified as URL parameters prefixed with opt_. For POST or PUT requests, options are specified in the body, inside the top-level options object (a sibling of the data object). The option specified in the body overrides the opt_ one from URL parameter.

These options can be used in different combinations in a single request, though some of them may conflict in their impact on the response.

pretty:

?opt_pretty

options: { pretty: true }

Provides the response in “pretty” output. In case of JSON this means doing proper line breaking and indentation to make it readable. This will take extra time and increase the response size so it is advisable to use this only during debugging.

jsonp:

?opt_jsonp=myCallback

Returns the output in JSON-P format instead of plain JSON. This allows requests to come from within browsers and work around the “same origin policy.” The function named as the value of the opt_jsonp parameter will be called with a single argument, a JavaScript object representing the response.

fields:

?opt_fields=comma,separated,field,list

List of extra fields to include in response.

Performance recommendations

Rate Control

“Aggressive” IP addresses can be restricted in the speed with which servers are processing CDB requests. In this case CDB will respond with status code 429 to the requests that returned faster than allowed.

Expected client response to such restriction is to repeat requests returned with 429 status code increasing the delay between individual requests sent to the CDB until requests become successful (2xx / 3xx responses).

Such CDB servers behavior is required in order to distribute server resources evenly between clients.

Date Format: ISO 8601

The date format is ISO 8601.

http://imgs.xkcd.com/comics/iso_8601.png

Responses

After processing API always provides response, reporting either success or failure.

Status Codes

In all cases, the API should return an HTTP Status Code that indicates the nature of the failure (see below), with a response body in JSON format containing additional information.

200
Success. If data was requested, it will be available in the data field at the top level of the response body.
201
Success (for object creation). Its information is available in the data field at the top level of the response body. The API URL where the object can be retrieved is also returned in the Location header of the response.
400
Invalid request. This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
401
No authorization. A valid API key was not provided with the request, so the API could not associate a user with the request.
403
Forbidden. The API key and request syntax was valid but the server is refusing to complete the request. This can happen if you are trying to read or write to objects or properties that you do not have access to.
404
Not found. Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
412
Precondition Failed. See API in cluster mode.
429
Rate Limit Enforced. See Rate control.
500
Server error. There was a problem on OpenProcurement’s end.

Success Response

Every successful get, create, update, replace request results in response that contains data attribute. That data attribute contains full JSON object representation after the operation. If some data were generated in the result of processing (like new object IDs, or modified date) they are present in the respose.

The listing requests result in similar responses, but instead of single object in data attribute, the JSON response contains collection of objects.

Example Success Response

Here is a response that describes ....

Error Response

In the event of an error, the response body will contain an errors field at the top level. It contains an array of at least one error object, described below:

location:

Part of the request causing the error. Possible values are header and body.

name:
  • Specific header name that caused the problem (in case of header location)
  • The field name causing the error (in case of body location)
description:

Verbose (human readable) description of the error.

Example Error Response

Sample below indicates incomplete request.

Indices and tables