Respond to Commands

Commands are actions that the iorder system asks the client to perform. They arrive alongside orders in the GET /orders/location response. Unlike orders, commands require a response from the client.

How Commands Arrive

Commands arrive from GET /orders/location in the ExternalOrder envelope. Use these type markers to distinguish them from regular orders:

• readTableState: true — Read the current state of a table
• exportMainData: true — Export or synchronize menu data
• paymentNumber: <int> — Process a bill request

The command's number field is the command ID (id from the Command entity). Use this ID when sending responses.

Complete one command

1. Identify its type from readTableState, exportMainData, or paymentNumber and record its command ID from number.
2. Perform the requested operation once. For menu data, use the fetch response format; agree the table-state format with the installation operator.
3. Submit the response to /commands/{commandId}/response, using the command ID rather than an order number.
4. Check the HTTP result and the operation in the application. An accepted response alone does not prove a fetched menu was parsed successfully.
5. If the response times out or reports that the command already completed, reconcile its outcome before repeating the external operation.

The internal Command schema below is separate from the ExternalOrder envelope returned by polling.

Endpoints

1. POST /commands/{id}/response — Send a response to a specific command

1. Respond to a Command

POST https://{host}/commands/{commandId}/response

Path parameters:

Parameter	Type	Description
commandId	long	The command ID (from the number field)

Headers:

Header	Required	Description
api_key	Yes	Service device API key
Content-Type	Yes	text/plain

Request body: Plain text string containing the response data. The content depends on the command type:

Command Type	Response Content
readTableState	JSON string representing the current table state (e.g., {"tableNumber":12,"guestCount":2,"total":0.0,"rows":[]})
FETCH_REMOTE_MENU	JSON string with menu data

Response: 200 OK with empty body.

Table-state response

For readTableState, send a JSON object as the text body:

Field	Type	Required	Meaning
tableNumber	integer	Yes	Requested table number.
guestCount	integer	Yes	Number of guests reported by the register.
total	number	Yes	Current table total.
rows	array	No	Defaults to an empty list. Each row needs number, name, factor, and price; subrows is optional.

The empty-table example below is for a table with no booked items. Return the register's actual rows and total for an occupied table.

Curl Example: Success

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d '{"tableNumber":12,"guestCount":2,"total":0.0,"rows":[]}' \
  "https://{host}/commands/99/response"

Response:

HTTP/1.1 200 OK

Curl Example: Command Already Completed

If the command has already been processed:

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d 'response-data' \
  "https://{host}/commands/99/response"

Response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Command already completed.

Curl Example: Command Not Found

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d 'response-data' \
  "https://{host}/commands/99999/response"

Response:

HTTP/1.1 404 Not Found

Full Command Processing Flow

When polling returns an item with a command type marker:

1. Identify the command type by checking which field is non-null:

   • readTableState: true — It's a Read Table State command
   • exportMainData: true — It's an Export Data / Fetch Remote Menu command
   • paymentNumber: <int> — It's a Request Bill command

2. Process the command according to its type:

   • Read Table State: Query your local system for the table's current state, then POST the result to /commands/{commandId}/response.
   • Export Data / Fetch Remote Menu: Export your menu data. The server uses this to synchronize menu items with external systems.
   • Request Bill: This command is received via polling and represents a customer bill request. When received via polling, process the payment in your system.

3. Send the response via POST /commands/{commandId}/response for commands that need a response (Read Table State, Fetch Remote Menu).

Command Object Schema

When returned from the API, the Command object has these fields:

Field	Type	Description
id	long	Command ID
commandType	string	Type of command (ASK_FOR_BILL, READ_TABLE_STATE, FETCH_REMOTE_MENU)
orderState	string	Current state (NEW or COMPLETED)
json	string	Payload as a raw JSON string. Contents depend on the command type
created	string (ISO datetime)	When the command was created
locationName	string	Location the command belongs to
jsonResponse	string or null	Response set by the client after processing
configurationName	string or null	Configuration name (for FETCH_REMOTE_MENU commands)

Next Steps

• Error Handling — Understand error response formats and edge cases
• Security & Best Practices — Secure your integration