Rest API Documents to refund products - datawizio/pythonAPI GitHub Wiki

23. Resource /refund-documents/ (Documents to refund products, Collection, Read only)

Documents to refund products - are documents containing details about refunding goods in the shop. With the help of /refund-documents/ you can get access to the list of documents to refund products. And to add new documents for refunding products.

23.1. Refund documents object structure:

Field name Field type Size Required Read only Remark
url URL no yes
date time and date 50 yes no time and date of refund
order_id line 200 yes no receipt identifier
shop_id line 50 yes no shop identifier
shop_url URL no yes url of this object
cashier_id line no no cashier identifier
cashier_url URL no yes url of this object
loyalty_id line 50 no no has to be unique and correspond to an id of the loyalty program participant from a client's accounting application
loyalty_url URL no yes url of this object
price_total number yes no total cost of the item (=price*quantity)
items_qty number yes no quantity of products
products list yes no array of products
refund_id list yes no identifier of refund document

23.1.1. ‘PRODUCTS’ object structure:

Each product has some characteristics that can be shown in the next structure:

Field name Field type Size Required Read only Remark
product_id line 200 yes no product identifier from the Catalog of products (see.[/products/])
product_url URL no yes product identifier url
qty number yes yes quantity
price number no no real product price (if the field is absent, or price*qty <> price_total, it calculates as price_total/qty)
price_total number yes no total cost of the item (=price*quantity)
discount number no no discount

23.2. Available commands

To manage the /refund-documents/ resource, the following commands are used:

  • GET - to receive one page on a collection
  • POST - to load documents to refund products
  • OPTIONS - meta information about an object structure
  • HEAD - similar to GET, but you receive only a heading of a response

23.2.1. GET /refund-documents/ - to receive one page of a collection.

Command type: `GET http://api.datawiz.io/api/v1/refund-documents

Suffixes:

  • .json - to receive a response from a server in JSON format
  • .api - to receive a response from a server in HTML format (test platform)

Parameters:

  • format = json | api - similar to the stated above suffixes
  • page_size = {nn} - to establish a page size equal to {nn} objects
  • page = {n} - to load a page {n}
  • search = text - to show only the objects, which name contain "text"
  • ordering = name | identifier - to sort fields alphabetically (ascending)
  • ordering = -name | -identifier - to sort fields in the reverse order

Server's response:

The "collection" object consists of four fields (count, next, previous, results).

An example of an empty collection returned by server:

GET http://api.datawiz.io/api/v1/refund-documents/.json/?search=unknown-string

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

Example of a 2-element collection: 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"
                }
            ]
        }
    ]
}

Error report:

In case of an error, server returns a response with a corresponding status and an error report in detail key and/or in string 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/ - to add information about documents to refund products

Command type: POST http://api.datawiz.io/api/v1/refund-documents/?format=json

Suffixes:

  • .json - to receive a response from a server in JSON format
  • .api - to receive a response from a server in HTML format (test platform)

Parameters:

  • format = json | api - similar to the stated above suffixes

Request data:

A request contains a JSON-object of dictionary type describing documents to refund products.

Important fields: date, order_id, shop_id, price_total, items_qty, products, product_id, qty, price and price_total. The sequence of fields is not important.

Example of request to load documents to relocate products:

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"
                }
            ]
        }

Server's response:

At a particular request processing the server returns 201 status code and object creation details.

Example of a server's response:

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
}

Conditions and constraints:

  • If objects with order_id, shop_id, cashier_id, loyalty_id already exist on the server, the request will replace the object on server without notification.
  • One can not add to server an object if there is no product with an indicated product_id

Error report:

In case of an error, server returns a response with a corresponding status and an error report next to the field, related to that error. If an error is not only about one field, but the whole object, the report will appear next to the key non_field_errors.

Example of server's response with an error (product_id field is empty):

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** ⚠️