Отримання рахунку за номером стола

Для отримання рахунку, Expirenza надсилатиме наступне повідомлення:

getBill

❗️ Обов'язкові елементи запиту: rID,operation та tableNumber або billId.

❗️ Наразі інтеграція підтримує передачу параметру guests.dishes.dishId,
   у якому dishId порожній. 
 
❗️ Ми суворо рекомендуємо передавати dishId і не залишати його порожнім,так як
   варіант с порожнім dishId невдовзі стане застарілим, і якщо ви його
    не передавали у вас можуть виникнути проблеми з інтеграцією, та не буде 
     працювати оцінка блюд.

Переконайтесь, що ваша інтеграція підтримує всі можливі комбінації цих параметрів:

Сценарії :

1. Тільки з billId:

Сценарій з billId позначає що оплата буде здійснена по QR з пречеку.

{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "getBill",
    "billId": "079148b1-2824-11ed-8dbd-3c7c3fbcab3c"
}

1. Тільки з tableNumber:

Сценарій з tableNumber позначає що оплата буде здійснена по QR на столі.

{
    "rID" : "2021-03-13 00:32:04.942046#UP57RxE",
    "operation" : "getBill",
    "tableNumber" : "12",
}

---

Q. Як ресторану повідомити Expirenza про нове замовлення, як передати згенерований billId до Expirenza?

A. Наразі немає готового callback (він скоро буде) через який ресторан може повідомити Expirenza про нове замовлення.

Зараз Expirenza сама опитує ресторан і отримує від ресторану billId.

Приклад:

Гість ресторану робить замовлення -> замовлення вносять у POS-систему

-> гість ресторану поїв і сканує QR для оплати замовлення -> Expirenza дізнається про billId у момент сканування QR.

У випадку billId це QR на пречеку. У випадку tableNumber QR на столі.

Сервіс передачі інформації про знайдений рахунок

post

Header parameters

restoIdstringRequired

Ідентифікатор ресторану

signaturestringRequired

Підпис запиту

Body

application/json

errorCodestringOptional

Код помилки, якщо операція не успішна

errorMessagestringOptional

Текст помилки, якщо операція не успішна

rIDstringOptional

Ідентифікатор запиту в системі Shake To Pay

Example: Look for payload example: /callback/getBill

statestring · enumRequired

Стан. Enum: FAIL | SUCCESS

Possible values:

substatestringOptional

Підхід.Enum: TABLE_NOT_FOUND | ORDER_NOT_FOUND

Pattern: TABLE_NOT_FOUND|ORDER_NOT_FOUND

tableNumberinteger <int32> · int32Required

Номер столу

Responses

200

Запит прийнято та оброблено успішно

No content

post

/callback/getBill

HTTPcURLJavaScriptPython

POST /callback/getBill HTTP/1.1
Host: api.shaketopay.com.ua
restoId: text
signature: text
Content-Type: application/json
Accept: */*
Content-Length: 888

{
  "errorCode": "text",
  "errorMessage": "text",
  "orders": [
    {
      "billId": "7A051331-1C99-4DD2-9543-1585A4E21DCA",
      "bonusSum": 60.85,
      "created": "yyyy.MM.dd HH:mm:ss",
      "discounts": {},
      "guests": [
        {
          "dishes": [
            {
              "category": "Кухня",
              "categoryId": "18afdzgu53a",
              "checkNumber": "text",
              "count": 1.3,
              "dishId": "text",
              "linkedTo": "text",
              "hidden": "false",
              "name": "Шаурма царська",
              "orderNumber": 12365,
              "positionId": "text",
              "sum": 34.56,
              "taxCategory": "налоги",
              "taxCategoryId": "18afdzgu534",
              "type": "modifier"
            }
          ],
          "name": "Гость 1"
        }
      ],
      "isBanquetOrder": true,
      "isDelivery": true,
      "orderNumber": 256,
      "paymentType": "text",
      "pricingTime": "text",
      "rawSum": 1,
      "rootBillId": "text",
      "splitAvailable": true,
      "state": "text",
      "tableId": "qc7-sdv9",
      "totalSum": 123.35,
      "waiter": "text",
      "waiterId": "text",
      "billAmountForTips": 123.35
    }
  ],
  "rID": "Look for payload example: /callback/getBill",
  "state": "FAIL",
  "substate": "text",
  "tableNumber": null
}

200

Запит прийнято та оброблено успішно

No content

Payload example: /callback/getBill

JSON

{
  "errorCode": "BILL_NOT_FOUND",
  "errorMessage": "Not found bills by table number 7",
  "orders": [
    {
      "billId": "7A051331-1C99-4DD2-9543-1585A4E21DCA",
      "created": "yyyy.MM.dd HH:mm:ss",
      "discounts": {},
      "guests": [
        {
          "dishes": [
            {
              "category": "Кухня",
              "categoryId": "18afdzgu53a",
              "checkNumber": "string",
              "count": 1.3,
              "dishId": "string",
              "linkedTo": "string",
              "hidden": false,
              "name": "Шаурма царська",
              "orderNumber": 12365,
              "positionId": "string",
              "sum": 34.56,
              "taxCategory": "налоги",
              "taxCategoryId": "18afdzgu534",
              "type": "dish"
            }
          ],
          "name": "Гость 1"
        }
      ],
      "isBanquetOrder": false,
      "isDelivery": false,
      "orderNumber": 256,
      "pricingTime": "string",
      "rawSum": 0,
      "rootBillId": "string",
      "splitAvailable": true,
      "state": "string",
      "tableId": "qc7-sdv9",
      "totalSum": 123.35,
      "waiter": "string",
      "waiterId": "string",
      "billAmountForTips":123.12
    }
  ],
  "rID": "2021-04-01 09:39:06.021078#BpOI0gO",
  "state": "FAIL",
  "substate": "string",
  "tableNumber": 9
}

Роз'яснення по linkedTo

positionId - id позиції в чеку. Позиція = строчка в чеку. linkedTo - id Батьківської позиції в чеку. *Якщо страва сама по собі є батьківською треба передавати linkedTo: null

Наприклад, клієнт замовив: Біг Мак Меню

Що складається з:

1. Біг мак

1. Діпи: - Сирний соус

2. Апельсиновий Сік

В POS системі Біг Мак Меню - це комбо страва. Яка має 3 можливих складових:

1. Бургер - Біг Бак

2. Картопля на вибір Діпи/Картопля фрі (+ соус як модифікатор до картоплі).

3. Напій на вибір Кола/Спрайт/Апельсиновий сік.

Біг Мак - це батьківська страва - linkedTo = null positionId = AAA

Діпи це дочірня страва до Біг Маку, тому linkedTo = AAA - де ААА - id позиції батьківської страви positionId = BBB

Сирний соус - дочірня страва до діпів - linkedTo = BBB, positionId = CCC Апельсиновий сік - дочірня страва до Біг Маку - linkedTo = AAA, positionId = DDD

Таблиця можливих статусів.

❗❗ Для стану FAIL наявність суб-статусу є обов'язковим, суб-статус також не має бути = null.

Це потрібно для правильної комунікації із клієнтами ресторану.

Приклад: Замовлення не було знайдено, але не передано суб-статус - ORDER_NOT_FOUND. Клієнт бачить на боці Expirenza невідому помилку, замість помилки "Рахунок на столику не знайдено".

state	substate	Description
SUCCESS	-	Рахунок знайдено
FAIL	TABLE_NOT_FOUND	Стіл переданий у пошук не існує в ресторані
FAIL	ORDER_NOT_FOUND	Рахунок на столику не знайдено

Приклад: НЕ правильна помилка, коли при status - Fail не був переданий substate.

Приклад: Правильна помилка, коли при status - Fail був переданий substate.

---

Застосування знижки

Застосувати знижку для замовлення можна використовуючи об'єкт discounts що знаходиться в структурі getBill.

"discounts":{"list":[{"id": "","name":"","sum":0}} Знижки через discounts працюють тільки на відображення у чеку, це означає що знижку інтеграція має вираховувати самостійно на своєму боці та передавати у поля sum та totalSum суми страв вже з урахуванням знижки.

❗Сума кожної страви має враховувати знижки застосовані до чеку.

❗Сума знижки не має бути у від'ємних значеннях ( Приклад як не треба: sum:"-350")

Приклад використання знижки

До страви яка коштує 249 грн застосовується скидка 40 грн. Страва:

{
   "sum":249,
   "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
   "count":1.0,
   "guest":"guest",
   "category":"Кухня",
   "category_id":"b4e30148-b13e-11ea-80e8-d8d9ff6efa94",
   "order_number":"000080526"
}

Знижка 40 грн:

"discounts":{
   "list":[
      {
         "id":"id",
         "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
         "sum":40
      }
   ]
}

При застосуванні знижки до страви(страв), потрібно змінювати sum цієї страви(страв) і вираховувати totalSum відповідно до застосованих знижок. Тобто сума після застосування знижки має виглядати так:

}   
   "sum":209,
   "name":"Індичка у вершковому соусі з грибами, томатами кімчі",
   "count":1.0,
   "guest":"guest",
   "category":"Кухня",
   "category_id":"b4e30148-b13e-11ea-80e8-d8d9ff6efa94",
   "order_number":"000080526"
}

---