Integration handbook for POS systems extension: POS QR Codes

This page describes a mode, where QR codes are generated by POS. It gives a freedom to the POS to do many things on its own.

How it works

1. The POS creates a QR code, which will be scanned by custommers phone. The contents of this QR code is described in QR Code section.
2. The phone talks with Qerko server and the data from the scanned QR code will be sent to the POS. POS have to identify the bill based on this data.
3. POS receives the data from the QR code into the method searchBills and should return a list of matched bills. A list with length 1 is still a list :).

Required data

This needs to be entered into the POS in the setup process.

1. The API key POS still needs to be conencted to Qerko API using websocket or long-polling. API key is needed there.
2. idRestaurant This is the primary key for the restaurant on Qerko side. Qerko needs it in order to be able to send QR data to the correct restaurant. POS must enable the restaurant to enter the idRestaurant along with the API key or POS can download the idRestuarant from the whoami method

QR Code

The QR code generated by POS must:

• contain following URL in order to work
• contain Qerko logo (This is mandatory and you won't get production Pos-Id without the logo)

Data

Contents of the QR code is this URL

https://qerko.com/~qr/pos/<idRestaurant>~<URL encoded data>

Keep in mind that this should still comply to URL spec. The URL should be no longer than 2000 characters, so keep the data relatively short. Besides 2 kB QR codes tends to be large.

Example

In this example we will use:

• restaurant-1 as idRestaurant. In reality it is GUID.
• customer-1 as idCustomer. In reality it is GUID.
• { "param1": "foo", "param2": "bar" } as data. Reality is up to POS.

Result URL is:

https://qerko.com/~qr/pos/restaurant-1~%7B%20%22param1%22%3A%20%22foo%22%2C%20%22param2%22%3A%20%22bar%22%20%7D

Message for POS will be:

{
    "type": "method-call-request",
    "method": "searchBills",
    "args": [
        "{ \"param1\": \"foo\", \"param2\": \"bar\" }", // qrIdentifier - The data - Qerko removes the URL encoding
        "customer-1", // idCustomer - As described in the extension-direct-bills.pdf
    ]
}

QR Generator

You can use Qerko's QR generator to generate the QR code visual. It will take care of adding the logo. Or you can use your own qr-generator, but the logo is mandatory.

https://qr-generator.qerko.com/?theme=logo&contents=<URL encoded contents - the whole URL>
https://qr-generator-sandbox.qerko.com/?theme=logo&contents=<URL encoded contents - the whole URL>

In production definitely use the first URL. It will work soon. It waits for deploy.

Example

https://qr-generator.qerko.com/?theme=logo&contents=https%3A%2F%2Fqerko.com%2F~qr%2Fpos%2Frestaurant-1~%257B%2520%2522param1%2522%253A%2520%2522foo%2522%252C%2520%2522param2%2522%253A%2520%2522bar%2522%2520%257D

Methods

This section describes additional method availible for this extension.

Qerko Methods

Follows a list of methods which can be called by POS using ​websocket​ or using an endpoint REST API​.

whoAmI()

This method can be used to get info about restaurants whose API keys are used. If you have sent multiple API keys then there will be multiple restaurants (Undocumented feature).

Endpoint

GET /api/v2/pos/who-am-i

Returns:

• HTTP 200 - response Restaurant structure (REST API doesn't support multiple API keys)
• HTTP 401 - invalid API key

Method

whoAmI()

• Args: <none>
• Returns: Restaurant[]

Data structures

Follows a list of additional data structures.

Restaurant

This structure carries info about the restaurant.