Вітаємо на сайті документації по openregistry.lots.basic!¶
Будь ласка повідомляйте про всі проблеми та поради покращень або через розсилку, або issue tracker.
Зміст:
Огляд¶
openregistry.lots.basic містить документацію з описом роботи з базою даних реєстру активів (RDB).
Особливості¶
ФГВФО має право на формування лотів.
Лот може містити один або декілька asset’ів
Декілька asset’ів, що, поєднуючись, формують лот, позначаються прикріпленими до цього лоту.
При створенні нового лоту, у випадку, якщо хоч один з assets вже прикріплений до іншого лоту, то поточний лот позначається як невалідний.
Якщо лот успішно створений, він стає доступний для виставлення на торги.
Домовленості¶
API приймає JSON або form-encoded вміст у запитах. Він повертає JSON вміст у всіх свої відповідях, включно з помилками. Підтримується лише UTF-8 кодування і для запитів, і для відповідей.
Всі API POST та PUT запити очікують об’єкт верхнього рівня з єдиним елементом з назвою data. Відповіді з повідомленням про успіх будуть віддзеркалювати цей формат. Елемент data повинен сам бути об’єктом, що містить параметри запиту.
Якщо запит був успішним, ми отримаємо код відповіді 201, який вказує, що об’єкт був створений. Ця відповідь буде мати data поле на верхньому рівні, яке вміщуватиме повну інформацію про новий лот, включно з ID.
Якщо під час запиту виникли труднощі, ми отримаємо інший код стану та JSON, який при поверненні міститиме errors поле на верхньому рівні зі списком проблем. Ми дивимось на першу з них і видруковуємо її повідомлення.
Стан проекту¶
Статус цього проекту - пре альфа.
Репозиторій джерельних текстів цього проекту є на GitHub: https://github.com/openprocurement/openregistry.api
Стабільність API¶
API є відносно стабільним. Зміни в API обговорюються через Open Procurement API розсилку.
Стандарт даних¶
Стандарт даних змодельований згідно Open Contracting Standard з розширеннями в тих областях, які він не покриває.
Basic Lot¶
Схема¶
| id: | рядок, автогенерований, лише для читання |
|---|---|
| lotID: | рядок, автогенерований, лише для читання Ідентифікатор лоту, наявний для того, аби знайти його у паперовій документації. OpenContracting Description: LotID включають, щоб зробити структуру даних більш зручною та читабельною. |
| date: | рядок, автогенерований, лише для читання Дата створення/знищення лоту. |
| dateModified: | рядок, автогенерований, лише для читання OpenContracting Description: Дата внесення останніх змін до лоту. |
| status: | рядок, обов’язковий Статус лоту в реєстрі. |
| value: | Value, обов’язково Оціночна вартість. |
| assets: | рядок, не обов’язковий Ідентифікатор активу, який приркріплений до лоту. |
| lotType: | рядок, обов’язковий Тип лоту. |
| title: | рядок, багатомовний
Вказання йменування англійською/російською не обов’язкове. |
| description: | рядок, багатомовний, не обов’язково OpenContracting Description: Опис товарів та послуг, які повинні бути надані.
|
| documents: | OpenContracting Description: Пов’язані з лотом документи та додатки. |
| lotCustodian: | Organization, обов’язково Розпорядник лоту. |
| mode: | не обов’язково Додатковий параметр, що вказує на тестовий режим. |
Value¶
Схема¶
| amount: | float, обов’язково Повинно бути додатним. |
|---|---|
| currency: | рядок, обов’язковий OpenContracting Description: Валюта у трибуквенному форматі ISO 4217. |
| valueAddedTaxIncluded: | |
булеве значення, обов’язково |
|
Organization¶
Схема¶
| name: | рядок, багатомовний Назва організації. |
|---|---|
| identifier: |
Ідентифікатор цієї організації. |
| additionalIdentifiers: | |
Список об’єктів Identifier |
|
| address: | Address, обов’язково |
| contactPoint: | ContactPoint, обов’язково |
Identifier¶
Схема¶
| scheme: | рядок OpenContracting Description: Ідентифікатори організації беруться з існуючої схеми ідентифікації. Це поле вказує схему або список кодів, де можна знайти ідентифікатор організації. Це значення повинно братись зі Схеми Ідентифікації Організацій. |
|---|---|
| id: | рядок, обов’язковий OpenContracting Description: Ідентифікатор організації у вибраній схемі. Дозволеними є коди зі спику кодів “Organisation Registration Agency” Стандарту IATI з додаванням коду UA-EDR для організацій, зареєстрованих в Україні (ЄДРПОУ та ІПН). |
| legalName: | рядок, багатомовний OpenContracting Description: Легально зареєстрована назва організації. Повна юридична назва (наприклад - “Надра Банк”). |
| uri: | uri OpenContracting Description: URI для ідентифікації організації, наприклад, ті, які надають Open Corporates або інші постачальники URI. Це не для вебсайту організації, його можна надати в полі url в ContactPoint організації. |
Address¶
Схема¶
| streetAddress: | рядок OpenContracting Description: Вулиця. Наприклад, вул.Хрещатик, 22. |
|---|---|
| locality: | рядок OpenContracting Description: Населений пункт. Наприклад, Київ. |
| region: | рядок OpenContracting Description: Область. Наприклад, Київська. |
| postalCode: | рядок OpenContracting Description: Поштовий індекс, Наприклад, 78043. |
| countryName: | рядок, багатомовний, обов’язковий OpenContracting Description: Назва країни. Наприклад, Україна. |
ContactPoint¶
Схема¶
| name: | рядок, багатомовний, обов’язковий OpenContracting Description: Ім’я контактної особи, назва відділу чи контактного пункту для листування, що стосується цього процесу укладання договору. |
|---|---|
| email: | OpenContracting Description: Адреса електронної пошти контактної особи/пункту. |
| telephone: | рядок OpenContracting Description: Номер телефону контактної особи/пункту. Повинен включати міжнародний телефонний код. |
| faxNumber: | рядок OpenContracting Description: Номер факсу контактної особи/пункту. Повинен включати міжнародний телефонний код. |
| url: | URL-адреса OpenContracting Description: Веб адреса контактної особи/пункту. |
Повинне бути заповнене хоча б одне з полів: або email, або telephone.
Схема роботи лотів¶
![digraph G {
subgraph cluster_1 {
node [style=filled, fillcolor=seashell2];
edge[style=dashed, arrowhead="vee"];
"draft" -> "pending" [color="0.0000 0.0000 0.3882"];
edge[style=dashed, arrowhead="vee"];
"pending" -> "verification" [color="0.0000 0.0000 0.3882"];
edge[style=solid, arrowhead="vee"];
"verification" -> "pending" [color="0.6667 1.0000 0.5020"];
"verification" -> "active.salable" [color="0.6667 1.0000 0.5020"];
edge[dir="both"];
"active.salable" -> "active.awaiting" [color="0.6667 1.0000 0.5020"];
edge[dir="forward"];
"active.awaiting" -> "active.auction" [color="0.6667 1.0000 0.5020"];
edge[dir="forward"];
"active.auction" -> "pending.sold" [color="0.6667 1.0000 0.5020"];
edge[dir="forward"];
"pending.sold" -> "sold" [color="0.6667 1.0000 0.5020"];
color=white;
}
subgraph cluster_1 {
node [style=dashed];
edge[style=dashed, dir="forward"];
"active.salable" -> "recomposed" [color="0.0000 0.0000 0.3882"];
edge[style=solid, dir="forward"];
"recomposed" -> "pending" [color="0.6667 1.0000 0.5020"];
}
edge[style=dashed, arrowhead="vee"]
"pending" -> "deleted" [color="0.0000 0.0000 0.3882"];
edge[style=solid];
node [style=dashed];
edge[style=dashed];
"active.salable" -> "pending.dissolution" [color="0.0000 0.0000 0.3882"];
edge[style=solid];
node [style=solid];
"pending.dissolution" -> "dissolved" [color="0.6667 1.0000 0.5020"];
}](_images/graphviz-c4e074eebff5b0eef6052ab5f982261670497ece.png)
Умовні Позначення¶
Пунктирні лінії - дії користувача
Суцільні лінії - автоматичні дії
Туторіал¶
Базові правила¶
Подивимось як працює точка входу /lots:
GET /api/0.1/lots?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/lots?offset=",
"uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots?offset=",
"offset": ""
},
"data": []
}
При виклику видає пустий набір.
Спробуймо створити новий лот
POST /api/0.1/lots?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"
}
]
}
Помилка вказує, що єдиний прийнятний тип вмісту це application/json.
Задовільнимо вимогу типу вмісту:
POST /api/0.1/lots?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"
}
]
}
Помилка вказує, що data не знайдено у тілі JSON.
Створення лоту¶
Створимо лот з мінімально допустимим набором даних (тільки параметри обовязкові для заповнення) :
POST /api/0.1/lots?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 1104
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"lotIdentifier": "Q81318b19827",
"lotCustodian": {
"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": "м. Київ"
}
},
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
],
"title": "Тестовий лот",
"lotType": "basic",
"description": "Щось там тестове"
}
}
Response: 201 Created
Content-Type: application/json
Location: http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots/f0c5e8decc17498cabe79808ee889cc3
X-Content-Type-Options: nosniff
{
"access": {
"token": "5b2eae27ea3a41cfa4197fab969a0859"
},
"data": {
"status": "draft",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000001",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.426524+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.424179+02:00",
"id": "f0c5e8decc17498cabe79808ee889cc3",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
PATCH /api/0.1/lots/f0c5e8decc17498cabe79808ee889cc3?acc_token=5b2eae27ea3a41cfa4197fab969a0859 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",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000001",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.473538+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.473361+02:00",
"id": "f0c5e8decc17498cabe79808ee889cc3",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
PATCH /api/0.1/lots/f0c5e8decc17498cabe79808ee889cc3?acc_token=5b2eae27ea3a41cfa4197fab969a0859 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 36
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"status": "verification"
}
}
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "verification",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000001",
"description": "Змінений опис тестового лоту",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.566111+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.565938+02:00",
"id": "f0c5e8decc17498cabe79808ee889cc3",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
Успіх! Тепер ми бачимо, що новий об’єкт було створено. Код відповіді 201 та заголовок відповіді Location вказує місцерозташування створеного об’єкта. Тіло відповіді показує інформацію про створений лот, його внутрішнє id (яке співпадає з сегментом Location), його офіційне lotID та dateModified дату, що показує час, коли лот востаннє модифікувався. Зверніть увагу на те, що лот створений в статусі verification.
Використаємо URL створеного об’єкта (заголовок відповіді Location):
Ми бачимо ту ж відповідь, що і після створення лоту.
GET /api/0.1/lots?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/lots?offset=2018-01-15T15%3A33%3A03.512434%2B02%3A00",
"uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots?offset=2018-01-15T15%3A33%3A03.512434%2B02%3A00",
"offset": "2018-01-15T15:33:03.512434+02:00"
},
"data": [
{
"id": "f0c5e8decc17498cabe79808ee889cc3",
"dateModified": "2018-01-15T15:33:03.512434+02:00"
}
]
}
Подивимось, що показує список лотів:
Ми бачимо внутрішнє id лоту (що може бути використано для побудови повної URL-адреси, якщо додати https://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots/ та його dateModified дату.
Попередній лот був створений лише з обов’язковими полями. Тепер додамо лот з максимально допустимим набором даних при створенні (лот повинен бути у статусі ‘created’):
POST /api/0.1/lots?opt_pretty=1 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 1104
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"lotIdentifier": "Q81318b19827",
"lotCustodian": {
"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": "м. Київ"
}
},
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
],
"title": "Тестовий лот",
"lotType": "basic",
"description": "Щось там тестове"
}
}
Response: 201 Created
Content-Type: application/json
Location: http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots/462705149c174132b41d723ac081a816
X-Content-Type-Options: nosniff
{
"access": {
"token": "f48bb882fb7e49e9b629053657581259"
},
"data": {
"status": "draft",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000002",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.614369+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.612730+02:00",
"id": "462705149c174132b41d723ac081a816",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
PATCH /api/0.1/lots/462705149c174132b41d723ac081a816?acc_token=f48bb882fb7e49e9b629053657581259 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",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000002",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.644639+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.644468+02:00",
"id": "462705149c174132b41d723ac081a816",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
PATCH /api/0.1/lots/df82d57c54b84ff6a78bdc9a727859f6?acc_token=61630dbc933a42bc84ada62b3c712ce7 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 43
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"status": "pending.dissolution"
}
}
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "pending.dissolution",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000003",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.148178+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.148017+02:00",
"id": "df82d57c54b84ff6a78bdc9a727859f6",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
І знову код відповіді 201 Created, заголовок Location і тіло з додатковим id, lotID та властивість dateModified.
Перевіримо, що містить реєстр:
GET /api/0.1/lots?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/lots?offset=2018-01-15T15%3A33%3A03.566111%2B02%3A00",
"uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots?offset=2018-01-15T15%3A33%3A03.566111%2B02%3A00",
"offset": "2018-01-15T15:33:03.566111+02:00"
},
"data": [
{
"id": "f0c5e8decc17498cabe79808ee889cc3",
"dateModified": "2018-01-15T15:33:03.566111+02:00"
}
]
}
Дійсно, в нас зараз є два лоти.
У разі, якщо зміни потрбіно внести у вже сформований лот (статус active.salable), Ліквідатору необхідно перевести статус цього лоту в recomposed
PATCH /api/0.1/lots/34b371dc3b8f47a0869a8cac45be1181?acc_token=9791acb0d26647c48dd0a2570b7b53e3 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 34
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"status": "recomposed"
}
}
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "recomposed",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000005",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.952634+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.952462+02:00",
"id": "34b371dc3b8f47a0869a8cac45be1181",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
Опісля, його статус автоматично буде змінений на pending.
Модифікація лоту¶
Оновимо лот шляхом надання йому усіх інших важливих властивостей:
PATCH /api/0.1/lots/f0c5e8decc17498cabe79808ee889cc3?acc_token=5b2eae27ea3a41cfa4197fab969a0859 HTTP/1.0
Authorization: Basic YnJva2VyOg==
Content-Length: 182
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",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000001",
"description": "Змінений опис тестового лоту",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:03.512434+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:03.473361+02:00",
"id": "f0c5e8decc17498cabe79808ee889cc3",
"assets": [
"b49f767133cb4d0bbcfd9c404ece8b01"
]
}
}
Ми бачимо, що додаткові властивості об’єднані з існуючими даними лоту. Додатково оновлена властивість dateModified, щоб відображати останню дату модифікації.
Ще одна перевірка списку відображає нову дату модифікації:
GET /api/0.1/lots?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/lots?offset=",
"uri": "http://lb.api-sandbox.registry.ea.openprocurement.net/api/0.1/lots?offset=",
"offset": ""
},
"data": []
}
Видалення лоту¶
Видалимо лот
Інтеграція з активами¶
Зв’язок реєстру лотів з реєстром активів¶
Для того, аби сформувати лот, необхідно вказати id активів, які Ви хочете прикріпити до лоту. Якщо всі вказані Вами активи доступні, статус лоту зміниться на active.salable:
GET /api/0.1/lots/df82d57c54b84ff6a78bdc9a727859f6 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.salable",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000003",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.100775+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.100596+02:00",
"id": "df82d57c54b84ff6a78bdc9a727859f6",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
У випадку, якщо хоча б один із зазначених активів виявився недоступним (напр. цей актив вже прикріплений до іншого лоту), статус поточного лоту буде змінено на pending:
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 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",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.333455+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.333259+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
У разі, якщо лот перебуває у статусі pending.dissolution, бот відкріплює причеплені до цього лоту активи, відтак їхні статуси змінюються на pending. Статус самого лоту автоматично стає dissolved.
PATCH /api/0.1/lots/df82d57c54b84ff6a78bdc9a727859f6 HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
Content-Length: 33
Content-Type: application/json
Host: lb.api-sandbox.registry.ea.openprocurement.net
DATA:
{
"data": {
"status": "dissolved"
}
}
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "dissolved",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000003",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.184140+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.183968+02:00",
"id": "df82d57c54b84ff6a78bdc9a727859f6",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
У разі, якщо лот перебуває у статусі recomposed, бот відкріплює причеплені до цього лоту активи, відтак їхні статуси змінюються на pending. Статус самого лоту автоматично стає pending.
PATCH /api/0.1/lots/34b371dc3b8f47a0869a8cac45be1181 HTTP/1.0
Authorization: Basic Y29uY2llcmdlOg==
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",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000005",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.990049+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.989886+02:00",
"id": "34b371dc3b8f47a0869a8cac45be1181",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
У разі, якщо лот перебуває у статусі pending.sold, бот змінює статус активів, що були причеплені до цього лоту на complete, змінюючи статус самого лоту на sold.
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 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": "sold",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.733583+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.733416+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
За’язок ЦБД з RDB¶
Після того, як лот сформований (active.saleable), він стає доступним до виставлення на торги в ЦБД. Аби завести процедуру по певному лоту, необхідно вказати його lot id. Виконавши це, у процедурі з’явиться поле merchandisingObject, у якому значитиметься id поточного лоту, а також вказуватиметься id аукціону, у якому продаватиметься цей лот. В Реєстрі статус лоту з яким ви працюєте зміниться на active.awaiting, що ідентифікуватиме процес заведення процедури по цьому лоту в ЦБД, а також те, що він стає недоступним для використання в інших процедурах.
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 HTTP/1.0
Authorization: Basic Y29udm95Og==
Host: lb.api-sandbox.registry.ea.openprocurement.net
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "active.awaiting",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.471010+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.470846+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
Якщо в ЦБД процедура успішно створена, в RDB статус лота змінюється на active.auction:
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 HTTP/1.0
Authorization: Basic Y29udm95Og==
Host: lb.api-sandbox.registry.ea.openprocurement.net
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "active.auction",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.620778+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.620586+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
Якщо в заведеній процедурі лот було продано, його статус в RDB змінюється на sold:
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 HTTP/1.0
Authorization: Basic Y29udm95Og==
Host: lb.api-sandbox.registry.ea.openprocurement.net
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "pending.sold",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.678385+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.678224+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
У випадку, якщо лот залишився некупленим, його статус повертається у active.auction, стаючи знову доступним до виставлення на торги:
GET /api/0.1/lots/f1f4c4b5df334cf087215b7e2f29e113 HTTP/1.0
Authorization: Basic Y29udm95Og==
Host: lb.api-sandbox.registry.ea.openprocurement.net
Response: 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
{
"data": {
"status": "active.salable",
"lotIdentifier": "Q81318b19827",
"lotID": "UA-LR-DGF-2018-01-15-000004",
"description": "Щось там тестове",
"title": "Тестовий лот",
"lotType": "basic",
"dateModified": "2018-01-15T15:33:04.521993+02:00",
"owner": "broker",
"lotCustodian": {
"contactPoint": {
"name": "Державне управління справами",
"telephone": "0440000000"
},
"identifier": {
"scheme": "UA-EDR",
"id": "00037256",
"uri": "http://www.dus.gov.ua/"
},
"name": "Державне управління справами",
"address": {
"postalCode": "01220",
"countryName": "Україна",
"streetAddress": "вул. Банкова, 11, корпус 1",
"region": "м. Київ",
"locality": "м. Київ"
}
},
"date": "2018-01-15T15:33:04.521820+02:00",
"id": "f1f4c4b5df334cf087215b7e2f29e113",
"assets": [
"d7017f6e2c474d4fa8b25f8363b45d70"
]
}
}
Отримання інформації про лот¶
Отримати список всіх лотів¶
Отримати список всіх лотів.
Приклад запиту:
Приклад відповіді:
query offset: параметр, який ви повинні додати до вихідного запиту, щоб отримати наступну сторінку
query limit: обмеження кількості активів, що повертаються (дефолтне значення - 100)
reqheader Authorization: необов’язковий токен OAuth для аутентифікації
statuscode 200: без помилок
statuscode 404: ресурс не знайдено
Сортування¶
Повернені лоти просортовані за датою модифікації.
Обмеження кількості лотів, що повертаються¶
Ви можете контролювати кількість data записів потоку даних закупівлі (розмір пакета) за допомогою параметра limit. Якщо він не вказаний, то дані будуть повернені пакетами по 100 елементів.
Пакети¶
Відповідь містить елемент next_page з такими властивостями:
| offset: | Це параметр, який ви повинні додати до вихідного запиту, щоб отримати наступну сторінку. |
|---|---|
| path: | Це частина шляху URL-адреси з вихідними параметрами та доданим/заміненим offset параметром вище. |
| uri: | Повна версія URL-адреси для наступної сторінки. |
Якщо запит наступної сторінки повертається без даних (наприклад, пустий масив), тоді немає сенсу викликати сторінки далі.
Синхронізація¶
Часто необхідно мати можливість синхронізувати зміни центральної бази даних з іншою базою даних (ми будемо називати її “локальною”). Стандартне сортування “за датою модифікації” разом із механізмом пакетування дозволяє ефективно здійснювати синхронізацію. Процес синхронізації може виконуватись посторінково, поки не буде жодних нових даних, що повертаються. Тоді синхронізатор призупиниться на деякий час, щоб дозволити центральній базі даних зареєструвати деякі зміни і спробувати завантажити наступну сторінку. next_page гарантує, що усі зміни з останнього запиту будуть включені у новий пакет.
Безпечна частота запитів на синхронізацію - раз в 5 хвилин.
Прочитати інформацію про окремі лоти¶
Отримати деталі лоту
Приклад запиту:
Приклад відповіді:
reqheader Authorization: необов’язковий токен OAuth для аутентифікації
statuscode 200: без помилок
statuscode 404: лот не знайдено
Аутентифікація¶
Деякі запити API (особливо GET запити лише для читання) не потребують аутентифікації. Інші, ті, які модифікують дані у базі даних, потребують аутентифікації брокера через ключ API. Додатково видаються токени власника, щоб забезпечити кілька ролей дійових осіб при створенні об’єкта.
Ключі API¶
Ключ API - це ім’я користувача, що буде використовуватись зі схемою базової аутентифікації.
Токени власника¶
Отримання токена¶
Токен видається, коли об’єкт створюється в базі даних:
У відповіді є access разом з token. Це значення можна використати для модифікації об’єктів у “ролі Власника”.
Використання токена¶
Ви можете передати токен доступу такими способами:
параметр рядка URL запиту acc_token
заголовок HTTP запиту X-Access-Token
- access.token in the body of POST/PUT/PATCH request
Ось приклад, де токен передається як рядок URL запиту:
Робота з API в режимі кластеру¶
Дані синхронізуються на кластері з декількох серверів. Для узгодження між окремими запитами до RDB важливо, щоб клієнт працював завжди з одним сервером. Тому обов’язково використовувати реп’яшок (сookie) при подачі POST/PUT/PATCH/DELETE запитів. Реп’яшки (сookies) забезпечують прив’язку до сервера. Такий реп’яшок можна отримати через GET запит, а тоді використовувати його в POST/PUT/PATCH/DELETE.
Якщо під час операцій сервер запитаний реп’яшком недоступний або впав, клієнт отримає 412 код стану запиту і новий реп’яшок. Запит потрібно повторити з використанням нового реп’яшка.
Опції¶
Крім надання полів та їхніх значень у запиті ви можете ще вказати опції для контролю над тим, як буде оброблятись запит і як буде генеруватись відповідь. Для GET запитів, опції вказуються як URL параметри з префіксом opt_. Для POST чи PUT запитів опції вказуються в тілі, всередині об’єктів опцій вищого рівня (схожих на обє’кт даних). Опція вказана в тілі перевизначає opt_ опцію з URL параметра.
Ці опції можна комбінувати в одному запиті, хоча деякі з них можуть викликати конфлікт у відповіді.
| pretty: | ?opt_pretty options: { pretty: true } Надає відповідь у форматі “pretty”. У випадку з JSON це означає правильне розбиття рядків і відступи для зручності читання. Це займе додатковий час і збільшить розмір відповіді, тому краще буде використовувати цю опцію тільки під час налагоджування (debugging). |
|---|---|
| jsonp: | ?opt_jsonp=myCallback Повертає відповідь у форматі JSON-P замість простого JSON, щоб дозволити запитам приходити з браузерів і працювати навколо “однакової політики походження (same origin policy).” Функція названа так само як значення параметра opt_jsonp буде викликана з одним аргументом - JavaScript об’єктом, що представляє відповідь. |
| fields: | ?opt_fields=comma,separated,field,list Список додаткових полів, що міститимуться у відповіді. |
Рекомендації для роботи¶
Контроль частоти запитів¶
На “агресивні” IP адреси може бути накладено обмеження на швидкість, з якою сервери RDB опрацьовують запити. У відповідь на запити, які прийшли швидше ніж дозволено, RDB відповідає з кодом статусу 429
Очікується, що на такий код відповіді ПЗ майданчика буде реагувати таким чином: буде повторювати запити, які повернулися з таким кодом помилки, збільшуючи затримку між окремими запитами, що посилаються на RDB, доти доки запити не почнуть вдаватися (2xx/3xx відповіді).
Така поведінка серверів RDB необхідна, щоб рівномірніше розподіляти ресурси серверів між майданчиками.
Відповіді¶
Після обробки API завжди надає відповідь, звітуючи або про успіх, або про помилку.
Коди стану¶
У будь-якому випадку API повинен повернути Код стану HTTP, що вказуватиме природу помилки (див. внизу), з тілом відповіді у форматі JSON, що міститиме додаткову інформацію.
- 200
Успіх. Якщо це був запит про інформацію, то вона буде доступна у data полі на верхньому рівні тіла відповіді.
- 201
Створено. Його інформація доступна у data полі на верхньому рівні тіла відповіді. API URL, де об’єкт можна прочитати, міститься у Location заголовку відповіді.
- 400
Неправильний запит. Зазвичай це відбувається через відсутній або неправильний параметр. Перевірте документацію та синтаксис вашого запиту і спробуйте ще раз.
- 401
Несанкційонований доступ. Не було надано дійсного API ключа разом із запитом, тому API не може зв’язати користувача із запитом.
- 403
Заборонено. API ключ та синтаксис запиту були дійсними, але сервер відмовляється виконати запит. Це може статися, якщо ви пробуєте прочитати або записати об’єкти чи властивості, до яких не маєте доступу.
- 404
Ресурс не знайдено. Або даний метод та шлях запиту не вказують відому дію для API, або об’єкт, вказаний у запиті, не існує.
- 412
Збій під час обробки попередньої умови. Дивіться розділ Pобота з API в режимі API in cluster mode.
- 429
Перевищено допустиму частоту запитів. Дивіться розділ Контроль частоти запитів.
- 500
Помилка сервера. Була проблема зі сторони OpenProcurement.
Відповідь з повідомленням про успіх¶
Кожен успішний запит вичитки, створення, оновлення, чи заміни отримує відповідь, що містить data атрибут. Цей data атрибут містить повне представлення JSON об’єкта після операції. Якщо деякі дані були згенеровані у результаті обробки (наприклад, нові ID об’єкта або modified дата), то вони присутні у відповіді.
Запити списку отримують схожі відповіді, але замість одного об’єкта в data атрибуті, JSON відповідь містить колекцію об’єктів.
Приклад відповіді з повідомленням про успіх¶
Це відповідь, що описує лот.
Відповідь з повідомленням про помилку¶
У випадку помилки, тіло відповіді міститиме errors поле на вищому рівні. Воно містить масив як мінімум одного помилкового об’єкта описаного нижче:
| location: | Частина запиту спричинює помилку. Можливі значення це header (заголовок) або body (тіло). |
|---|---|
| name: |
|
| description: | Докладний (придатний для читання людиною) опис помилки. |
Приклад відповіді з повідомленням про помилку¶
Зразок нижче вказує на неповний запит.