Skip to content

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

Jump to bottom Edit New page
Victor Danyliuk edited this page Sep 8, 2016 · 9 revisions

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

Документ на отримання товару - це накладна, в якій зазначені дані на поставлений постачальником товар в магазин. В накладній вказується назва товару, штрих-код, ціна, кількість. З допомогою ресурсу /receive-documents/ можна отримати доступ до списку документів на отримання товарів. А також додавати в довідник нові документи на отримання.

21.1. Структура об'єкта Receive documents:

Назва поля Тип поля розмір Обов'язково Тільки читання Примітка
document_id рядок 50 так ні ідентифікатор документа, повинен відповідати id з клієнтської бухгалтерської програми
url URL ні так url цього об'єкта
supplier_id рядок 50 так ні ідентифікатор постачальника
supplier_url URL ні так url цього об'єкта
document_number рядок 50 ні ні номер документу
shop_id рядок 50 так ні ідентифікатор магазину
shop_url URL ні так url цього об'єкта
order_id рядок 50 ні ні ідентифікатор замовлення
order_url URL ні так url цього об'єкта
document_date дата, час так ні дата та час створення документа
responsible рядок 100 так ні відповідальний за отримання
products список так ні масив товарів
items_qty число так ні кількість товарів
price_total число так ні загальна вартість товарів в документі

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

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

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

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

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

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

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

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

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, HEAD, OPTIONS
{
    "count": 11, 
    "next": "http://api.datawiz.io/api/v1/receive-documents/?page=2&page_size=2&format=api", 
    "previous": null, 
    "results": [
        {
           "document_id": "r-document-1",
            "url": "http://api.datawiz.io/api/v1/receive-documents/r-document-1/",
            "supplier_id": "2",
            "supplier_url": "http://api.datawiz.io/api/v1/suppliers/supplier-1/",
            "document_number": "11221",
            "shop_id": "863",
            "shop_url": "http://api.datawiz.io/api/v1/shops/9856d0f5-0929-11e5-80d8-7054d2c57800/",
            "order_id": "1414274",
            "order_url": "http://api.datawiz.io/api/v1/purchase-documents/p-document-1/",
            "document_date": "2016-01-01T00:00:00",
            "responsible": "Petya",
            "items_qty": "3.0000",
            "price_total": "20.0000",
            "products": [
                {
                  "product_id": "a26f866b-1465-11e5-80cb-a01d4897e530",
                    "product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
                    "qty": "3.0000",
                    "price": "10.0000",
                    "price_total": "20.0000"
                } 
                         ]

   },        
   {
       "document_id": "r-document-1",
        "url": "http://api.datawiz.io/api/v1/receive-documents/r-document-1/",
        "supplier_id": "2",
        "supplier_url": "http://api.datawiz.io/api/v1/suppliers/supplier-1/",
        "document_number": "11221",
        "shop_id": "863",
        "shop_url": "http://api.datawiz.io/api/v1/shops/9856d0f5-0929-11e5-80d8-7054d2c57800/",
        "order_id": "1414274",
        "order_url": "http://api.datawiz.io/api/v1/purchase-documents/p-document-1/",
        "document_date": "2016-01-01T00:00:00",
        "responsible": "Petya",
        "items_qty": "3.0000",
        "price_total": "20.0000",
        "products": [
            {
              "product_id": "a26f866b-1465-11e5-80cb-a01d4897e530",
                "product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
                "qty": "3.0000",
                "price": "10.0000",
                "price_total": "20.0000"
            } 
                     ]
   }, 
]



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

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

HTTP 404 NOT FOUND 
Content-Type: application/json 
Vary: Accept 
Allow: GET, HEAD, OPTIONS, PATCH 

{
"detail": "Not found"
}

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

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

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

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

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

{
    "document_id": "r-document-1",
    "supplier_id": "2",
    "document_number": "11221",
    "shop_id": "863",
    "order_id": "1414274",
    "document_date": "2016-01-01T00:00:00",
    "responsible": "Petya",
    "items_qty": "3.0000",
    "price_total": "20.0000"
    "products": [
                {
                  "product_id": "3276889",
                  "qty": "10.0000",
                  "price": "20.0000",
                  "price_total": "200.0000"
                }
                ]
}
Відповідь сервера:

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

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

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Location: http://api.datawiz.io/api/v1/receive-documents/124/
Allow: GET, POST, HEAD, OPTIONS

{
"updated": 0,
"inserted": 1
}
Умови та обмеження (Constraints):
  • Якщо об'єкт з ідентифікатором product_id, shop_id, date вже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
  • price_total повинен бути рівним price*qty.
  • Не можна додати на сервер об'єкт, якщо не існує магазину з вказаним ідентифікатором shop_id
  • Не можна додати на сервер об'єкт, якщо не існує товару з вказаним ідентифікатором product_id
  • Не можна додати на сервер об'єкт, якщо не існує товару з вказаним ідентифікатором supplier_id
Повідомлення про помилку:

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

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

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

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

21.2.3. OPTIONS /receive-documents/ - мета-інформація по структурі об'єкта

При виконанні даної команди повертається така JSON-структура:

OPTIONS /api/v1/receive-documents/ 

HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
"name": "Receive 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",
"max_length": 50
},
"url": {
"type": "field",
"required": false,
"read_only": true,
"label": "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"
},
"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"
},
"order_id": {
"type": "string",
"required": false,
"read_only": false,
"label": "Order id",
"max_length": 50
},
"order_url": {
"type": "field",
"required": false,
"read_only": true,
"label": "Order url"
},
"document_date": {
"type": "datetime",
"required": true,
"read_only": false,
"label": "Document date"
},
"responsible": {
"type": "string",
"required": true,
"read_only": false,
"label": "Responsible",
"max_length": 100
},
"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"
}
}
}
},
"items_qty": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Items qty"
},
"price_total": {
"type": "decimal",
"required": true,
"read_only": false,
"label": "Price total"
}
}
}
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally