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}/statusupdate -->|  (6) Bestellstatus aktualisieren (COMPLETED, ABORTED)
  |--- POST /commands/{id}/response ->|  (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

Stimmen Sie vor der Implementierung mit dem Installationsbetreiber Folgendes ab:

• Basis-URL der Anwendung und einen Dienst-API-Schlüssel für den vorgesehenen Standort.
• Einen Teststandort und eine Ergebniskontrolle an der Kasse ohne Beeinträchtigung des Betriebs.
• Das erwartete Format der Tischstatus- und Menüantworten.
• Die Zuständigkeit für die Verarbeitung bei mehreren verbundenen Clients oder Geräten.

Ersetzen Sie {host} und den Beispielschlüssel durch Host und Zugangsdaten Ihrer Anwendung. API-Pfade beziehen sich auf die Basis-URL der Anwendung. /manuals/ ist nur die Dokumentationsadresse.

Beginnen Sie mit einer abgestimmten Testbestellung: verbinden, Standort im ready-Ereignis prüfen, abrufen, einmal verarbeiten, Ergebnis bestätigen und in der Anwendung kontrollieren. Testen Sie Befehle und Verbindungsabbrüche vor dem Einsatz im Restaurantbetrieb.

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