REST API Interface
This section describes a set of endpoints for communicating between POS and Qerko using long-polling and REST API. You can choose to use websocket instead. It is still possible to use these endpoints while using websocket, except the long-polling endpoint.
Endpoints use standard HTTP protocol, version 1.1, using TLS (1.0 or newer). It is required to send SNI. You can skip this paragraph if you use a reasonably new HTTP client (usually a library).
All data is transferred in JSON format. Each restaurant can have only one and separated connection.
HTTP headers
POS must send these headers with every request.
Header name | Required? | Description |
---|---|---|
Accept-Language | no | Language for error messages. It doesn’t influence anything else. Default: en |
Authorization | yes | The API key with Bearer prefix.Example: Bearer abcd-efgh-ijkl-mnop-qrst |
Content-Type | no | With the value application/json . Required when sending payload to the server. |
Pos-Id | yes | Pos-Id assigned to your POS. See Production environment. |
GET /api/v2/pos/payment/<idPayment>
This request returns information about payment. This endpoint is provided to resolve various situations when POS missed the paymentClosed(…) call. This way POS can retrieve info about payment at any moment.
URL parameter | Description |
---|---|
idPayment | Identifier of payment |
Response
- status:
200 OK
‒ response contains canceled Payment - status:
401 Unauthorized
‒ invalid API key, or Pos-Id ‒ response contains Error - status:
403 Forbidden
‒ payment is from another restaurant ‒ response is empty - status:
404 Not Found
‒ payment doesn’t exist ‒ response is empty
Example
Request
GET /api/v2/pos/payment/1234 HTTP/1.1
Host: sandbox.qerko.com
Pos-Id: my-pos-id
Authorization: Bearer my-api-key
User-Agent: MyPos/1.0.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"additionalData": null,
"currency": "CZK",
"discount": null,
"id": "1234",
"idBill": "1",
"idCustomer": "aaf10f7b-730b-4283-9087-965060c6350a",
"items": [
{
"id": "156",
"minQuantity": "1",
"name": "Item 5,-",
"price": "5",
"quantity": "1",
"tags": ["Misc"]
}
],
"state": "PAID",
"parts": [
{
"total": "156",
"provider": {
"id": "qerko",
"name": "Qerko",
"type": "CARD"
}
}
],
"tipBrutto": "0",
"tipNetto": "0"
}
DELETE /api/v2/pos/payment/<idPayment>
Cancels the payment. Use this request to cancel the payment and return funds to the customer. Limited to 3 hours from payment creation.
URL parameter | Description |
---|---|
idPayment | Identifier of payment |
Response
- status:
200 OK
‒ response contains Payment - status:
401 Unauthorized
‒ invalid API key, or Pos-Id ‒ response contains Error - status:
403 Forbidden
‒ payment is from another restaurant ‒ response is empty - status:
404 Not Found
‒ payment doesn’t exist ‒ response is empty - status:
410 Gone
‒ limit for cancellation has expired ‒ response is empty
Example
Request
DELETE /api/v2/pos/payment/1234 HTTP/1.1
Host: sandbox.qerko.com
Pos-Id: my-pos-id
Authorization: Bearer my-api-key
User-Agent: MyPos/1.0.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"additionalData": null,
"currency": "CZK",
"discount": null,
"id": "1234",
"idBill": "1",
"idCustomer": "aaf10f7b-730b-4283-9087-965060c6350a",
"items": [
{
"id": "156",
"minQuantity": "1",
"name": "Item 5,-",
"price": "5",
"quantity": "1",
"tags": ["Misc"]
}
],
"state": "CANCELLED",
"parts": [
{
"total": "156",
"provider": {
"id": "qerko",
"name": "Qerko",
"type": "CARD"
}
}
],
"tipBrutto": "0",
"tipNetto": "0"
}
POST /api/v2/pos/payment/<idPayment>/capture
Capture the payment which was started in captureMode=manual
mode.
URL parameter | Description |
---|---|
idPayment | Identifier of payment |
Payload
See Receipt.
Response
- status:
200 OK
- status:
401 Unauthorized
‒ invalid API key, or Pos-Id ‒ response contains Error - status:
403 Forbidden
‒ payment is from another restaurant ‒ response is empty - status:
404 Not Found
‒ payment doesn’t exist ‒ response is empty
Example
Request
POST /api/v2/pos/payment/1234/capture HTTP/1.1
Host: sandbox.qerko.com
Pos-Id: my-pos-id
Authorization: Bearer my-api-key
User-Agent: MyPos/1.0.0
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"status": "Accepted"
}
POST /api/v2/pos/poll
This request provides a way for Qerko to be able to call methods in POS. This technique is called long-polling. You can use websocket instead. Do not use websocket and long-polling at once. Choose only one approach.
This request is held open until Qerko needs to call one of the methods. Qerko responds with info required to call a method. POS internally calls the method and sends the result in another request to this endpoint putting the response into payload.
Payload
None or MethodCallResponse if response is available. Response isn’t available if you are initiating a connection to Qerko. It is available when you have the return value from a method or you caught an error from a previous MethodCallRequest.
Response
- status:
200 OK
‒ response contains MethodCallRequest - status:
400 Bad Request
‒ you have sent something wrong ‒ response contains Error - status:
401 Unauthorized
‒ invalid API key, or Pos-Id ‒ response contains Error - status:
409 Conflict
‒ server ends connection because another concurrent connection has been open to the same restaurant ‒ response is empty - status:
503 Service Unavailable
‒ server is about to be restarted. Try again in 2 minutes ‒ response can contain various things and should be ignored
Example
Request #1
POST /api/v2/pos/poll HTTP/1.1
Host: sandbox.qerko.com
Pos-Id: my-pos-id
Authorization: Bearer my-api-key
User-Agent: MyPos/1.0.0
Response #1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"uuid": "xyz-1234-5678",
"method": "getTableContents",
"args": ["foo-table", "bar-customer"]
}
Request #2
POST /api/v2/pos/poll HTTP/1.1
Host: sandbox.qerko.com
Pos-Id: my-pos-id
Authorization: Bearer my-api-key
User-Agent: MyPos/1.0.0
Content-Type: application/json; charset=utf-8
{
"uuid":"xyz-1234-5678",
"calledMethod": "getTableContents",
"result": [{
"id": "the-bill-id",
"currency": "CZK",
"items": [{
"name": "Coca Cola",
"price": "5",
"quantity": "1"
}]
}]
}
Response #2
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"uuid": null,
"method": "noop",
"args": []
}