Rest API List of receipts - datawizio/pythonAPI GitHub Wiki

15. Resource /receipts/ (List of receipts, Collection)

receipts - is a list of sales receipts. Each receipt contains a list of product items. With the help of /receipts/ resource one can get access to the list of receipts and add new receipts to a catalog.

15.1. Structure of receipt

15.1.1. Structure of receipt object:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
date datetime 200 yes no Time and date of receipt logging by point-of-sale terminal
order_id line 200 yes no any receipt identifier (unique within the day and point-of-sale terminal where it was used)
shop_id line 50 no yes Shop identifier (has to correspond to shop id from the client's accounting application)
shop_url URL no yes shop identifier url
terminal_id line 50 yes no point-of-sale terminal identifier
terminal_url URL no yes point-of-sale terminal url
loyalty_id line 50 no no loyalty program identifier
loyalty_url URL no yes loyalty program identifier url
cashier_id line 50 no no cashier identifier
cashier_url URL no yes cashier identifier url
cartitems list no no array of objects of cartitems type
marker list no no list of receipt markers

15.1.2. Structure of the cartitems object in receipt

Each receipt contains a list of 0 and more items of the following structure:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
order_no whole yes no any number of item in receipt (unique whole number within one receipt)
product_id line 200 yes no product identifier from the Catalog of products (див.[/products/])
product_url URL no yes product identifier url
base_price number no no price without discount
price number no no real product price (if the field is absent price*qty <> total_price, it calculates as total_price/qty)
qty number yes no quantity
total_price number yes no total cost of the item (=price*quantity)

15.2. Available commands

The following commands are used with the /receipts/ resource:

  • GET - to receive one page from collection
  • POST - to add new receipt or list of receipts
  • `OPTIONS - meta information about the object structure
  • HEAD - similar to GET, but shows only heading of the response

15.2.1. GET /receipts/ - to receive one page of a collection.

Command type: GET http://api.datawiz.io/api/v1/receipts/

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}
  • Min_date = YYYY-MM-DD - to return only receipts with date ≥ YYYY-MM-DD
  • Max_date = YYYY-MM-DD - to return receipts with date < YYYY-MM-DD
  • Ordering = url | date | order_id - to sort fields in ascending order
  • Ordering = -url | -date | order_id - to sort fields in 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/receipts/?max_date=0000-00-00

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

Example of a 2-element collection:

GET http://api.datawiz.io/api/v1/receipts/?format=json&page_size=2:

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "count": 362203,
     "next": "http://api.datawiz.io/api/v1/receipts/?page=2&amp;page_size=2",
     "previous": null,
     "results": [
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810894/",
             "date": "2013-04-04T00: 00: 00",
             "order_id": "5281KASSA3",
             "cartitems": [
                 {
                     "url": "http://api.datawiz.io/api/v1/receipts/1810894/cartitems/9873504/",
                     "product_id": "6316",
                     "product_url": "http://api.datawiz.io/api/v1/products/6316/",
                     "price": "30.5625",
                     "qty": "0.1600",
                     "total_price": "4.8900"
                 }
                 {
                     "url": "http://api.datawiz.io/api/v1/receipts/1810894/cartitems/9875943/",
                     "product_id": "7561",
                     "product_url": "http://api.datawiz.io/api/v1/products/7561/",
                     "price": "27.2619",
                     "qty": "0.3360",
                     "total_price": "9.1600"
                 }
             ]
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810895/",
             "date": "2013-04-04T00: 00: 00",
             "order_id": "5282KASSA3",
             "cartitems": [
                 {
                     "url": "http://api.datawiz.io/api/v1/receipts/1810895/cartitems/9445051/",
                     "product_id": "1292",
                     "product_url": "http://api.datawiz.io/api/v1/products/1292/",
                     "price": "3.5400",
                     "qty": "1.0000",
                     "total_price": "3.5400"
                 }
                 {
                     "url": "http://api.datawiz.io/api/v1/receipts/1810895/cartitems/9611714/",
                     "product_id": "11495",
                     "product_url": "http://api.datawiz.io/api/v1/products/11495/",
                     "price": "12.5000",
                     "qty": "1.0000",
                     "total_price": "12.5000"
                 }
                 {
                     "url": "http://api.datawiz.io/api/v1/receipts/1810895/cartitems/10043536/",
                     "product_id": "10965",
                     "product_url": "http://api.datawiz.io/api/v1/products/10965/",
                     "price": "3.8900",
                     "qty": "1.0000",
                     "total_price": "3.8900"
                 }
             ]
         }
     ]
}

Error report:

In case of an error, server returns a response with a corresponding status and an error report in detail key:

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

15.2.2. POST /receipts/ - to add new receipt

Command type: POST http://api.datawiz.io/api/v1/receipts/?format=json

Suffixes:

  • .json - to interact with a server in JSON format
  • .api - to interact with a server in HTML format (test platform)

Parameters:

  • format=json - to interact with a server in JSON format
  • format=api - to interact with a server in HTML format (test platform)

Request data:

The requers contains JSON object describing receipt. Two fields are important: date and order_id.

cartitems field provides an array of items that may not be filled (empty receipt).

receipt can contain one or more cartitems, and in this case the following fields have to be filled for each item: product identifier (product_id) from the Catalog of products (see resource /products/), quantity (qty) and total price of the item (total_price).

Product rice field is optional and is calculated as total_price/qty.

Example of correct requests to add new receipt:

POST http://api.datawiz.io/api/v1/receipts/.json - empty receipt ( cartitems field is absent)

{
     "date": "2014-06-06T00:00:00", 
     "order_id": "1000" 
}

POST http://api.datawiz.io/api/v1/receipts/.json - empty receipt ( cartitems field is present - empty array)

{
     "date": "2014-06-06T00:00:00", 
     "order_id": "1000", 
     "cartitems": [] 
}

POST http://api.datawiz.io/api/v1/receipts/.json - receipt with two items

{
     "date": "2014-04-04T12:30:45", 
     "order_id": "KASSA3-2222", 
     "cartitems": [
         {
             "product_id": "6316", 
             "price": "30.5625", 
             "qty": "0.1600", 
             "total_price": "4.8900" 
         } 
         {
             "product_id": "7561", 
             "price": "27.2619", 
             "qty": "0.3360", 
             "total_price": "9.1600" 
         } 
     ] 
}

Server's response:

At a particular request processing the server returns 201 status code and a created object with filled url field.

Example of a server's response: Empty receipt is created:

HTTP 201 CREATED 
Content-Type: application / json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/receipts/2173120/ 
Allow: GET, POST, HEAD, OPTIONS 
{
     "url": "http://api.datawiz.io/api/v1/receipts/2173120/",
     "date": "2014-07-03T10: 06: 30",
     "order_id": "TEST-RECEIPT-777",
     "cartitems": []
}

Created receipt with two items:

HTTP 201 CREATED 
Content-Type: application/json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/receipts/2173121/ 
Allow: GET, POST, HEAD, OPTIONS 
{
     "url": "http://api.datawiz.io/api/v1/receipts/2173121/",
     "date": "2014-07-03T10: 06: 30",
     "order_id": "TEST-RECEIPT-7777",
     "cartitems": [
         {
             "url": "http://api.datawiz.io/api/v1/receipts/2173121/cartitems/10488145/",
             "product_id": "6316",
             "product_url": "http://api.datawiz.io/api/v1/products/6316/",
             "price": "30.5625",
             "qty": "0.1600",
             "total_price": "4.8900"
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/2173121/cartitems/10488144/",
             "product_id": "7561",
             "product_url": "http://api.datawiz.io/api/v1/products/7561/",
             "price": "27.2619",
             "qty": "0.3360",
             "total_price": "9.1600"
         }
     ]
}

Constraints:

  • You can not add receipt to server if here already exists receipt with the same date+order_id
  • total_price should equal price*qty. If it doesn't, the price field is stated as total_price/qty

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 ( order_id field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "order_id": [
         "This field is required." 
     ] 
}

15.2.3. OPTIONS /receipts/ - meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/receipts/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "name": "Receipt List",
     "description": "",
     "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
             }
             "date": {
                 "type": "datetime",
                 "required": true,
                 "read_only": false
             }
             "order_id": {
                 "type": "string",
                 "required": true,
                 "read_only": false,
                 "max_length": 200
             }
             "cartitems": {
                 "url": {
                     "type": "field",
                     "required": false,
                     "read_only": true,
                     "label": "Url"
                 }
                 "product_id": {
                     "type": "string",
                     "required": true,
                     "read_only": false,
                     "label": "Product id",
                     "max_length": 200
                 }
                 "product_url": {
                     "type": "field",
                     "required": false,
                     "read_only": true,
                     "label": "Product url"
                 }
                 "price": {
                     "type": "decimal",
                     "required": true,
                     "read_only": false,
                     "label": "price"
                 }
                 "qty": {
                     "type": "decimal",
                     "required": true,
                     "read_only": false,
                     "label": "qty"
                 }
                 "total_price": {
                     "type": "decimal",
                     "required": true,
                     "read_only": false,
                     "label": "total price"
                 }
             }
         }
     }
}

16. Resource /receipts/{receipt_id} - separate receipt *

With the help of /receipts/{receipt_id} resource you can get from server, fully or partially modify, or delete a particular receipt. To choose a needed receipt you should make a request to address from url field of the receipt. The list of available receipts and their identifiers can be received using GET /receipts/ command (for more details see chapter 2). Resource /receipts/ (List of receipts, Collection)

16.1. Structure of receipt

16.1.1. Structure of receipt object:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
date datetime 200 yes no Time and date of receipt logging by point-of-sale terminal
order_id line 200 yes no any receipt identifier (unique within the day and point-of-sale terminal where it was used)
shop_id line 50 no yes Shop identifier (has to correspond to shop id from the client's accounting application)
shop_url URL no yes shop identifier url
terminal_id line 50 yes no point-of-sale terminal identifier
terminal_url URL no yes point-of-sale terminal url
loyalty_id line 50 no no loyalty program identifier
loyalty_url URL no yes loyalty program identifier url
cashier_id line 50 no no cashier identifier
cashier_url URL no yes cashier identifier url
marker list no no list of receipt markers
cartitems list no no array of objects of cartitems type

16.1.2. Structure of the object CARTITEMS:

Field name Field type Size Required Read only Remark
url URL no yes url of this object
order_no whole yes no any number of item in receipt (unique whole number within one receipt)
product_id line 200 yes no product identifier from the Catalog of products (see /products/)
product_url URL no yes product identifier url
base_price number no no price without discount
price number no no real product price (if the field is absent, or price*qty <> total_price, it calculates as total_price/qty)
qty number yes no quantity
total_price number yes no total cost of the item (=price*quantity)

16.2. Available commands:

The following commands are used with the /receipts/{receipt_id} resource:

  • GET -to receive a receipt defined with the help of identifier {receipt_id}
  • PUT - * fully* substitute a receipt on server with a new one
  • PATCH - to change the value of particular fields of an object
  • DELETE - to delete a receipt
  • OPTIONS- meta information about the object structure
  • HEAD - similar to GET, but yoy receive only heading of a response

16.2.1. GET /receipts/{receipt_id}/ - to receive a receipt defined with the help of identifier {receipt_id}

Command type: GET http://api.datawiz.io/api/v1/receipts/12345 - to get a receipt with {receipt_id} = 12345

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 - to set a data format. Similar to stated above suffixes

Server's response:

If one sends to server GET /receipts/{receipt_id} command with an empty body, the server returns an object of a requested structure in JSON format or an error report.

For example, GET http://api.datawiz.io/api/v1/receipts/1710900/.json:

HTTP 200 OK 
Content-Type: application / json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
     "url": "http://api.datawiz.io/api/v1/receipts/1810900/",
     "date": "2013-04-04T00: 00: 00",
     "order_id": "5287KASSA3",
     "cartitems": [
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10209184/",
             "product_id": "8277",
             "product_url": "http://api.datawiz.io/api/v1/products/8277/",
             "price": "2.9300",
             "qty": "1.0000",
             "total_price": "2.9300"
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10318560/",
             "product_id": "6212",
             "product_url": "http://api.datawiz.io/api/v1/products/6212/",
             "price": "8.5000",
             "qty": "1.0000",
             "total_price": "8.5000"
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10374429/",
             "product_id": "2966",
             "product_url": "http://api.datawiz.io/api/v1/products/2966/",
             "price": "1.9800",
             "qty": "1.0000",
             "total_price": "1.9800"
         }
     ]
}

Error report:

In case of an error, server returns a response with a corresponding status and an error report in detail key:

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

16.2.2. PUT /receipts/{receipts_id}/ - to replace an object on server with a new object

Command type: PUT http://api.datawiz.io/api/v1/receipts/12345/.json - to replace the object with {receipt_id}=12345 into another

Suffixes:

  • .json - to interact with a server in JSON format
  • .api - to interact with a server in HTML format (test platform)

Parameters:

  • format=json - to interact with a server in JSON format
  • format=api - to interact with a server in HTML format (test platform)

Request data:

Request contains JSON object with new values of receipt

Two fields are important: date and order_id.

cartitems field is an array of items that may be not filled (empty receipt).

receipt can contain one or more cartitems, and in this case the following fields have to be filled for each item: product identifier (product_id) from the Catalog of products (see resource /products /), quantity (qty) and total price of the item (total_price).

Product rice field is optional and is calculated as total_price/qty.

Example of a request to replace an object in the Catalog of products.

PUT http://api.datawiz.io/api/v1/receipts/123456-TEST/.json

{
     "date": "2013-04-04T12: 30: 00", 
     "order_id": "KASSA3-12345", 
     "cartitems": [
         {
             "product_id": "8277", 
             "qty": 1.0000, 
             "total_price": 2.9300 
         } 
         {
             "product_id": "6212", 
             "qty": 1.0000, 
             "total_price": 8.5000 
         } 
         {
             "product_id": "2966", 
             "qty": 1.0000, 
             "total_price": 1.9800 
         } 
     ] 
}

Server's response:

At a particular request processing the server returns 200 status code and a changed object with filled url field.

Example of a server's response:

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
     "url": "http://api.datawiz.io/api/v1/receipts/1810900/",
     "date": "2013-04-04T12: 30: 00",
     "order_id": "KASSA3-12345",
     "cartitems": [
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10209184/",
             "product_id": "8277",
             "product_url": "http://api.datawiz.io/api/v1/products/8277/",
             "price": "2.9300",
             "qty": "1.0000",
             "total_price": "2.9300"
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10318560/",
             "product_id": "6212",
             "product_url": "http://api.datawiz.io/api/v1/products/6212/",
             "price": "8.5000",
             "qty": "1.0000",
             "total_price": "8.5000"
         }
         {
             "url": "http://api.datawiz.io/api/v1/receipts/1810900/cartitems/10374429/",
             "product_id": "2966",
             "product_url": "http://api.datawiz.io/api/v1/products/2966/",
             "price": "1.9800",
             "qty": "1.0000",
             "total_price": "1.9800"
         }
     ]
}

Constraints:

  • You can not add receipt to server if here already exists receipt with the same date+order_id
  • Total_price should equal price*qty. If it doesn't, the price field is stated as total_price/qty

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 ( order_id field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "order_id": [
         "This field is required." 
     ] 
}

16.2.3. PATCH /reseipts/{reseipts_id}/ - to change the value of particular fields of an object

PATCH command is used to change particular fields of an object PATCH is similar to PUT, but here you can state not only all objects, but the fields that have to be changed.

Command type: PATCH http://api.datawiz.io/api/v1/receipts/12345/.json - to remove particular fields of the object with receipt_id = 12345 into another

Suffixes:

  • .json - to interact with a server in JSON format
  • .api - to interact with a server in HTML format (test platform)

Parameters:

  • format=json - to interact with a server in JSON format
  • format=api - to interact with a server in HTML format (test platform)

Request data:

Request contains JSON object with new value of particular field of an object

Two fields are important: date and order_id.

cartitems field is an array of items that may be not filled (empty receipt). receipt can contain one or more cartitems, and in this case the following fields have to be filled for each item: product identifier (product_id) from the Catalog of products (see resource/products/), quantity (qty) and total price of the item (total_price).

Product price field is optional and is calculated as total_price/qty.

Remark cartitems field is one inseparable object. Thus, this command can not change, add or delete one item, but only delete all existing items and add all new. If there is a need to modify items in receipt (add, modify or delete) - use resource /receipt/{receipt_id}/cartitems/

Example of a request to change the value of the field date for the receipt with {receipt_id}=123456:

PUT http: //api.datawiz.io/api/v1/receipts/123456/.json

{
     "date": "2013-04-04T12: 30: 00" 
}

Server's response:

At a particular request processing the server returns 200 status code and a changed object with filled url field.

Example of a server's response:

HTTP 200 OK 
Content-Type: application / json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
     "url": "http://api.datawiz.io/api/v1/receipts/123456/",
     "date": "2013-04-04T12:30:00",
     "order_id": "RECEIPT-777",
     "cartitems": []
}

Constraints:

During a removal you can not state another receipt_id if there already exists an object with the same receipt_id.

  • During removal you can not put another date and order_id if there exists a receipt with the same date + order_id
  • total_price should equal price*qty. If it doesn't, the price field is stated as total_price/qty

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 ( qty field is empty):

HTTP 400 BAD REQUEST 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
     "cartitems": [
         {},
         {},
         {
             "qty": [
                 "Quantity can not be empty or zero"
             ]
         }
     ]
}

16.2.4. DELETE /reseipts/{reseipts_id}/ - to delete a receipt

DELETE command is used to delete a particular receipt

Command type: DELETE http://api.datawiz.io/api/v1/receipts/12345/ - to delete a receipt with receipt_id = 12345

Suffixes:

  • .json - to interact with a server in JSON format
  • .api - to interact with a server in HTML format (test platform)

Parameters:

  • format=json - to interact with a server in JSON format
  • format=api - to interact with a server in HTML format (test platform)

Request data:

The request doesn't have to contain anything.

Server's response:

At a particular request processing the server returns 204 NO CONTENT.

Example of a server's response:

HTTP 204 NO CONTENT 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

Constraints:

  • no

Error report:

In case of an error, server returns a response with a corresponding status and an error report in detail key:

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

16.2.5. OPTIONS /reseipts/{reseipts_id}/- meta information about an object structure

The following JSON structure returns at this command:

OPTIONS /api/v1/receipts/123456-NEW-ID/

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
     "name": "Receipt Instance",
     "description": "this is my second text \ naaaaa",
     "renders": [
         "application/json",
         "text/html"
     ],
     "parses": [
         "application/json",
         "application/x-www-form-urlencoded",
         "multipart / form-data"
     ],
     "actions": {
         "PUT": {
             "url": {
                 "type": "field",
                 "required": false,
                 "read_only": true
             }
             "date": {
                 "type": "datetime",
                 "required": true,
                 "read_only": false
             }
             "order_id": {
                 "type": "string",
                 "required": true,
                 "read_only": false,
                 "max_length": 200
             }
             "cartitems": {
                 "url": {
                     "type": "field",
                     "required": false,
                     "read_only": true,
                     "label": "Url"
                 }
                 "product_id": {
                     "type": "string",
                     "required": true,
                     "read_only": false,
                     "label": "Product id",
                     "max_length": 200
                 }
                 "product_url": {
                     "type": "field",
                     "required": false,
                     "read_only": true,
                     "label": "Product url"
                 }
                 "price": {
                     "type": "decimal",
                     "required": false,
                     "read_only": false,
                     "label": "Price"
                 }
                 "qty": {
                     "type": "decimal",
                     "required": true,
                     "read_only": false,
                     "label": "qty"
                 }
                 "total_price": {
                     "type": "decimal",
                     "required": true,
                     "read_only": false,
                     "label": "total price"
                 }
             }
         }
     }
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️