Documentation
Orders

Orders

Introduction

This page describes API for delivering orders directly to POS. We want to resolve the problem that restaurants have multiple tablets for every single ordering system. They have to hire a worker whose job is to operate those tablets and copy incoming orders to POS manually. Another problem is the need to fill the same menu into multiple systems.

Qerko wants to resolve it by cooperation with POS systems. Everyone in the restaurant uses POS and accepting an orders and their lifecycle should be as easy as pressing an accept button. Menu should be automatically synchronized so no need to fill the menu manually.

In order to make it work we need to make following steps. We recomend to implement in this order too :).

  1. Menu synchronization
  2. Orders and their lifecycle

General

Please make sure that your implementation doesn't throw error if there are additional unknown parameters in structures. This will allow us to improve the API. We will test your implementation before any major change and if your implementation throws error on a new parameter then this limits us significantly.

Menu synchronization

The job is clear. We need to make sure, that Qerko has the correct and up-to-date menu. Qerko shows it in mobile app to the customers who make orders. Qerko also caches menu to minimize performance requirements on the POS side.

Synchronization may be started by both sides:

POS should sync whenever there is important change to the menu. For example when a meal becomes out-of-stock, new meal is added to the menu or an existing meal is removed from the menu.

Qerko syncs menu when we encounter certain errors in orderStart() method or orderPrepare() method. See Error codes of orderPrepare() method. Or after a while. Currently every 2 minutes, but only if there is a customer asking for the menu. The TTL of the cached menu will most probably change in the near futurue. We want to maximize it to minimize asking POS for menu.

Because it is only one-way synchronization (from POS to Qerko), no other steps are needed.

Orders and their lifecycle

Order is submited by a customer. He picks his meal from the menu and submits it. The customer can be sitting in the restaurant and he wants just another beer (delivery toBill/toTable) or he can be sitting in his livingroom and wants to pickup the order later (delivery byCustomer) or he wants the order to be delivered to him (delivery byOperator).

Don't worry. You can support only subset of delivery types :).

Delivery byOperator is not ready yet. If you want to use it, please contact Qerko.

  1. orderPrepare() method is called. This method can change the order and/or offer additional discounts/upsells. When the customer decides to accept upsell or changes items by any other way then orderPrepare() method is called again.
  2. orderStart() method is called. This method submits the order to the POS. The order won't change any more. It can be accepted or rejected. POS returns the state in which the order will be afterwards.
  3. Optionally orderMarkAsPaid() method is called. This method is called to announce that the customer has paid the order in advance. Standard Qerko payment is passed to this method. Right now it is called when delivery byCustomer is used.
  4. orderClose() method is called. This method is called when the order process is finished.

(Methods orderStart, orderMarkAsPaid, orderClose are analogous to the basic payment methods paymentStart, paymentProcessed, paymentClose.)

When the order is submitted its lifecycle continues. The order has a status which represents the current phase of the order. When the order is submited the work starts. The cook has to prepare the order and optionally the operator has to deliver it. So states are:

  • OrderWaiting - The order is waiting for restaurant personel to accept it. POS should show a dialog where the personel can accept the order.
  • OrderPreparing - The order is accepted and the cook is working on it.
  • ReadyForPickUp - The cook has finished his job and the order is waiting for the customer/operator to pick it up. Relevant for deliveries: byCustomer, byOperator
  • Completed - The order is completed and picked up/sent
  • Cancelled - The order is cancelled

When the status changes POS should call updateQerkoOrderStatus() method. No need to support all statuses. Qerko won't change the status itself. POS is always changing the status. Technically it is possible to switch status to any other status. The only limitation is Cancelled status. The order remains Cancelled no matter what. Switching the order to Cancelled also returns money to the customer.

Methods

Method signatures use ​TypeScript​ syntax for documentation purposes.

POS Methods

Below is a list of methods which can be called by Qerko. POS must implement these methods.

All of these methods supports error code ERROR_MESSAGE which shows returned error message to the customer. But try to use specific error codes where possible.

getMealMenus()

getMealMenus(): MealMenus

Qerko calls this method when it needs to get fresh menu from the POS. POS should respond with up-to-date menu. This method accepts no arguments.

This method returns MealMenus structure which should contain up-to-date menu.

Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getMealMenus",
    "args": []
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getMealMenus",
    "result": {
        "menus": [{
            "id": "the-menu",
            "currency": "CZK",
            "deliveryTypes": [ "toTable", "toBill" ],
            "categories": [
                {
                    "id": "category-1",
                    "name": "Daily offer",
                    "description": "Meals served from 11 AM to 3 PM.",
                    "orderableTimeSlots": [{
                        "startTime": "11:00:00",
                        "endTime": "15:00:00"
                    }],
                    "items": [
                        {
                            "id": "item-1",
                            "name": "Vegetable soup",
                            "description": "Boiled potatoes and a few more ingredients.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }, {
                            "id": "item-2",
                            "name": "T-bone steak",
                            "description": "Slice of cow's leg with the bone \"eye\" inside.",
                            "price": "145",
                            "inStock": true,
                            "modifiers": [
                                {
                                    "id": "ab4a054a-5a0a-48fe-947b-f5c23a566bbe",
                                    "minSelected": 1,
                                    "maxSelected": 1,
                                    "maxCount": 1,
                                    "name": "Steak Doneness",
                                    "options": [
                                        {
                                            "id": "b7055208-0827-4eca-8542-bd6d3b99252a",
                                            "menuItemId": "rare",
                                            "defaultSelected": 0,
                                            "addPrice": "0",
                                            "maxCount": 1
                                        },
                                        {
                                            "id": "92d8519f-4cba-4c45-a8fb-989200d50d54",
                                            "menuItemId": "medium",
                                            "defaultSelected": 1,
                                            "addPrice": "0",
                                            "maxCount": 1
                                        }
                                    ]
                                }
                            ],
                            "type": "sale"
                        }
                    ]
                },{
                    "id": "category-2",
                    "name": "Drinks",
                    "description": "Drinks served all the time.",
                    "items": [
                        {
                            "id": "item-3",
                            "name": "Coca-Cola",
                            "description": "We all know it. Ice-cold black sweet drink with bubbles.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }, {
                            "id": "item-4",
                            "name": "Beer",
                            "description": "Czech classic beer from Pilsen.",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "sale"
                        }
                    ]
                },
                {
                    "id": "modifiers",
                    "name": "modifiers",
                    "description": "This catogory is for modifier items and won't be showed in application",
                    "items": [
                        {
                            "id": "medium",
                            "name": "Medium",
                            "description": "This item will be hidden in application",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "modifier"
                        },
                        {
                            "id": "rare",
                            "name": "Rare",
                            "description": "This item will be hidden in application",
                            "price": "45",
                            "inStock": true,
                            "modifiers": [],
                            "type": "modifier"
                        }
                    ]
                }
            ],
            "minOrderTime": 0,
            "maxOrderTime": 0
        }],
        "deliveryInfos": [
            {
                "type": "byOperator",
                "paused": false
            },
            {
                "type": "byCustomer",
                "paused": false,
            },
            {
                "type": "toTable",
                "paused": false
            },
            {
                "type": "toBill",
                "paused": false,
            },
        ],
    }
}

orderPrepare()

orderPrepare(args: object): object

Qerko calls this method as a zero-th step of an order. The order is not submitted by the customer yet, but he has reached a summary before the final submission. This is the moment where he might want to apply a discount, accept an upsell offer, etc. POS can pre-validate the order and offer upsell and/or discounts.

This method can be called multiple times for one order.

Offering discounts and upsells is not ready in this moment. Please contact Qerko if you want to use this feature.

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128ID of the order which might be assigned in the previous call.
customerIdNonull / string length: 1 - 128ID of the customer. It is not required because the customer might not be logged in yet.
orderDeliveryYesOrderDeliveryToTable, OrderDeliveryToBill, OrderDeliveryByCustomer, OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg:  { "deliveryType": "toBill", "billId": "xyz" }
itemsYesOrderItem[] items: 1 - 256Ordered items._Eg: [{ "mealId": "m2c1i1001" }]

Returns (the same structure as in the input):

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128POS can set this to an identifier and Qerko will pass it to next call of this method or to orderStart method.
orderDeliveryYesOrderDeliveryToTable OrderDeliveryToBill OrderDeliveryByCustomer, OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg: { "deliveryType": "toBill", "billId": "xyz" }
allowTipNobooleanCan the customer add a tip? Default: true
denyDiscountsNobooleanWhether Qerko can apply another discount. Set it to TRUE when there already is an internally applied discount by POS and other discounts are unwanted. This is related to discounts provided by restaurant owners only. Discounts paid by Qerko or third parties (sponsors like breweries) aren't affected by this property. FALSE ‒ Qerko can apply a discount. TRUE ‒ Qerko can’t apply a discount. Default: false

TIP: You can just return unchanged input.

Error codes
  • ITEM_NOT_AVAILABLE

    • Qerko announces that an item is not availible any more and suggests to the custommer to make a new order.
    • Qerko tries to update the menu
  • INVALID_ITEM_PRICE

    • Qerko announces that prices have been changed and suggests to the custommer to make a new order.
    • Qerko tries to update the menu
  • BILL_LOCKED

    • Qerko announces that there is a waiter operating with the bill right now and suggest to the customer to try the order afterwards.
  • BILL_NOT_FOUND

    • Qerko announces that there is a waiter operating with the bill right now and suggest to the customer to try the order afterwards.
  • TABLE_NOT_FOUND

    • Qerko announces that the table doesn't exist any more and suggests to the custommer to make a new order.
  • BILL_CLOSED

    • Qerko announces that the bill was closed and it is not possible to make an order to this bill.
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderPrepare",
    "args": [{
        "orderId": "id-order-124",
        "items": [
            { "mealId": "m2c1i1001" }
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }]
}
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderPrepare",
    "result": {
        "orderId": "id-order-124",
        "items": [
            { "mealId": "m2c1i1001" }
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }
}

orderStart()

orderStart(args: object): object

Qerko calls this method as a first step of an order. The customer has just submitted the order. The order won't change any more except its status. POS should validate it in this step. POS returns orders and their lifecycle status. Suggested statuses are OrderWaiting, or OrderPreparing.

ParameterRequiredTypeDescription
orderIdNostring length: 1 - 128ID of the order which might be assigned in the previous orderPrepare().
customerIdYesstring length: 1 - 128ID of the customer.
calculatedPriceYesstring regexp: ^\d{1,6}(?:\.\d{1,3})?$ length: 1 - 10Calculated price for items. Eg: "129.66"
orderDeliveryYesOrderDeliveryToTable OrderDeliveryToBill OrderDeliveryByCustomer OrderDeliveryByOperatorStructure with details regarding the order delivery. See the specific type for details. Eg: { "deliveryType": "toBill", "billId": "xyz" }
itemsYesOrderItem[] items: 1 - 256Ordered items. Eg: [{ "mealId": "m2c1i1001" }]
orderDateTimeYesstring length: 1 - 25Marks the time the order has been placed in the Qerko app in the following format: 'yyyy-mm-ddTHH:MM:SS+HH:MM' Eg: "2022-03-21T14:41:50+01:00"

Returns:

ParameterRequiredTypeDescription
orderId Yesstring length: 1- 128Identifier of the created order.
billId Nostring length: 1- 128Required for delivery type toTable. It is the identifier of the created bill to which ordered items were added.
orderReferenceNostring length: 1- 128Could be used as code for pickup for delivery type byCustomer or byOperator
status YesstringOne of - OrderWaiting - OrderPreparing - ReadyForPickUp - Completed - Cancelled See Orders and their lifecycle section for details.
Error codes

The same as in orderPrepare method

Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderStart",
    "args": [{
        "calculatedPrice": "129.34",
        "items": [
            { "mealId": "m2c1i1001" }calculatedPrice
        ],
        "orderDelivery": {
            "deliveryType": "toBill",
            "billId": "xyz"
        }
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderStart",
    "result": {
        "orderId": "id-order-124",
        "status": "OrderWaiting"
    }
}

orderMarkAsPaid()

orderMarkAsPaid(args: Payment): Receipt

Qerko calls this method is an optional second step of an order. This method marks the order as paid. It receives the Payment object with a few modifications - orderId is used instead of idBill and the items property contains an array of Order items instead of BillItems. It returns a Receipt. Analogous to the paymentProcessed method in base.pdf.

The payment always pays for the whole order. Never only part of it.

Any error cancels the order.

orderClose()

orderClose(args: object): null

Qerko calls this method is a final step of an order. Error in this method won't cancel the order. Analogous to the paymentClose method in payments.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order which was assigned in paymentStart() method.
statusYesstringOne of: OK - Success the order was successfuly ordered, Cancelled - Something went wrong. The order is cancelled.
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderClose",
    "args": [{
        "orderId": "id-order-124",
        "status": "OK"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderClose",
    "result": null
}

orderStatus()

orderStatus(args: object): object

Qerko calls this method as a first step of an order. The customer has just submitted the order. The order won't change any more except its status. POS should validate it in this step. POS returns orders and their lifecycle status. Suggested statuses are OrderWaiting, or OrderPreparing.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order status of which should be returned.

Returns:

ParameterRequiredTypeDescription
StatusYesstringOnde of: - OrderWaiting - OrderPreparing - ReadyForPickUp - Completed - Cancelled See Orders and their lifecycle section for details
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "orderStatus",
    "args": [{
        "orderId": "123"
    }]
}
 
/** Method call response (sent by POS) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "orderStatus",
    "result": {
        "status": "OrderWaiting"
    }
}

getResource()

getResource(args: object): object

Qerko calls this method to get resource from the POS. Resources are images for now. This method receives a string idResource which was sent in MenuItem .images array. This method returns structure, which contains mime-type and of course the data of the resource.

Qerko can download all resources immediately after menu sync or any time after. Qerko wil cache the resource. If you want to update the resource send another idResource.

ParameterRequiredTypeDescription
idResourceYesstring length: 1 - 128String idResource which was sent in MenuItem.images array.

Returns

ParameterRequiredTypeDescription
mimeYesstringOne of: _ image/png - PNG format. _ image/jpeg - JPEG format.
dataYesstring length: 0 - 1000000Base64 encoded data. Size of the image in B64 encoding is 1MB (1000000 bytes). It means max file size 750kB (750000 bytes) using B64 encoding, without padding and line ends.
Example
/** Method call request (sent by Qerko) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getResource",
    "args": [{
        "idResource": "C:\\POS\\images\\the-product.jpg::lastMod=1234567890"
    }]
}
 
/** Method call response (sent by POS) */1000000
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getResource",
    "result": {
        "mime": "image/jpeg",
        "data": " ... JPEG data in Base64 ..."
    }
}

Qerko Methods

Below is a list of methods which can be called by POS using ​websocket​ or REST endpoint. Qerko implements them.

updateMenus()

updateMenus(menus: MealMenus): null

POS calls this method to perform synchronization of menu whenever there is an important change in the menu. It accepts the same structure as is returned by getMealMenus() method.

Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "updateMenus",
    "args": [{
        "menus": [{
            "id": "the-menu",
            "currency": "CZK",
            "deliveryTypes": [ "toTable", "toBill" ],
            "categories": [
                {
                    "id": "category-1",
                    "name": "Daily offer",
                    "description": "Meals served from 11 AM to 3 PM.",
                    "orderableTimeSlots": [{
                        "startTime": "11:00:00",
                        "endTime": "15:00:00"
                    }],
                    "items": [
                        {
                            "id": "item-1",
                            "name": "Vegetable soup",
                            "description": "Boiled potatoes and a few more ingredients.",
                            "price": "45",
                            "tagIds": [ "tag-1", "tag-2" ],
                            "inStock": true
                        }, {
                            "id": "item-2",
                            "name": "T-bone steak",
                            "description": "Slice of cow's leg with the bone \"eye\" inside.",
                            "price": "145",
                            "inStock": true
                        }
                    ]
                },{
                    "id": "category-2",
                    "name": "Drinks",
                    "description": "Drinks served all the time.",
                    "items": [
                        {
                            "id": "item-3",
                            "name": "Coca-Cola",
                            "description": "We all know it. Ice-cold black sweet drink with bubbles.",
                            "price": "45",
                            "inStock": true
                        }, {
                            "id": "item-4",
                            "name": "Beer",
                            "description": "Czech classic beer from Pilsen.",
                            "price": "45",
                            "inStock": true
                        }
                    ]
                }
            ],
            "minOrderTime": 0,
            "maxOrderTime": 0
        }],
        "deliveryInfos": [
            {
                "type": "byOperator",
                "paused": false
            },
            {
                "type": "byCustomer",
                "paused": false,
            },
            {
                "type": "toTable",
                "paused": false
            },
            {
                "type": "toBill",
                "paused": false,
            },
        ],
    }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "updateMenus",
    "result": null
}
Long-polling

Request:

POST /api/v2/pos/update-menus HTTP/1.1
Host: sandbox.qerko.com
Content-Type: application/json
Pos-Id: my-pos-id
Authorization: Bearer foo-bar-api-key

{
    "menus": [{
        "id": "the-menu",
        "currency": "CZK",
        "deliveryTypes": [ "toTable", "toBill" ],
        "categories": [
            {
                "id": "category-1",
                "name": "Daily offer",
                "description": "Meals served from 11 AM to 3 PM.",
                "orderableTimeSlots": [{
                    "startTime": "11:00:00",
                    "endTime": "15:00:00"
                }],
                "items": [
                    {
                        "id": "item-1",
                        "name": "Vegetable soup",
                        "description": "Boiled potatoes and a few more ingredients.",
                        "price": "45",
                        "tagIds": [ "tag-1", "tag-2" ],
                        "inStock": true
                    }, {
                        "id": "item-2",
                        "name": "T-bone steak",
                        "description": "Slice of cow's leg with the bone \"eye\" inside.",
                        "price": "145",
                        "inStock": true
                    }
                ]
            },{
                "id": "category-2",
                "name": "Drinks",
                "description": "Drinks served all the time.",
                "items": [
                    {
                        "id": "item-3",
                        "name": "Coca-Cola",
                        "description": "We all know it. Ice-cold black sweet drink with bubbles.",
                        "price": "45",
                        "inStock": true
                    }, {
                        "id": "item-4",
                        "name": "Beer",
                        "description": "Czech classic beer from Pilsen.",
                        "price": "45",
                        "inStock": true
                    }
                ]
            }
        ],
        "minOrderTime": 0,
        "maxOrderTime": 0
    }],
    "deliveryInfos": [
        {
            "type": "byOperator",
            "paused": false
        },
        {
            "type": "byCustomer",
            "paused": false,
        },
        {
            "type": "toTable",
            "paused": false
        },
        {
            "type": "toBill",
            "paused": false,
        },
    ],
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{}

updateQerkoOrderStatus()

updateQerkoOrderStatus(args: object): object

POS calls this method to set another status of the order. Beware setting the order to Cancelled status is irreversible and will return money to the customer.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order which was assigned in paymentStart() method.
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
collectionDateTimeNostringWhen will the order be availible for pickup Eg: "2020-01-30T23:42:42Z"

Returns:

ParameterRequiredTypeDescription
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "updateQerkoOrderStatus",
    "args": [{
        "collectionDateTime": "2020-01-30T23:42:42Z",
        "orderId": "order-1",
        "status": "Completed"
    }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "updateQerkoOrderStatus",
    "result": {
        "status": "Completed"
    }
}
Long-polling

Request:

POST /api/v2/pos/update-qerko-order-status HTTP/1.1
Host: sandbox.qerko.com
Content-Type: application/json
Pos-Id: my-pos-id
Authorization: Bearer foo-bar-api-key

{
    "orderId": "the-order-id",
    "status": "OrderPreparing",
    "collectionDateTime": "2021-05-06T12:22:49Z"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "status":"OrderPreparing" }

getQerkoOrderStatus()

getQerkoOrderStatus(args: object): object
Error Codes
  • NOT_FOUND
    • We couldn't find specified order. For POS it means that the order is cancelled. Something could go so wrong, that the order is just lost.

POS calls this method to set another status of the order. Beware setting the order to Cancelled status is irreversible and will return money to the customer.

ParameterRequiredTypeDescription
orderIdYesstring length: 1 - 128ID of the order which was assigned in paymentStart() method.

Returns

ParameterRequiredTypeDescription
statusYesstringOne of OrderWaiting, OrderPreparing, ReadyForPickUp, Completed, Cancelled. See Orders and their lifecycle section for details.
paymentStatusNostringState of related payment, if the order was marked as paid. One of STARTED, PROCESSING, PAID, CANCELLED, ERROR.
Example
Websocket
/** Method call request (sent by POS) */
{
    "type": "method-call-request",
    "uuid": "call-uuid",
    "method": "getQerkoOrderStatus",
    "args": [{ "orderId": "order-1" }]
}
 
/** Method call response (sent by Qerko) */
{
    "type": "method-call-response",
    "uuid": "call-uuid",
    "calledMethod": "getQerkoOrderStatus",
    "result": {
        "status": "Completed",
        "paymentStatus": "PAID"
    }
}
Long-polling

Request:

POST /api/v2/pos/get-qerko-order-status HTTP/1.1
Host: sandbox.qerko.com
Content-Type: application/json
Pos-Id: my-pos-id
Authorization: Bearer foo-bar-api-key

{ "orderId": "the-order-id" }

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{ "status": "OrderPreparing", "paymentStatus": "PAID" }

Data structures

Follows a list of data structures, which are used for data exchange between POS and Qerko.

DeliveryAddress

This represent delivery address.

PropertyRequiredTypeDescription
nameYesstringT. Pavlacký
phoneYesstring+420602341203
emailNostringtomas.pavlacky@gmail.com
streetYesstringPivovarská 3
postcodeYesstring15000
cityYesstringPraha 5
latitudenostring38.8951
longitudenostring-77.0364

OrderItem

This represent order item.

PropertyRequiredTypeDescription
mealIdYesstring length: 1 - 128Identifier of the menuItem.id.
modifiersNoOrderItemModifier[] items: 0 - 256Modifiers of the item. Default: [] (empty array) Eg: medium-rare
portionIdNostring length: 0 - 128This feature is unimplemented. Contact Qerko if you need to use it. Id of portion Default: "" (empty string) Eg: "portion-10"
priceNostring regexp: ^\d6(?:\.\d3)?$ length: 0 - 10Price of the item without used modifiers.

OrderItemModifier

This represent modifier in order item.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the modifier.
selectedOptionsYesOrderItemModifierOption[]Selected options of modifiers. Eg: "raw", "medium"

OrderItemModifierOption

This represent option of modifier in order item.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the modifier option.
itemYesOrderItemOrderItem which is used as modifier

Category

This represent menu category. Menus are divided into categories which contains menu items.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the category.
nameYesstring length: 1 - 128Human readable name. Should be short. _Eg: "Drinks""Soups", ...
descriptionNostring length: 0 - 256Human readable description. Default: "" (empty string) Eg: "These are our delicious homebrewn drinks."
itemsNoMenuItem[] items: 0 - 256List of items in this category. Default: [] (empty array)
orderableTimeSlotsNoOrderableTimeSlot[] items: 0 - 256Slot when it is possible to order items from this category. It can only further limit `orderableTimeSlots` from the whole menu. Default: unlimited

MenuItem

This represents one orderable item.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the item. You will receive this in order as `mealId`.
nameYesstring length: 1 - 128Human readable name. Should be short
inStockYesbooleanIs item available (= true) or sold-out (= false)?
priceYesstring regexp: ^\d{1,6}(?:\.\d{1,3})?$Total price for this items including taxes.
typeYesstringType of menuItem. Possible values: "sale" - Item can be ordered alone."modifier" - Item is hidden in application and can be ordered only like modifier.
alergensNostring[] items: 0 - 256This feature is unimplemented. Contact Qerko if you want to use it. List of alergens. Can be numbers or short texts. Default: [] (empty array) Eg: ["10"], or ["Mustard"], or ["10 - Mustard"]
descriptionNostring length: 0 - 512Human readable description. Default: "" (empty string) Eg: "The best drink on Earth. Our bartender has spent a lot of effort to prepare this. Get ready for the best time of your life while drinking it."
deliveryTypesNostring[] items: 1 - 4 unique itemsList of allowed delivery types. It can only further limit deliveryTypes of the whole menu. Possible values: "toTable""toBill""byCustomer""byOperator" Notice: byOperator is unimplemented. Contact Qerko if you want to use it.
imagesNostring[] length: 1 - 2000 items: 0 - 10This is list of resourceIds. See getResource() method. Qerko will use these IDs to pull the resources when they are needed. Menu can be quite lengthy and we don't want to overload the connection with hundreds of images :). Default: [] (empty array)
modifiersNoMenuItemModifier[] items: 0 - 256Modifiers that are available for this item Default: [] (empty array) Eg: medium-rare
portionsNoPortion[] items: 0 - 256This feature is unimplemented. Contact Qerko if you need to use it. Variant of the item which should influence its size. Default: [] (empty array) Eg: child-portion
tagIdsNostring[] length: 1 - 128 items: 0 - 1000This feature is unimplemented. Contact Qerko if you need to use it. List of tags. Should reference MealMenus.listTags. Default: [] (empty array)

MenuItemModifier

This represent modifier in menu item.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the modifier.
minSelectedYesnumber range 0 - 65635Minimum count of selected unique options
maxSelectedNonumber / null range 1 - 65635Maximum count of selected unique options. Default null. If null then unlimited.
maxCountYesnumber range: 1 - 65635Maximum count of selected non-unique options.
nameYesstring length: 1 - 128Name of modifier. Eg. "Pick steak doneness"
optionsYesMenuItemModifierOption[]Modifier options. Eg. "medium rare" "raw"

MenuItemModifierOption

This represent option of a modifier in menu item.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the modifier option.
menuItemIdYesstringID of menuItem which will be used like modifier option value.
addPriceYesstringPrice of option, which will be added to final orderItem. This price overrides price of the menuItem linked by menuItemId.
defaultSelectedNonumber/ nullNumber of default selected items. Default null.
maxCountNonumber /nullMaximum number of selections for this option. Default null. If null then unlimited.

MealMenus

This structure contains a collection of menus. There can be multiple menu alternatives because of different currencies, languages and delivery options.

PropertyRequiredTypeDescription
menusYesOneMealMenu[] items: 0 - 256Array of menu alternatives. Items have tagIds which points to this array. Default: [] (empty array)
listTagsNoTag[] items: 0 - 256This feature is unimplemented. Contact Qerko if you need to use it. Array of tags which are used in the menu. Items have tagIds which points to this array. Default: [] (empty array)
deliveryInfosYesDeliveryInfo[] items: 0 - 4 unique itemsDelivery info effects availability of delivery type for the restaurant. If Delivery info for delivery type is missing it means that delivery type is disabled.

OneMealMenu

This sturcrure represents one menu alternative for concrete language, currency and set of delivery types

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the menu.
categoriesYesCategory[] items: 0 - 256List of categories which further contains menu items. Default: [] (empty array)
currencyYesstring length: 3Currency code according to ISO 4217 (opens in a new tab). Eg: "CZK"
deliveryTypesYesstring[] items: 1 - 4 unique itemsList of allowed delivery types. Possible values: "toTable" - The order can be added to the table as a new open bill. "toBill" - The order can be added to the existing bill. "byCustomer" - The order can be picked up by customer. Used in takeaway windows. "byOperator" - The order can be delivered to given address. This is unimplemented. Contact Qerko if you want to use it.
minOrderTimeYesnumber value: 0 - 2147483647Minimum order postpone time in minutes. Minimum: 0 (Setting the order times to zero means the time of the pickup can be picked by the user.) Eg: 10 - it means that the customer can express his preference of pickup time to be in 10 minutes or later.
maxOrderTimeYesnumber value: 0 - 2147483647Maximum order postpone time in minutes. See TIP below this table. Minimum: 0 (Setting the order times to zero means the time of the pickup can be picked by the user.) Eg: 30 - it means that the customer can express his preference of pickup time to be in 30 minutes or before.
langYesstring length: 2ISO 639-1 (opens in a new tab) language code. Default: universal Eg: "cs"
orderableTimeSlotsNoOrderableTimeSlot[] items: 0 - 256Slot when it is possible to order items from this menu. Default: unlimited

TIP: maxOrderTime should be less than (real closing time - end of orders), eg:

  • restaurant closes at 9 PM
  • ordering ends in 8 PM (orderableTimeSlots.endTime = 20:00:00) because kitchen closes at 8:30 PM
  • then: maxOrderTime should be max 60 (minutes). Otherwise there is danger that the customer arrives when the restaurant will be closed.

OrderableTimeSlot

This structure represents a timespan from to which is used to allow orders.

PropertyRequiredTypeDescription
startTimeYesstring length: 8Start time of this timespan. Timezone is handled by Qerko configuration, because this isn't timezoned information. The restaurant usualy opens in 11 AM regardless of summer or winter time. Eg: "11:00:00"
endTimeYesstring length: 8Start time of this timespan. Timezone is handled by Qerko configuration, because this isn't timezoned information. The restaurant usualy closes in 11 PM regardless of summer or winter time. Eg: "23:00:00"
startDateNostring length: 10 nullStart date of this timespan. Use dates only if there is some sort of speciality in opening hours like New years eve. Or if it is special category like daily menu. Default: null, means every day Eg: "2021-03-02"
endDateNostring length: 10 nullEnd date of this timespan. Use dates only if there is some sort of speciality in opening hours like New years eve. Or if it is special category like daily menu. Default: null, means every day Eg: "2021-03-02"

OrderDeliveryByOperator

This structure holds info about delivery by operator. This means classic delivery as known from Uber Eats, Wolt, Dáme jídlo, etc.

PropertyRequiredTypeDescription
customerYesDeliveryAddress AddressAddress where to deliver
deliveryTypeYesstringConstant value - "byOperator"
collectionNotesNostring length: 0 - 256Customers note meant for the operator. Eg: "Leave the package under the bridge."
kitchenNotesNostring length: 0 - 256Customers note meant for the cook. Eg: "Shaken, not stirred."

OrderDeliveryByCustomer

This structure holds info for customers pickup. The customer will arive for the order to the restaurant.

PropertyRequiredTypeDescription
nameYesstring length: 0 - 128Name of the customer. Eg: "Miloslav M."
collectionDateTimeYesstringDate and time when the customer wants to arrive Eg: "2021-03-02T14:35:00.000+01:00"
deliveryTypeYesstringConstant value - "byCustomer"
collectionNotesNostring length: 0 - 256This feature is not yet implemented. Contact Qerko if you want to use it. Note regarding pickup Eg: "Wrap it into something special"
kitchenNotesNostring length: 0 - 256This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."
phoneNostringThis feature is not yet implemented. Contact Qerko if you want to use it. Phone to the customer. Eg: "+420123456789"

OrderDeliveryToTable

This structure holds info for delivery to table. This means that the customer is sitting in the restaurant and wants something delivered to the table. But he has no bil opened yet. POS should create new bill when the order is accepted.

PropertyRequiredTypeDescription
tableCodeYesstring length: 1 - 256Code of the table where the customer sits.
deliveryTypeYesstringConstant value - "toTable"
kitchenNotesNostring length: 0 - 256This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."

OrderDeliveryToBill

This structure holds info for delivery to table. This means that the customer is sitting in the restaurant and wants something delivered to the table. But he has already opened bill on the table, so ordered items should be added to existing bill.

PropertyRequiredTypeDescription
billIdYesstring length: 1 - 128Identifier of the customers bill.
deliveryTypeYesstringConstant value - "toBill"
kitchenNotesNostring length: 0 - 256This feature is not yet implemented. Contact Qerko if you want to use it. Customers note meant for the cook. Eg: "Shaken, not stirred."
tableCodeNostring length: 1 - 128Table identification

Payment

The difference from the default Payment structure is that there is OrderId used instead of idBill and the items property contains an array of Order items instead of BillItems.

Used in orderMarkAsPaid() method.

Receipt

Refers to the same structure as in Receipt data structure. Used in orderMarkAsPaid() method.

DeliveryInfo

This structure contains info about a supported delivery types.

PropertyRequiredTypeDescription
typeYesstringDelivery type identifier. Correct values are "toTable", "toBill", "byCustomer", "byOperator"
pausedYesbooleanShoud be true if ordering for delivery type is paused. Can be used if restaurant needs temporarily pause ordering for high demand or other issues.

Tag

This feature is not yet implemented. Contact Qerko if you want to use it.

This structure contains info about a tag. Tag is a label which will be displayed by the menu item. Some examples of tags could be Vegetarian, Local product, etc.

PropertyRequiredTypeDescription
idYesstring length: 1 - 128Identifier of the tag. Must be unique so items can reference exect tag.
nameYesstring length: 1 - 128Human readable name. Should be short. Eg: "Vegetarian"
descriptionNostring length: 0 - 256Human readable description. Eg: "This meal doesn't contain meat."