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}/status -->|  (6) Update order status (COMPLETED, ABORTED)
  |--- POST /commands/{id}/resp ->|  (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 you start:

• You need a valid API key provisioned by the iorder admin UI.
• Your client must be able to open HTTPS connections and handle SSE streams.
• Your client must have a stable network connection to the iorder server.

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