-
Notifications
You must be signed in to change notification settings - Fork 3
Rest API Список документів на замовлення продукту
Документ на замовлення продукту - це документ, який складається магазином під час замовлення товарів у постачальника чи виробника. Він включає назву товару, артикул, штрих-код, одиниці виміру, ціну та кількість товару. З допомогою ресурсу /purchase-documents/
можна отримати доступ до списку документів на замовлення товарів. А також додавати в довідник нові документи на замовлення
Назва поля | Тип поля | розмір | Обов'язково | Тільки читання | Примітка |
---|---|---|---|---|---|
document_id |
рядок | так | ні | ідентифікатор документа, повинен відповідати id з клієнтської бухгалтерської програми |
|
url |
URL | 50 | ні | так | url цього об'єкта |
document_number |
рядок | 50 | ні | ні | порядковий номер документа |
shop_id |
рядок | 50 | ні | так | повинен відповідати id магазину з клієнтської бухгалтерської програми |
shop_url |
URL | ні | так | url цього об'єкта | |
supplier_id |
рядок | 50 | так | ні | повинен відповідати id постачальника товару |
supplier_url |
URL | ні | так | url цього об'єкта | |
items_qty |
число | 50 | так | ні | кількість продуктів |
receive_date |
дата, час | 50 | так | ні | дата та час отримання |
responsible |
рядок | 200 | так | ні | відповідальний |
order_date |
дата, час | так | ні | дата та час замовлення | |
price_total |
число | так | ні | загальна вартість | |
commodity_credit_days |
число | ні | ні | кількість днів товарного кредиту | |
products |
рядок | так | ні | товари |
Кожен товар містить в собі певні характеристики, які можна виразити в такій структурі:
Назва поля | Тип поля | розмір | Обов'язково | Тільки читання | Примітка |
---|---|---|---|---|---|
product_id |
рядок | 200 | так | ні | ідентифікатор товару з Довідника по товарах (див.[/products/ ]) |
product_url |
URL | ні | так | url ідентифікатора товару | |
qty |
число | так | так | кількість | |
price |
число | ні | ні | реальна ціна позиції (якщо це поле відсутнє, чи price *qty <> price_total , то вираховується, як price_total /qty ) |
|
price_total |
число | так | ні | загальна вартість позиції (= ціна * кількість) |
Для управління ресурсом /purchase-documents/
підтримуються наступні команди:
-
GET
- отримати одну сторінку колекції -
POST
- завантажити документи на замовлення продукту -
OPTIONS
- мета-інформація по структурі об'єкта -
HEAD
- аналогGET
, але повертається тільки заголовок відповіді
Вид команди: GET http://api.datawiz.io/api/v1/purchase-documents
-
.json
- Отримати відповідь з серверу в форматі JSON -
.api
- Отримати відповідь з серверу в форматі HTML (тестова платформа)
-
format = json | api
- аналог вищевказаних суфіксів -
page_size = nn
- встановити розмір сторінки рівнийnn
об'єктів -
page = n
- завантажити сторінкуn
-
search = text
- відображати тільки об'єкти, в поліname
яких знайдено "text" -
ordering = name | identifier
- сортувати по полю в алфавітному порядку (від меншого - до більшого) -
ordering = -name | -identifier
- сортувати по полю в зворотньому порядку
Об'єкт "колекція" складається з чотирьох полів (count
, next
, previous
, results
).
Приклад пустої колекції, отриманої в результаті запиту:
GET http://api.datawiz.io/api/v1/purchase-documents/.json/?search=unknown-string
{
"count": 0,
"next": null,
"previous": null,
"results": []
}
Приклад колекції з 2-х елементів:
GET http://api.datawiz.io/api/v1/purchase-documents/?format=api&page_size=2
:
HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
"document_id": "11114",
"url": "http://api.datawiz.io/api/v1/purchase-documents/11114/",
"document_number": "",
"shop_id": "675",
"shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
"supplier_id": "2",
"supplier_url": "http://api.datawiz.io/api/v1/suppliers/supplier-1/",
"items_qty": "2.0000",
"receive_date": "2016-07-01T00:00:00",
"responsible": "",
"order_date": "2016-01-01T00:00:00",
"price_total": "20.0000",
"commodity_credit_days": 0,
"products": [
{
"product_id": null,
"product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
"qty": "2.0000",
"price": "10.0000",
"price_total": "20.0000"
}
]
},
{
"document_id": "11112",
"url": "http://api.datawiz.io/api/v1/purchase-documents/11112/",
"document_number": "",
"shop_id": "675",
"shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
"supplier_id": "2",
"supplier_url": "http://api.datawiz.io/api/v1/suppliers/supplier-1/",
"items_qty": "2.0000",
"receive_date": "2016-07-01T00:00:00",
"responsible": "",
"order_date": "2016-01-01T00:00:00",
"price_total": "20.0000",
"commodity_credit_days": 0,
"products": [
{
"product_id": null,
"product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
"qty": "2.0000",
"price": "10.0000",
"price_total": "20.0000"
}
]
},
У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомлення про помилку, записаним у ключі detail
і/або в полі http.response.content
:
HTTP 404 NOT FOUND
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS, PATCH
{
"detail": "Not found"
}
Вид команди: POST http://api.datawiz.io/api/v1/purchase-documents/?format=json
-
.json
- Отримати відповідь з сервера в форматі JSON -
.api
- Отримати відповідь з сервера в форматі HTML (тестова платформа)
-
format = json | api
- аналог вищевказаних суфіксів
У запиті передається JSON-об'єкт типу словник (dictionary), який описує документ на замовлення продукту. Важливі поля: document_id
, shop_id
, supplier_id
, product_id
, qty
, document_date
, responsible
, order_date
, price_total
, price>
. Послідовність полів не принципова.
Приклад запиту на завантаження документу на замовлення продукту:
POST http://api.datawiz.io/api/v1/purchase-documents/.json
{
"document_id": "11112",
"document_number": "",
"shop_id": "675",
"supplier_id": "2",
"items_qty": "2.0000",
"receive_date": "2016-07-01T00:00:00",
"responsible": "",
"order_date": "2016-01-01T00:00:00",
"price_total": "20.0000",
"commodity_credit_days": 0,
"products": [
{
"product_id": null,
"qty": "2.0000",
"price": "10.0000",
"price_total": "20.0000"
}
]
}
При коректній обробці запиту сервер повертає код статусу 201 і статус створення об'єкта.
Приклад відповіді сервера:
HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Location: http://api.datawiz.io/api/v1/purchase-documents/124/
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 1
}
- Якщо об'єкт з ідентифікатором
product_id, shop_id, date
вже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження. -
price_total
повинен бути рівнимprice
*qty
. - Не можна додати на сервер об'єкт, якщо не існує магазину з вказаним ідентифікатором
shop_id
- Не можна додати на сервер об'єкт, якщо не існує товару з вказаним ідентифікатором
product_id
- Не можна додати на сервер об'єкт, якщо не існує постачальника із вказаним ідентифікатором
supplier_id
У випадку виникнення помилки сервер повертає відповідь із відповідним статусом, а також повідомленням про помилку, записаним навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors
.
ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядкових символів.
Приклад відповіді сервера при виникненні помилки (поле qty
передано порожнім):
HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"qty": [
"This field is required."
]
}
При виконанні даної команди повертається така JSON-структура:
OPTIONS /api/v1/purchase-documents/
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
"name": "Purchase Order Document List",
"description": "this is my text. You can see this text on the REST-page",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"document_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Document id"
},
"url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Url"
},
"document_number": {
"type": "string",
"required": false,
"read_only": false,
"label": "Document number",
"max_length": 50
},
"shop_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Shop id",
"max_length": 50
},
"shop_url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Shop url"
},
"supplier_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Supplier id",
"max_length": 50
},
"supplier_url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Supplier url"
},
"items_qty": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Items qty"
},
"receive_date": {
"type": "datetime",
"required": true,
"read_only": false,
"label": "Receive date"
},
"responsible": {
"type": "string",
"required": true,
"read_only": false,
"label": "Responsible",
"max_length": 200
},
"order_date": {
"type": "datetime",
"required": true,
"read_only": false,
"label": "Order date"
},
"price_total": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Price total"
},
"commodity_credit_days": {
"type": "integer",
"required": false,
"read_only": false,
"label": "Commodity credit days"
},
"products": {
"type": "field",
"required": true,
"read_only": false,
"label": "Products",
"child": {
"type": "nested object",
"required": true,
"read_only": false,
"children": {
"product_id": {
"type": "string",
"required": true,
"read_only": false,
"label": "Product id"
},
"product_url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Product url"
},
"qty": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Qty"
},
"price": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Price"
},
"price_total": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Price total"
}
}
}
}
}
}
}