POS QR Codes

This page describes a mode where QR codes are generated by the POS. This gives the POS the freedom to handle many things independently.

How it works

1. The POS can create a QR code (possibly even offline), which will be scanned by the customer’s phone. The contents of this QR code are described in the QR Code section below.
2. The customer scans the code, and the data will be sent to the POS. The POS receives the data from the QR code via the searchBills method and should return a list of matched bills.

Required data

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

1. API key The POS still needs to be connected to the Qerko API using WebSocket or long-polling. The API key is required for this.
2. idRestaurant The POS can download the idRestaurant using the whoAmI method or it can be entered manually.

QR Code

The QR code generated by the POS must:

• Contain the following URL format to work.
• Contain the Qerko logo (this is mandatory and you won’t get a production Pos-Id without the logo).

Data

The contents of the QR code should be this URL:

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

Keep in mind that this should comply with the URL specification. The URL should be no longer than 2000 characters, so keep the data relatively short. Also, QR codes larger than 2 kB tend to be physically large.

Example

In this example we will use:

• restaurant-1 as idRestaurant (in reality, this is a GUID).
• customer-1 as idCustomer (in reality, this is a GUID).
• { "param1": "foo", "param2": "bar" } as data (the actual data is up to the POS).

Resulting URL:

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 the 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 is waiting for deployment.

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 methods available for this extension.

Qerko Methods

Below is a list of methods that can be called by the POS using ​WebSocket​ or the REST API​ endpoint.

whoAmI()

This method can be used to get info about restaurants whose API keys are used. If you have sent multiple API keys, 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

Below is a list of additional data structures.

Restaurant

This structure carries info about the restaurant.

Need help? If you get stuck or have questions, email us at techsupport@qerko.com—we’re here for you!