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
- 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.
- 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.
- The API key
POS still needs to be conencted to Qerko API using websocket or long-polling. API key is needed there. idRestaurant
POS can download theidRestuarant
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
asidRestaurant
. In reality it is GUID.customer-1
asidCustomer
. In reality it is GUID.{ "param1": "foo", "param2": "bar" }
asdata
. 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.
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 abbr IN or IČO in czech language. |
taxIdentificationNumber | string``null | Tax identification number, also known as abbr TIN or DIČ in czech language. |
longitude | float | GPS coord of the restaurant |
latitude | float | GPS coord of the restaurant |
address | string | Restaurant's address |