Rest API Purchase documents - datawizio/pythonAPI GitHub Wiki

20. Resource /purchase-documents/ (Purchase documents, Collection, Read only)

Purchase documents - are documents made by shop when ordering goods from suppliers or manufacturers. They include product name, item number, bar code, measurement units, price and quantity. With the help of /order document/ you can get access to the list of purchase documents and add new documents for purchases.

20.1. Purchase documents object structure:

Field name Field type Size Required Read only Remark
document_id line yes no Document identifier has to correspond to id from the client's accounting application
url URL 50 no yes url of this object
document_number line 50 no no reference number of the document
shop_id line 50 no yes has to correspond to shop id from the client's accounting application
shop_url URL no yes url of this object
supplier_id line 50 yes no has to correspond to product supplie id
supplier_url URL no yes url of this object
items_qty number 50 yes no quantity of products
receive_date time and date 50 yes no time and date of receiving
responsible line 200 yes no responsible person
order_date time and date yes no time and date of ordering
price_total number yes no total price
commodity_credit_days number no no number of days for commodity credit
products line yes no products

20.1.2. 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)

20.2. Available commands

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

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

20.2.1. GET /purchase-documents/ - to receive one page of a collection.

Command type: GET http://api.datawiz.io/api/v1/purchase-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 to a request:

GET http://api.datawiz.io/api/v1/purchase-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/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"
                }
            ]
        },

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

20.2.2 POST /purchase-documents/ - to add information about purchase documents

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

Suffixes:

  • .json - to receive the response from a server in JSON format
  • .api - to receive an 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 purchase documents. Important fields: document_id, shop_id, supplier_id, product_id, qty, document_date, responsible, order_date, price_total, price . The sequence of fields is not important.

Example of request to load purchase document:

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

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/purchase-documents/124/
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 1
}

Conditions and constraints:

  • If an object with product_id, shop_id, date already exists on the server, the request will replace the object on server without notification.
  • price_total should equal price*qty.
  • One can not add to server an object if there is no shop with an indicated shop_id
  • One can not add to server an object if there is no product with an indicated product_id
  • One can not add to server an object if there is no supplier with an indicated supplier_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 (qty field is empty):

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

20.2.3. OPTIONS /purchase-documents/ - meta information about an object structure

The following JSON structure returns at this command:

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"
}
}
}
}
}
}
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️