Rest API Список документів на повернення товару

23. Ресурс `/refund-documents/` (Документ на повернення товару, Колекція, Тільки для читання)

Документ на повернення товару - це документ із зазначеними деталями відносно повернення товару в магазин. З допомогою ресурсу /refund-documents/ можна отримати доступ до списку документів на товари, які були повернені. А також додавати в довідник нові документи на повернення .

23.1. Структура об'єкта Refund documents:

Назва поля	Тип поля	розмір	Обов'язково	Тільки читання	Примітка
`url`	URL		ні	так	url цього об'єкта
`date`	дата, час	50	так	ні	дата та час повернення товару
`order_id`	рядок	200	так	ні	ідентифікатор чека
`shop_id`	рядок	50	так	ні	ідентифікатор магазину
`shop_url`	URL		ні	так	url цього об'єкта
`cashier_id`	рядок		ні	ні	ідентифікатор касира
`cashier_url`	URL		ні	так	url цього об'єкта
`loyalty_id`	рядок	50	ні	ні	повинен бути унікальним і відповідати `id` учасника програми лояльності з клієнтської бухгалтерської програми
`loyalty_url`	URL		ні	так	url цього об'єкта
`price_total`	число		так	ні	загальна вартість позиції (= ціна * кількість)
`items_qty`	число		так	ні	кількість товарів
`products`	список		так	ні	масив товарів
`refund_id`	список		так	ні	ідентифікатор документу повернення

23.1.2. Структура об'єкта ТОВАРИ (`PRODUCTS`):

Кожен товар містить в собі певні характеристики, які можна виразити в такій структурі:

Назва поля	Тип поля	розмір	Обов'язково	Тільки читання	Примітка
`product_id`	рядок	200	так	ні	ідентифікатор товару з Довідника по товарах (див.[`/products/`])
`product_url`	URL		ні	так	url ідентифікатора товару
`qty`	число		так	так	кількість
`price`	число		ні	ні	реальна ціна позиції (якщо це поле відсутнє, чи `price`*`qty` <> `price_total`, то вираховується, як `price_total`/`qty`)
`price_total`	число		так	ні	загальна вартість позиції (= ціна * кількість)
`discount`	число		ні	ні	знижка

23.2. Доступні команди

Для управління ресурсом /refund-documents/ підтримуються наступні команди:

GET - отримати одну сторінку колекції
POST - завантажити документи на повернення товару
OPTIONS - мета-інформація по структурі об'єкта
HEAD - аналог GET, але повертається тільки заголовок відповіді

23.2.1. `GET /refund-documents/` - отримати одну сторінку колекції.

Вид команди: GET http://api.datawiz.io/api/v1/refund-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/refund-documents/.json/?search=unknown-string

{
     "count": 0,
     "next": null,
     "previous": null,
     "results": [] 
}

Приклад колекції з 2-х елементів: GET http://api.datawiz.io/api/v1/refund-documents/?format=api&page_size=2:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
            "url": "http://api.datawiz.io/api/v1/refund-documents/cb2084aa-4644-11e5-80d8-a01d4897e530/",
            "date": "2015-01-01T00:00:00",
            "order_id": "cb2084aa-4644-11e5-80d8-a01d4897e530",
            "shop_id": "675",
            "shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
            "cashier_id": null,
            "cashier_url": null,
            "loyalty_id": null,
            "loyalty_url": null,
            "price_total": "20.0000",
            "items_qty": "2.0000",
            "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",
                    "discount": "5.0000"
                }
            ]
        },
        {
            "url": "http://api.datawiz.io/api/v1/refund-documents/e2df0ccd-5489-11e6-a618-e03f4978a152/",
            "date": "2015-01-01T00:00:00",
            "order_id": "e2df0ccd-5489-11e6-a618-e03f4978a152",
            "shop_id": "675",
            "shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
            "cashier_id": null,
            "cashier_url": null,
            "loyalty_id": null,
            "loyalty_url": null,
            "price_total": "20.0000",
            "items_qty": "2.0000",
            "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",
                    "discount": "5.0000"
                }
            ]
        }
    ]
}

Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь з відповідним статусом, а також повідомлення про помилку, записаним у ключі detail і/або в полі http.response.content:

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS, PATCH 
{
"detail": "Not found"
}

23.2.2 `POST /refund-documents/` - додати інформацію по документу на повернення продукту

Вид команди: POST http://api.datawiz.io/api/v1/refund-documents/?format=json

Суфікси:

.json - Отримати відповідь з сервера в форматі JSON
.api - Отримати відповідь з сервера в форматі HTML (тестова платформа)

Параметри:

format = json | api - аналог вищевказаних суфіксів

Дані запиту:

У запиті передається JSON-об'єкт типу словник (dictionary), який описує документ на отримання продукту. Важливі поля: date, order_id, shop_id, price_total, items_qty, products, product_id, qty, price price_total. Послідовність полів не принципова.

Приклад запиту на завантаження документу на переміщення товару: POST http://api.datawiz.io/api/v1/refund-documents/.json

{
            "url": "http://api.datawiz.io/api/v1/refund-documents/cb2084aa-4644-11e5-80d8-a01d4897e530/",
            "date": "2015-01-01T00:00:00",
            "order_id": "cb2084aa-4644-11e5-80d8-a01d4897e530",
            "shop_id": "675",
            "shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
            "cashier_id": null,
            "cashier_url": null,
            "loyalty_id": null,
            "loyalty_url": null,
            "price_total": "20.0000",
            "items_qty": "2.0000",
            "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",
                    "discount": "5.0000"
                }
            ]
        }

Відповідь сервера:

При коректній обробці запиту сервер повертає код статусу 201 і статус створення об'єкта.

Приклад відповіді сервера:

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Location: http://api.datawiz.io/api/v1/refund-documents/124/
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 1
}

Умови та обмеження (Constraints):

Якщо об'єкт з ідентифікатором order_id, shop_id, cashier_id, loyalty_id вже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
Не можна додати на сервер об'єкт, якщо не існує товару з вказаним ідентифікатором product_id

Повідомлення про помилку:

У випадку виникнення помилки сервер повертає відповідь із відповідним статусом, а також повідомленням про помилку, записаним навпроти імені поля, з яким ця помилка пов'язана. Якщо помилка стосується не окремого поля, а всього об'єкта, то повідомлення про помилку буде записано навпроти ключа non_field_errors.

ПРИМІТКА. Кожне повідомлення про помилку являє собою колекцію (масив) рядкових символів.

Приклад відповіді сервера при виникненні помилки (поле product_id передано порожнім):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
    "name": "Refund 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": {
            "url": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Url"
            },
            "date": {
                "type": "datetime",
                "required": true,
                "read_only": false,
                "label": "Date"
            },
            "order_id": {
                "type": "string",
                "required": true,
                "read_only": false,
                "label": "Order id",
                "max_length": 200
            },
            "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"
            },
            "cashier_id": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "Cashier id",
                "max_length": 50
            },
            "cashier_url": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Cashier url"
            },
            "loyalty_id": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "Loyalty id",
                "max_length": 50
            },
            "loyalty_url": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Loyalty url"
            },
            "price_total": {
                "type": "decimal",
                "required": true,
                "read_only": false,
                "label": "Price total"
            },
            "items_qty": {
                "type": "decimal",
                "required": true,
                "read_only": false,
                "label": "Items qty"
            },
            "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"
                        },
                        "discount": {
                            "type": "decimal",
                            "required": false,
                            "read_only": false,
                            "label": "Discount"
                        }
                    }
                }
            }
        }
    }
}

Rest API Список документів на повернення товару - datawizio/pythonAPI GitHub Wiki

23. Ресурс `/refund-documents/` (Документ на повернення товару, Колекція, Тільки для читання)

23.1. Структура об'єкта Refund documents:

23.1.2. Структура об'єкта ТОВАРИ (`PRODUCTS`):

23.2. Доступні команди

23.2.1. `GET /refund-documents/` - отримати одну сторінку колекції.

Суфікси:

Параметри:

Відповідь сервера:

Повідомлення про помилку:

23.2.2 `POST /refund-documents/` - додати інформацію по документу на повернення продукту

Суфікси:

Параметри:

Дані запиту:

Відповідь сервера:

Умови та обмеження (Constraints):

Повідомлення про помилку:

⚠️ GitHub.com Fallback ⚠️

Rest API Список документів на повернення товару - datawizio/pythonAPI GitHub Wiki

23. Ресурс /refund-documents/ (Документ на повернення товару, Колекція, Тільки для читання)

23.1. Структура об'єкта Refund documents:

23.1.2. Структура об'єкта ТОВАРИ (PRODUCTS):

23.2. Доступні команди

23.2.1. GET /refund-documents/ - отримати одну сторінку колекції.

Суфікси:

Параметри:

Відповідь сервера:

Повідомлення про помилку:

23.2.2 POST /refund-documents/ - додати інформацію по документу на повернення продукту

Суфікси:

Параметри:

Дані запиту:

Відповідь сервера:

Умови та обмеження (Constraints):

Повідомлення про помилку:

⚠️ **GitHub.com Fallback** ⚠️

23. Ресурс `/refund-documents/` (Документ на повернення товару, Колекція, Тільки для читання)

23.1.2. Структура об'єкта ТОВАРИ (`PRODUCTS`):

23.2.1. `GET /refund-documents/` - отримати одну сторінку колекції.

23.2.2 `POST /refund-documents/` - додати інформацію по документу на повернення продукту

⚠️ GitHub.com Fallback ⚠️