DocumentationREST-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, 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 nameRequired?Description
Accept-LanguagenoLanguage for error messages. 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 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 parameterDescription
idPaymentIdentifier 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": []
}
EnvironmentsWebsocket interface