Integration Guide

This guide explains how to integrate a cash register or POS client system with the iorder POS platform. It covers the four integration touchpoints that every client needs to implement for real-time order and command processing.

Integration Flow

The integration follows a notification-driven polling pattern:

Client                      iorder POS Server
  |                                |
  |--- SSE CONNECT --------------->|  (1) Open SSE stream
  |<-- ready event -----------------|  (2) Receive subscriptionId + locationName
  |                                |
  |<-- message event (new data) ---|  (3) Server notifies: new orders/commands available
  |--- GET /orders/location ------>|  (4) Client polls for new data
  |<-- ExternalOrder[] ------------|  (5) Receive orders + commands
  |                                |
  |--- PUT /orders/{id}/statusupdate -->|  (6) Update order status (COMPLETED, ABORTED)
  |--- POST /commands/{id}/response ->|  (7) Respond to command

The server pushes lightweight events via SSE to wake up the client. The client then polls for the actual data. This avoids sending full order payloads over the event stream and gives the client full control over when to fetch.

The Four Touchpoints

#	Touchpoint	Direction	Endpoint
1	SSE Notification	Server to Client	GET /notifications/service/stream
2	Poll Orders & Commands	Client to Server	GET /orders/location
3	Update Order Status	Client to Server	PUT /orders/{orderId}/statusupdate
4	Respond to Commands	Client to Server	POST /commands/{id}/response

Supported Client Types

The integration supports two types of remote clients:

• Service clients — cash register systems, kitchen display systems, or any backend that processes placed orders. These clients open an SSE stream and poll for new orders and commands.
• Client sessions — frontend ordering devices (customer-facing tablets, POS terminals). These create and update orders interactively. This guide focuses on service clients.

Authentication

Every API request requires an API key. See the Authentication chapter for details.

Prerequisites

Before implementing the client, agree these details with the installation operator:

• The application base URL and a service API key for the intended location.
• A test location and a way to verify the result at the register without affecting restaurant service.
• The expected format of table-state and menu responses.
• Which client owns processing when multiple workers or devices connect.

In the examples, replace {host} with your application host and the sample API key with your credential. API paths are relative to the application base URL; /manuals/ is only the documentation address.

Start with one controlled order: connect, verify the ready location, poll, process it once, acknowledge the outcome, and check it in the application. Test command handling and interrupted connections before using the integration during service.

Next Steps

1. Authentication — Obtain and use your API key
2. SSE Notification — Open the notification stream
3. Polling — Poll for orders and commands
4. Update Order Status — Update order states
5. Respond to Commands — Handle commands
6. Error Handling — Handle errors gracefully
7. Security & Best Practices — Secure your integration