Rest API Список документів оприбуткування (в результаті інвентаризації) - datawizio/pythonAPI GitHub Wiki

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

Документ оприбуткування. За допомогою ресурсу /incoming-documents/ можна отримати доступ до списку документів оприбуткування. А також додавати в довідник нові документи.

32. Структура об'єкта Incoming documents:

Назва поля Тип поля розмір Обов'язково Тільки читання Примітка
url URL ні так url цього об'єкта
document_id рядок так ні ідентифікатор документа
date дата, час 50 так ні дата та час інвентаризації
shop_id рядок 50 так ні ідентифікатор магазину
shop_url URL ні так url цього об'єкта
stuff_id рядок 50 ні ні ідентифікатор касира
stuff_url рядок ні так url цього касира
products список так ні масив товарів

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

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

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

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

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

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

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

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

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

Приклад колекції: GET http://api.datawiz.io/api/v1/incoming-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/incoming-documents/cb2084aa-4644-11e5-80d8-a01d4897e530/",
            "document_id": "cb2084aa-4644-11e5-80d8-a01d4897e530",
            "date": "2015-01-01T00:00:00",
            "shop_id": "675",
            "shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
            "stuff_id": null,
            "stuff_url": null,
            "products": [
                {
                    "product_id": null,
                    "product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
                    "qty": "2.0000",
                    "price": "10.0000",
                    "total_price": "20.0000"
                }
            ]
        },
        . . .
    ]
}
Повідомлення про помилку:

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

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

{
"detail": "Not found"
}

32.2.2 POST /incoming-documents/ - додати інформацію по документу оприбуткування

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

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

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

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

{
            "url": "http://api.datawiz.io/api/v1/incoming-documents/cb2084aa-4644-11e5-80d8-a01d4897e530/",
            "document_id": "cb2084aa-4644-11e5-80d8-a01d4897e530",
            "date": "2015-01-01T00:00:00",
            "shop_id": "675",
            "shop_url": "http://api.datawiz.io/api/v1/shops/46e08f10-cbe3-11e4-80b9-a01d4897e530/",
            "stuff_id": null,
            "stuff_url": null,
            "products": [
                {
                    "product_id": null,
                    "product_url": "http://api.datawiz.io/api/v1/products/a26f866b-1465-11e5-80cb-a01d4897e530/",
                    "qty": "2.0000",
                    "price": "10.0000",
                    "total_price": "20.0000"
                }
            ]
        }
Відповідь сервера:

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

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

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

{
"updated": 0,
"inserted": 1
}
Умови та обмеження (Constraints):
  • Якщо об'єкт з ідентифікатором document_id, shop_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": "Incoming Document 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,
                "label": "Url"
            },
            "document_id": {
                "type": "string",
                "required": true,
                "read_only": false,
                "label": "Document id",
                "max_length": 200
            },
            "stuff_id": {
                "type": "integer",
                "required": true,
                "read_only": false,
                "label": "Stuff id"
            },
            "stuff_url": {
                "type": "integer",
                "required": false,
                "read_only": true,
                "label": "Stuff url"
            },
            "shop_id": {
                "type": "integer",
                "required": true,
                "read_only": false,
                "label": "Shop id"
            },
            "shop_url": {
                "type": "integer",
                "required": false,
                "read_only": true,
                "label": "Shop url"
            },
            "date": {
                "type": "datetime",
                "required": true,
                "read_only": false,
                "label": "Date"
            },
            "products": {
                "type": "field",
                "required": true,
                "read_only": false,
                "label": "Products",
                "child": {
                    "type": "nested object",
                    "required": true,
                    "read_only": false,
                    "children": {
                        "url": {
                            "type": "field",
                            "required": false,
                            "read_only": true,
                            "label": "Url"
                        },
                        "product_id": {
                            "type": "integer",
                            "required": true,
                            "read_only": false,
                            "label": "Product id"
                        },
                        "product_url": {
                            "type": "integer",
                            "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"
                        },
                        "total_price": {
                            "type": "decimal",
                            "required": true,
                            "read_only": false,
                            "label": "Total price"
                        }
                    }
                }
            }
        }
    }
}
Add a custom footer
⚠️ **GitHub.com Fallback** ⚠️