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 (opens in a new tab), version 1.1, using TLS (1.0 or newer) (opens in a new tab). It is required to send SNI (opens in a new tab). You can skip this paragraph if you use a reasonably new HTTP client (usually a library).

All data is transferred in JSON (opens in a new tab) 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. (opens in a new tab) 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/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": []
}

Environments Websocket interface