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 are returned by the polling endpoint GET /orders/location as ExternalOrder objects where isCommand() returns true. They are distinguished from regular orders by these fields:

• readTableState: true — Read the current state of a table
• moveTableTo: <int> — Move order to a different 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.

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,"occupied":true,"orders":[12345]})
FETCH_REMOTE_MENU	JSON string with menu data

Response: 200 OK with empty body.

Curl Example: Success

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d '{"tableNumber":12,"occupied":true,"orders":[12345,12346]}' \
  "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 your client polls GET /orders/location and receives an item where isCommand() returns true:

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

   • readTableState: true — It's a Read Table State command
   • moveTableTo: <int> — It's a Move Table 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.
   • Move Table: Move the order data to the specified table in your system.
   • 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