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

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 список да нет массив товаров

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, но возвращается только заголовок ответа

22.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"
}

22.2.2 POST /refund-documents/ - добавить информацию по документу на возврат товара

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

Суффиксы:
  • .json - получить ответ с сервера в формате JSON
  • .api - получить ответ с сервера в формате HTML (тестовая платформа)
Параметры:
  • format = json | api - аналог вышеуказанных суффиксов
    • Данные запроса:

    словарь (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"
                        }
                    }
                }
            }
        }
    }
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️