POS QR Codes

This page explains how to generate QR codes in the POS, giving the integration more control over the customer experience.

How it works

The POS creates a QR code (even offline if needed) that the customer scans. The QR code format is described in the QR Code section.
The customer scans the code, and the data is sent to the POS. The POS receives the decoded payload via the searchBills method and responds with the matching bills.

Required data

Provide the following values during setup:

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.
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 URL format described below.
Include the Qerko logo. Production Pos-Ids are issued only when the logo is present.

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 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

The POS receives the following payload:

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

QR Generator

Use Qerko’s QR generator to produce the final QR code with the required logo, or use your own generator and ensure the logo is embedded.

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>

Use the production URL in live environments once it is deployed.

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.

Parameter	Type	Description
`id`	`string`	The restaurant’s primary key. It will never change.
`name`	`string`	The restaurant’s human-readable name.
`variableSymbol`	`string`	Variable symbol used to identify payments.
`identificationNumber`	`string`	Identification number, also known as IN or IČO in Czech.
`taxIdentificationNumber`	`string` or `null`	Tax identification number, also known as TIN or DIČ in Czech.
`longitude`	`float`	GPS coordinate of the restaurant.
`latitude`	`float`	GPS coordinate of the restaurant.
`address`	`string`	Restaurant’s address.

Need help? Contact techsupport@qerko.com for assistance.

Loyalty cards Qerko for e-shop