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

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

Rest API Список документов на получение товара - datawizio/pythonAPI GitHub Wiki

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

21.1. Структура объекта Receive documents:

21.1.2. Структура обьекта ТОВАРЫ (`PRODUCTS`):

21.2. Доступные команды

21.2.1. `GET /receive-documents/` - получить одну страницу коллекции.

Суффиксы:

Параметры:

Ответ сервера:

Сообщение об ошибке:

21.2.2 `POST /receive-documents/` - добавить информацию по документу на получение продукта

Суффиксы:

Параметры:

Данные запроса:

Ответ сервера:

Условия и ограничения (Constraints):

Сообщение об ошибке:

21.2.3. `OPTIONS /receive-documents/` - мета-информация по структуре объекта

⚠️ GitHub.com Fallback ⚠️

Rest API Список документов на получение товара - datawizio/pythonAPI GitHub Wiki

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

21.1. Структура объекта Receive documents:

21.1.2. Структура обьекта ТОВАРЫ (PRODUCTS):

21.2. Доступные команды

21.2.1. GET /receive-documents/ - получить одну страницу коллекции.

Суффиксы:

Параметры:

Ответ сервера:

Сообщение об ошибке:

21.2.2 POST /receive-documents/ - добавить информацию по документу на получение продукта

Суффиксы:

Параметры:

Данные запроса:

Ответ сервера:

Условия и ограничения (Constraints):

Сообщение об ошибке:

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

⚠️ **GitHub.com Fallback** ⚠️

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

21.1.2. Структура обьекта ТОВАРЫ (`PRODUCTS`):

21.2.1. `GET /receive-documents/` - получить одну страницу коллекции.

21.2.2 `POST /receive-documents/` - добавить информацию по документу на получение продукта

21.2.3. `OPTIONS /receive-documents/` - мета-информация по структуре объекта

⚠️ GitHub.com Fallback ⚠️