Documentation
POS QR codes

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 can create a QR code (possible even offline), which will be scanned by custommers phone. The contents of this QR code is described in QR Code section below.
  2. Customer scand the code and the data will be sent to the POS. POS receives the data from the QR code to the method searchBills and should return a list of matched bills.

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
    POS can download the idRestuarant from the whoami method or it can be manually entered.

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

the QR code

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

Data structures

Follows a list of additional data structures.

Restaurant

This structure carries info about the restaurant.

ParameterTypeDescription
idstringThe restaurant's primary key. It will never change.
namestringThe restaurant's human readable name.
variableSymbolstringVariable symbol used to identify payments.
identificationNumberstringIdentification number, also known as abbr IN or IČO in czech language.
taxIdentificationNumberstring``nullTax identification number, also known as abbr TIN or DIČ in czech language.
longitudefloatGPS coord of the restaurant
latitudefloatGPS coord of the restaurant
addressstringRestaurant's address