Polling Orders & Commands

After receiving a message event on the SSE stream, the client polls GET /orders/location to retrieve all pending orders and commands. This endpoint returns both regular orders and command objects in a single response.

Endpoint

text

GET https://{host}/orders/location

Headers:

Header	Required	Description
`api_key`	Yes	Service device API key

Query parameters:

Parameter	Type	Default	Description
`orderNumber`	`long`	`0`	Only return orders with number greater than this value
`commandNumber`	`long`	`0`	Only return commands with ID greater than this value

Response: 200 OK with body ExternalOrder[] (JSON array)

Response Schema

The endpoint returns a JSON array of ExternalOrder objects. Each object can represent either a food/beverage order or a command (e.g., read table state, request bill, export data).

ExternalOrder

json

{
  "number": 12345,
  "orderTime": "10:30:00",
  "tableNumber": 12,
  "userNumber": 5,
  "guestCount": 1,
  "rows": [
    {
      "category": {
        "order": 0,
        "id": 0,
        "description": "Beverages"
      },
      "itemType": "Beverages",
      "name": "Espresso",
      "number": 1,
      "factor": 2,
      "price": 3.50,
      "subrows": []
    }
  ],
  "state": "PLACED"
}

Fields that are not set are omitted from the response — null values are never serialized. The payload above shows a regular order; commands carry the same envelope but replace rows with a single type marker (see Distinguishing Orders from Commands).

Top-Level Fields

Field	Type	Description
`number`	`long`	Unique order/command identifier. Use this for idempotency and offset tracking
`orderTime`	`string`	Time the order was placed (commands: when the command was created), format `HH:mm:ss`
`tableNumber`	`long` or `null`	Table number (absent for takeout orders)
`userNumber`	`long` or `null`	User number who placed the order (absent if no user session)
`guestCount`	`int`	Number of guests. Currently always `1` on orders
`readTableState`	`boolean`	Present (`true`) only on read-table-state commands
`paymentNumber`	`int`	Present only on request-bill commands (always `1`)
`exportMainData`	`boolean`	Present (`true`) only on export-data / fetch-remote-menu commands
`rows`	`array`	Order line items. Only present on orders; commands have no rows
`state`	`string`	Order state. Always present; commands always report `PLACED`

The DTO also defines togo, moveTableTo, receipt, paymentDiscount, and customer, but the current backend never populates them, so they never appear in responses.

OrderRow

Field	Type	Description
`category`	`object` or `null`	Product category with `order`, `id`, and `description` (`order`/`id` are currently always `0`)
`itemType`	`string`	Type of item. One of `Menu item`, `Food`, `Takeout`, `Condiments`, `Beverages`, `Arrangement`
`name`	`string`	Product name
`infotext`	`string`	Special instructions or notes (omitted when empty)
`number`	`int`	Row number
`factor`	`int`	Quantity
`price`	`number`	Unit price
`priceTogo`	`number`	Takeout price if different (currently never populated)
`discount`	`array`	Discounts applied to this row (currently never populated)
`subrows`	`array`	Sub-items (modifiers, sides). Always an array; `[]` when there are none

Field	Type	Description
`order`	`int`	Sort order
`id`	`int`	Category ID
`description`	`string` or `null`	Category name

Distinguishing Orders from Commands

The response array mixes regular orders and commands. Classify commands using their type markers rather than depending on a computed isCommand flag:

readTableState is true
exportMainData is true
paymentNumber is not null

The DTO also defines a moveTableTo field for a potential move-table command, but the current backend never produces it.

Detection pseudo-code:

javascript

function isCommand(item) {
  return item.readTableState === true
      || item.exportMainData === true
      || item.paymentNumber != null;
}

function processResponse(items) {
  for (const item of items) {
    if (isCommand(item)) {
      handleCommand(item);
    } else {
      handleOrder(item);
    }
  }
}

Command Types

Detection Field	Command Type	What To Do
`readTableState: true`	Read table state	Query your local table state and POST response to `/commands/{id}/response`
`exportMainData: true`	Fetch remote menu / export data	Export your menu data (e.g., for Vectron integration)
`paymentNumber: 1`	Request bill	Process the customer's bill request (paymentNumber is always `1`)

Command Payloads

Each command carries the same envelope as an order (number, orderTime, state) plus exactly one type marker:

Request bill (paymentNumber):

json

{
  "number": 42,
  "orderTime": "14:32:05",
  "tableNumber": 12,
  "paymentNumber": 1,
  "state": "PLACED"
}

Fetch remote menu / export data (exportMainData):

json

{
  "number": 43,
  "orderTime": "14:33:10",
  "exportMainData": true,
  "state": "PLACED"
}

Read table state (readTableState):

json

{
  "number": 44,
  "orderTime": "14:34:22",
  "tableNumber": 7,
  "readTableState": true,
  "state": "PLACED"
}

The number field is the command ID — use it when responding via POST /commands/{id}/response.

OrderState Enum

The state field on orders uses these values:

text

SELECTING  — Customer is still selecting items (not yet placed)
NEW        — Order was just created by a client application
PLACED     — Customer has submitted the order, ready for processing
ABORTED    — Order was cancelled (e.g., session closed)
FAILED     — Order processing failed in the backend system
COMPLETED  — Order was completed successfully

For polling, the endpoint returns orders with state PLACED. Commands always have state PLACED.

Polling Guidance

Poll on message and after connecting or reconnecting. Use a bounded fallback interval, for example five seconds, to check pending work.
Prevent overlapping poll loops in the same worker. Coordinate multiple workers before external processing.
Classify each result before using its number: order numbers and command IDs are separate sequences.
Persist the external processing outcome, then acknowledge through the appropriate endpoint.
Advance each offset only past work that has been resolved. If a lower-numbered item failed, advancing to a later success can hide that earlier item from subsequent polls.
Treat an empty array as no pending work returned for those offsets, not proof that every previous operation completed.

Verify one order and one supported command at a test location before enabling continuous processing.

Curl Examples

Success Response with Multiple Orders

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

http

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "number": 12345,
    "orderTime": "10:30:00",
    "tableNumber": 12,
    "userNumber": 5,
    "rows": [
      {
        "category": { "order": 0, "id": 0, "description": "Beverages" },
        "itemType": "Beverages",
        "name": "Espresso",
        "number": 1,
        "factor": 2,
        "price": 3.50
      }
    ],
    "state": "PLACED"
  },
  {
    "number": 12346,
    "orderTime": "10:32:00",
    "tableNumber": 5,
    "userNumber": 3,
    "rows": [
      {
        "category": { "order": 0, "id": 0, "description": "Main Course" },
        "itemType": "Food",
        "name": "Caesar Salad",
        "number": 1,
        "factor": 1,
        "price": 12.90
      }
    ],
    "state": "PLACED"
  }
]

With Offset Parameters (after processing)

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location?orderNumber=12346&commandNumber=42"

Empty Response (no pending items)

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

http

HTTP/1.1 200 OK
Content-Type: application/json

[]

Response Containing a Command

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

json

[
  {
    "number": 99,
    "orderTime": "11:05:00",
    "readTableState": true,
    "tableNumber": 12,
    "state": "PLACED"
  }
]

This is a Read Table State command for table 12. The readTableState: true indicates it is a command, not an order.

Error Handling

Status	Meaning
200	Success (may return empty array `[]`)
401	Unauthorized (invalid or expired API key)
500	Internal server error (retry with backoff)

Next Steps

Update Order Status — Mark orders as completed or aborted
Respond to Commands — Send responses to commands

Polling Orders & Commands ​

Endpoint ​

Response Schema ​

ExternalOrder ​

Top-Level Fields ​

OrderRow ​

Category ​

Distinguishing Orders from Commands ​

Command Types ​

Command Payloads ​

OrderState Enum ​

Polling Guidance ​

Curl Examples ​

Success Response with Multiple Orders ​

With Offset Parameters (after processing) ​

Empty Response (no pending items) ​

Response Containing a Command ​

Error Handling ​

Next Steps ​

Polling Orders & Commands

Endpoint

Response Schema

ExternalOrder

Top-Level Fields

OrderRow

Category

Distinguishing Orders from Commands

Command Types

Command Payloads

OrderState Enum

Polling Guidance

Curl Examples

Success Response with Multiple Orders

With Offset Parameters (after processing)

Empty Response (no pending items)

Response Containing a Command

Error Handling

Next Steps