Websocket Interface
This section describes a protocol for communication between POS and Qerko using a websocket. It is an alternative to the use of REST API. It is still possible to receive calls using websocket and use REST API for POS initiated requests (e.g. cancel payment endpoint).
Websockets are used according to RFC-6455 specification. We use websocket-over-TLS for security (handshake is made through HTTPS).
All data is transferred in JSON (opens in a new tab) format.
Each restaurant can have only one and separated connection.
WEBSOCKET wss://…/api/v2/pos/ws
Using this endpoint, POS can open a websocket connection to Qerko. This creates a duplex connection so POS can send messages to Qerko and Qerko can send messages to POS. This request provides a way for Qerko to be able to call methods in POS. Duplex websocket connection is an alternative to long-polling. Do not use websocket and long-polling at once. Choose only one, which fits best to you.
Response HTTP statuses
During opening websocket connection you can receive these http status codes:
- status:
503 Service Unavailable‒ server is about to be restarted. Try again in 2 minutes ‒ response can contain various things and should be ignored
Websocket close codes
Websocket connection can be terminated by these socket codes. Don't confuse it with http statuses, see CloseEvent (opens in a new tab).
- status:
1001 Going Away‒ Our server needs to restart the connection. You should try to reconnect immediately. It can happen, for example, when we are releasing an upgrade without downtime. - status:
4503 Service Unavailable‒ server is about to be restarted. Try again in 2 minutes ‒ response can contain various things and should be ignored - status:
4401 Unauthorized‒ invalid API key, or Pos-Id. It can happen when the API key is deleted while the connection is active. - status:
4409 Conflict‒ server ends connection because another concurrent connection has been open to the same restaurant ‒ response is empty
Messages
Messages are small data structures which are sent through websocket. They are identified by type property.
Authorization request message
The POS sends this message to Qerko to authenticate itself. Websockets don't support additional HTTP headers, so we need to authenticate the POS using something else.
Right after opening, Qerko awaits an authorization message. If it receives anything else the websocket will be closed. If no authorization message is received in 5 s from opening the connection, it will also be closed.
Send this message right after opening the websocket. It will authenticate the connection.
| Property | Type | Required? | Description |
|---|---|---|---|
| type | string | Yes | Present in all messages. It defines the purpose of the message. Value: auth-request |
| posId | string | Yes | Pos-Id assigned to your POS. See Production environment. |
| apiKey | string | Yes | The API key without any prefix. Example: abcd-efgh-ijkl-mnop-qrst |
| locale | string | No | Locale for error localization in ISO 639-1 (opens in a new tab) format. Default: en |
Authorization response message
This message is sent as a response to the authorization message.
| Property | Type | Required? | Description |
|---|---|---|---|
| type | string | Yes | Present in all messages. It defines the purpose of the message Value: auth-response |
| authorized | boolean | Yes | TRUE ‒ You are authorized and you can send and receive other messages. FALSE ‒ You are not authorized. Reason is in the message. Qerko closes the socket after this message. |
| error | Error null | Yes | If not authorized, here is the reason If authorized, null will be here. Example: {message: "Invalid Pos-Id", code: "POS_UNKNOWN" } |
Method call request message
This message can go both ways. It means from Qerko to POS and vice versa. After receiving this message the receiver executes the corresponding method and sends a Method call response message with a result
| Property | Type | Required? | Description |
|---|---|---|---|
| type | string | Yes | Present in all messages. It defines the purpose of the message. Value: method-call-request |
| uuid | string null | Yes | Identifier of the call. It can be null. If it is null, the receiver doesn’t have to send a response message. Example: 1d0de3e1-5d4c-11e9-bc19-064f106d678c |
| method | string | Yes | One of the method names. Example: paymentStart |
| args | object[] | Yes | Arguments for the method. Array will match the method's signature. Example: [{ id: "1", total: "255", ...}] |
Method call response message
This message can go both ways. It means from POS to Qerko and vice versa.
This message is sent when there is a result of a method call from a previous Method call request message. Answer is mandatory when a call request contains non-null uuid.
| Property | Type | Required? | Description |
|---|---|---|---|
| type | string | Yes | Present in all messages. It defines the purpose of the message Value: method-call-response |
| uuid | string | Yes | Identifier of the call. You have received this value in the previous Method call request message. Example: 1d0de3e1-5d4c-11e9-bc19-064f106d678c |
| result | any | No | It can be whatever the method returns including null. Default: null Example: { "foo": "bar" } |
| error | Error null | No | Error which occured, null if there was no error. Default: null |
| calledMethod | string null | No | Method which produced this response. Qerko sends this every time. Provided for easier statelessness. Default: null |