Integrationsleitfaden

Dieser Leitfaden erklärt, wie Sie ein Kassensystem oder POS-Client-System in die iorder POS-Plattform integrieren. Er behandelt die vier Integrationspunkte, die jeder Client für die Echtzeitverarbeitung von Bestellungen und Befehlen implementieren muss.

Integrationsablauf

Die Integration folgt einem benachrichtigungsgesteuerten Polling-Muster:

Client                      iorder POS Server
  |                                |
  |--- SSE CONNECT --------------->|  (1) SSE-Stream öffnen
  |<-- ready event -----------------|  (2) subscriptionId + locationName empfangen
  |                                |
  |<-- message event (new data) ---|  (3) Server meldet: neue Bestellungen/Befehle verfügbar
  |--- GET /orders/location ------>|  (4) Client fragt neue Daten ab
  |<-- ExternalOrder[] ------------|  (5) Bestellungen + Befehle empfangen
  |                                |
  |--- PUT /orders/{id}/status -->|  (6) Bestellstatus aktualisieren (COMPLETED, ABORTED)
  |--- POST /commands/{id}/resp ->|  (7) Auf Befehl antworten

Der Server sendet leichte Ereignisse über SSE, um den Client zu wecken. Der Client ruft dann die tatsächlichen Daten ab. Dies vermeidet das Senden vollständiger Bestelldaten über den Ereignisstrom und gibt dem Client die volle Kontrolle darüber, wann er Daten abruft.

Die vier Integrationspunkte

#	Integrationspunkt	Richtung	Endpunkt
1	SSE-Benachrichtigung	Server zu Client	GET /notifications/service/stream
2	Bestellungen & Befehle abrufen	Client zu Server	GET /orders/location
3	Bestellstatus aktualisieren	Client zu Server	PUT /orders/{orderId}/statusupdate
4	Auf Befehle antworten	Client zu Server	POST /commands/{id}/response

Unterstützte Client-Typen

Die Integration unterstützt zwei Arten von entfernten Clients:

• Service-Clients — Kassensysteme, Küchenanzeigesysteme oder jedes Backend, das aufgegebene Bestellungen verarbeitet. Diese Clients öffnen einen SSE-Stream und rufen neue Bestellungen und Befehle ab.
• Client-Sitzungen — Frontend-Bestellgeräte (kundenorientierte Tablets, POS-Terminals). Diese erstellen und aktualisieren Bestellungen interaktiv. Dieser Leitfaden konzentriert sich auf Service-Clients.

Authentifizierung

Jede API-Anfrage erfordert einen API-Schlüssel. Weitere Informationen finden Sie im Kapitel Authentifizierung.

Voraussetzungen

Bevor Sie beginnen:

• Sie benötigen einen gültigen API-Schlüssel, der über die iorder Admin-Oberfläche bereitgestellt wird.
• Ihr Client muss HTTPS-Verbindungen öffnen und SSE-Streams verarbeiten können.
• Ihr Client muss eine stabile Netzwerkverbindung zum iorder-Server haben.

Nächste Schritte

1. Authentifizierung — API-Schlüssel anfordern und verwenden
2. SSE-Benachrichtigung — Den Benachrichtigungsstrom öffnen
3. Polling — Bestellungen und Befehle abrufen
4. Bestellstatus aktualisieren — Bestellzustände aktualisieren
5. Auf Befehle antworten — Befehle verarbeiten
6. Fehlerbehandlung — Fehler ordnungsgemäß behandeln
7. Sicherheit & Best Practices — Ihre Integration absichern