REST API Interface

Available in API versions	`v1`, `v2`, `v3`

This section describes the endpoints that connect the POS to Qerko through long-polling and REST API calls. You can switch to the WebSocket interface if you prefer. The REST endpoints remain available even when you use WebSockets, except for the long-polling endpoint.

Endpoints use HTTP/1.1 over TLS 1.0 or newer and require SNI. Any modern HTTP client handles this automatically.

All data is transferred in JSON format. Each restaurant can maintain only one connection at a time.

HTTP headers

POS must send these headers with every request.

Header name	Required?	Description
Accept-Language	No	Language for error messages. Defaults to `en`.
Authorization	Yes	The API key with the `Bearer` prefix. Example: `Bearer abcd-efgh-ijkl-mnop-qrst`.
Content-Type	No	Use `application/json`. Required whenever you send a payload.
Pos-Id	Yes	POS ID assigned to your POS. See Production environment.

GET /api/v2/pos/payment/<idPayment>

This request returns payment details. Use it when the POS missed the paymentClosed(…) call so you can retrieve the payment state at any time.

URL parameter	Description
idPayment	Identifier of payment

Response

status: 200 OK - Response contains the canceled Payment.
status: 401 Unauthorized - Invalid API key or POS ID. Response contains Error.
status: 403 Forbidden - Payment belongs to another restaurant. Response is empty.
status: 404 Not Found - Payment doesn’t exist. Response is empty.

Example

Request

Compiling...

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 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 belongs to another restaurant. Response is empty.
status: 404 Not Found - Payment doesn’t exist. Response is empty.
status: 410 Gone - Cancellation window has expired. Response is empty.

Example

Request

Compiling...

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

Captures a payment that was started with captureMode=manual.

URL parameter	Description
idPayment	Identifier of payment

Payload

See Receipt.

Response

status: 200 OK - Capture succeeded.
status: 401 Unauthorized - Invalid API key or POS ID. Response contains Error.
status: 403 Forbidden - Payment belongs to another restaurant. Response is empty.
status: 404 Not Found - Payment doesn’t exist. Response is empty.

Example

Request

Compiling...

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "status": "Accepted"
}

POST /api/v2/pos/poll

This request lets Qerko call methods on the POS through long-polling. You can use the WebSocket interface instead, but choose only one approach—never run both at the same time.

The connection stays open until Qerko needs to call one of the methods. Qerko responds with the parameters required to invoke the method. The POS executes the method locally and sends the result in another request to this endpoint, providing the response in the payload.

Payload

None, or a MethodCallResponse when a response is available. The payload is empty when you initiate the connection to Qerko. Include a response once you have the return value from a method or you captured an error from a previous MethodCallRequest.

Response

status: 200 OK - Response contains a MethodCallRequest.
status: 400 Bad Request - The request is invalid. Response contains Error.
status: 401 Unauthorized - Invalid API key or POS ID. Response contains Error.
status: 409 Conflict - Another connection is already open for this restaurant. Response is empty.
status: 503 Service Unavailable - The server is about to be restarted. Try again in 2 minutes; any payload can be ignored.

Example

Request #1

Compiling...

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

Compiling...

Response #2

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
 "uuid": null,
 "method": "noop",
 "args": []
}

Need help? Contact techsupport@qerko.com for assistance.

Flows Websocket interface