Rest API Список касових терміналів для кожного з магазинів - datawizio/pythonAPI GitHub Wiki

Список касових терміналів - це список терміналів обслуговування покупців (касові термінали) стосовно кожного магазину торгової мережі. З допомогою ресурсу /terminals/ можна отримати доступ до списку касових терміналів, а також додавати у довідник нові термінали.

З ресурсом /terminals/ підтримуються наступні команди:

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

Вид команди: GET http://api.datawiz.io/api/v1/terminals/

• .json - Отримати відповідь з серверу в форматі JSON
• .api - Отримати відповідь з серверу в форматі HTML (тестова платформа)

• format=json|api - аналог вищевказаних суфіксів
• page_size={nn} - встановити розмір сторінки рівний {nn} об'єктів
• page={n} - завантажити сторінку {n}
• shop_id={n} - відображати тільки термінали, які належать магазину з id={n}
• search = {substring} - відображати тільки об'єкти, в полі name яких знайдено фрагмент "{substring}"
• ordering=name|identifier - сортувати по полю в алфавітному порядку (від меншого - до більшого)
• ordering=-name|-identifier - сортувати по полю в зворотному порядку

ПРИМІТКА: identifier - означає сортувати по полю terminal_id

Об'єкт "колекція" із чотирьох полів (count,next, previous,results).

Приклад порожньої колекції, отриманої в результаті запиту:

GET http://api.datawiz.io/api/v1/terminals/.json/?search=unknown-shop_id

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

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

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"count": 39,
"next": "http://api.datawiz.io/api/v1/terminals/?page=2&page_size=2&format=api",
"previous": null,
"results": [
{
"url": "http://api.datawiz.io/api/v1/terminals/1-1/",
"terminal_id": "1-1",
"name": "Kassa 1",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
},
{
"url": "http://api.datawiz.io/api/v1/terminals/2-1/",
"terminal_id": "2-1",
"name": "Kassa 1",
"shop_id": "2",
"shop_url": "http://api.datawiz.io/api/v1/shops/2"
}
]
}

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

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

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

• .json - Взаємодіяти з сервером в форматі JSON
• .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)

• `format=json - взаємодіяти з сервером в форматі JSON
• `format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)

В запиті передається JSON-об'єкт типу словник (dictionary), який описує новий товар. Важливі всі три поля: terminal_id, shop_id і name. Послідовність полів не принципова.

Приклад запиту на додавання одного нового об'єкта в Список касових терміналів: POST http://api.datawiz.io/api/v1/terminals/.json

{
     "terminal_id": "1-4",
     "shop_id": "1",
     "name": "New terminal"
}

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

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

HTTP 201 CREATED 
Content-Type: application/json 
Vary: Accept 
Location: http://api.datawiz.io/api/v1/terminals/1-4/
Allow: GET, POST, HEAD, OPTIONS 
{
"updated": 0,
"inserted": 1
}

• Якщо об'єкт з ідентифікатором terminal_id уже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
• Не можна добавити на сервер об'єкт, якщо не існує магазину з вказаним ідентифікатором shop_id
• Поле name не може бути порожнім.
• Поле name повинно бути унікальним в межах одного магазину.

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

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

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

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

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

• .json - Взаємодіяти з сервером в форматі JSON
• .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)

• `format=json - взаємодіяти з сервером в форматі JSON
• `format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)

В запиті передається JSON-об'єкт типу список (list), який містить один чи більше об'єктів, що описує новий термінал. Передача на сервер об'єктів не поодиноко, а списком дозволяє значно збільшити швидкість передачі об'єктів.

Приклад запиту на пакетне додавання трьох нових об'єктів у Список касових терміналів: POST http://api.datawiz.io/api/v1/terminals/.json

[
   {
     "terminal_id": "1-4",
     "shop_id": "1",
     "name": "Terminal 4",
   },
   {
     "terminal_id": "2-1",
     "shop_id": "2",
     "name": "Kassa 1", 
   },
   {
     "terminal_id": "2-2",
     "shop_id": "2",
     "name": "Kassa 2",
   }
]

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

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

HTTP 201 CREATED
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"updated": 0,
"inserted": 3
}

• Якщо об'єкт з ідентифікатором terminal_id уже існує на сервері, то вказаний запит замінить об'єкт на сервері (replace) без попередження.
• Не можна добавити на сервер об'єкт, якщо не існує магазину із вказаним ідентифікатором shop_id
• Поле name не може бути порожнім
• Поле name повинно бути унікальним у межах одного магазину

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

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

Приклад відповіді сервера при виникненні помилки (поле shop_id другого об'єкта передано невірно):

HTTP 400 BAD REQUEST
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
[
{},
{
"shop_id": [
"Shop with id=33 does not exist"
]
},
{}
]

Як видно, помилка відбулась у другому об'єкті, в полі shop_id. Тут вказана і причина помилки.

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

OPTIONS /api/v1/terminals/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
{
"name": "Terminal List",
"description": "Terminals",
"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
},
"terminal_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
},
"shop_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"shop_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}

Скориставшись ресурсом /terminals/{id} можна отримати із сервера, модифікувати повністю і частково, а також видалити вибраний об'єкт із Списку касових терміналів. Для вибору потрібного об'єкта необхідно замінити {id} в URL ресурсі на ідентифікатор із поля terminal_id існуючого об'єкта. Перелік існуючих об'єктів і їх ідентифікаторів можна отримати скориставшись командою 'GET /terminals/' (детальніше див.розділ "[3. Ресурс /terminals/ (Список касових терміналів для кожного із магазинів, Колекція)]")

З ресурсом /terminals/{id} підтримуються наступні команди:

• GET - отримати об'єкт з terminal_id={id}
• PUT - повністю замінити об'єкт на сервері новим
• PATCH - змінити значення окремих полів об'єкта
• DELETE - вилучити із Списку касових терміналів об'єкт з terminal_id={id}
• OPTIONS - мета-інформація по структурі об'єкта
• HEAD - аналог GET, але повертається тільки заголовок відповіді

Вид команди: GET http://api.datawiz.io/api/v1/terminals/CAT11 - отримати об'єкт з terminal_id="CAT11"

• .json - Отримати відповідь з серверу в форматі JSON
• .api - Отримати відповідь з серверу в форматі HTML (тестова платформа)

• format=json|api - встановити формат даних. Аналог вищевказаних суфіксів

При відправці на сервер команди GET /terminals/{id} із порожнім тілом запиту сервер повертає об'єкт заданої структури в форматі JSON чи повідомлення про помилку.

Наприклад, GET http://api.datawiz.io/api/v1/terminals/1-1/.json:

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"url": "http://api.datawiz.io/api/v1/terminals/1-1/",
"terminal_id": "1-1",
"name": "Kassa 1",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

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

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

Фактично даний запит працює, як два послідовних запити: 1 Видалити об'єкт із старим terminal_id = {id} (DELETE) 2 Створити новий об'єкт із новим terminal_id (POST)

Вид команди: PUT http://api.datawiz.io/api/v1/terminals/1-1/.json - замінити об'єкт з terminal_id="1-1" на інший

• .json - Взаємодіяти з сервером в форматі JSON
• .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)

• format=json - взаємодіяти з сервером в форматі JSON
• format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)

В запиті передається JSON-об'єкт з новим значенням об'єкта

Важливі всі три поля: terminal_id, shop_id і name.

Приклад запиту на заміну об'єкта в Списку касових терміналів:

PUT http://api.datawiz.io/api/v1/terminals/1-1/.json

{
     "terminal_id": "1-100", 
     "name": "Another Name",
     "shop_id": "1"
}

Тут замінити потрібно поля terminal_id та name. Зазначимо, що при заміні значення ключового поля (identifier, в даному випадку - terminal_id), дане поле зміниться всюди, і всі зв'язки збережуться.

При коректній обробці запиту сервер повертає код статусу 200 та змінений об'єкт із заповненим полем url.

ПРИМІТКА. Якщо змінювалось поле terminal_id, то і поле url також зміниться!

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

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH 
{
"url": "http://api.datawiz.io/api/v1/terminals/1-100/",
"terminal_id": "1-100",
"name": "Another Name",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

• При заміні не можна вказати інший terminal_id, якщо вже існує об'єкт з таким самим terminal_id
• Поле shop_id повинно містити коректне значення із довідника Списку магазинів (див.п.1)
• Поле name не може бути порожнім
• Поле name повинно бути унікальним в межах одного магазину

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

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

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

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

Команда PATCH використовується, якщо потрібно змінити окремі поля об'єкта. Команда PATCH у всьому схожа на команду PUT, тільки в ній можна вказувати не ввесь об'єкт, а тільки ті поля, які необхідно змінити.

Вид команди: PATCH http://api.datawiz.io/api/v1/terminals/1-100/.json - замінити окремі поля об'єкта з terminal_id=1-100 на інші

• .json - Взаємодіяти з сервером в форматі JSON
• .api - Взаємодіяти з сервером в форматі HTML (тестова платформа)

• format=json - взаємодіяти з сервером в форматі JSON
• format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)

В запиті передається JSON-об'єкт з новим значенням окремих полів об'єкта

Важливі всі три поля: terminal_id, shop_id і name.

Приклад запиту на заміну значення поля name для об'єкта з terminal_id=1-100 у Списку касових терміналів:

PATCH http://api.datawiz.io/api/v1/terminals/1-100/.json

{
     "name": "Terminal #100" 
}

При коректній обробці запиту сервер повертає код статусу 200 та змінений об'єкт із заповненим полем url.

ПРИМІТКА! Якщо змінювалось поле terminal_id, то і поле url також зміниться!

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

HTTP 200 OK 
Content-Type: application/json 
Vary: Accept 
Allow: GET, POST, HEAD, OPTIONS 
{
"url": "http://api.datawiz.io/api/v1/terminals/1-100/",
"terminal_id": "1-100",
"name": "Terminal #100",
"shop_id": "1",
"shop_url": "http://api.datawiz.io/api/v1/shops/1"
}

• При заміні не можна вказувати інший terminal_id, якщо вже існує об'єкт з таким самим terminal_id.
• Поле shop_id повинно містити коректне значення із довідника Списку магазинів (див.п.1)
• Поле name не може бути порожнім
• Поле name повинно бути унікальним в межах одного магазину

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

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

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

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

Команда DELETE використовується для вилучення вказаного об'єкта із Списку касових терміналів

Вид команди: DELETE http://api.datawiz.io/api/v1/terminals/1-100/ - вилучити об'єкт із terminal_id=1-100

• .json - взаємодіяти з сервером в форматі JSON
• .api - взаємодіяти з сервером в форматі HTML (тестова платформа)

• format=json - взаємодіяти з сервером в форматі JSON
• format=api - взаємодіяти з сервером в форматі HTML (тестова платформа)

В запиті нічого передавати не потрібно.

При коректній обробці запиту сервер повертає код статусу 204 NO CONTENT.

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

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

• Не можна видалити термінал, який використовується в чеках

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

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

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

OPTIONS /api/v1/terminals/1-100/

HTTP 200 OK
Content-Type: application/json
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
{
"name": "Terminal Instance",
"description": "my Terminal doc",
"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
},
"terminal_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"name": {
"type": "string",
"required": true,
"read_only": false,
"label": "name",
"max_length": 100
},
"shop_id": {
"type": "string",
"required": true,
"read_only": false,
"max_length": 50
},
"shop_url": {
"type": "field",
"required": false,
"read_only": true
}
}
}
}