Documentation
REST-API Interface

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 nameRequired?Description
Accept-LanguagenoLanguage for error messages. (opens in a new tab) It doesn't influence anything else. Default: en
AuthorizationyesThe API key with Bearer prefix.
Example: Bearer abcd-efgh-ijkl-mnop-qrst
Content-TypenoWith the value application/json. Required when sending payload to the server.
Pos-IdyesPos-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 parameterDescription
idPaymentIdentifier 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 parameterDescription
idPaymentIdentifier of payment

Response

  • status: 200 OK ‒ response contains Payment
  • status: 401 Unauthorized ‒ invalid API key, or Pos-Id ‒ response contains Error
  • status: 403 Forbiddenpayment is from another restaurant ‒ response is empty
  • status: 404 Not Foundpayment 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": []
}