Auf Befehle antworten

Befehle sind Aktionen, die das iorder-System vom Client ausführen lässt. Sie treffen zusammen mit Bestellungen in der GET /orders/location-Antwort ein. Im Gegensatz zu Bestellungen erfordern Befehle eine Antwort vom Client.

Wie Befehle eintreffen

Befehle werden von GET /orders/location in der ExternalOrder-Hülle geliefert. Unterscheiden Sie sie anhand dieser Typmerkmale von regulären Bestellungen:

• readTableState: true — Aktuellen Status eines Tisches lesen
• exportMainData: true — Menüdaten exportieren oder synchronisieren
• paymentNumber: <int> — Eine Rechnungsanforderung verarbeiten

Das Feld number des Befehls ist die Befehls-ID (id aus der Command-Entität). Verwenden Sie diese ID beim Senden von Antworten.

Einen Befehl abschließen

1. Ermitteln Sie den Typ anhand von readTableState, exportMainData oder paymentNumber und notieren Sie die Befehlskennung aus number.
2. Führen Sie den Vorgang einmal aus. Verwenden Sie für Menüdaten das Abruf-Antwortformat; stimmen Sie das Tischstatusformat mit dem Betreiber ab.
3. Senden Sie die Antwort an /commands/{commandId}/response mit der Befehlskennung, nicht einer Bestellnummer.
4. Prüfen Sie HTTP-Ergebnis und Vorgang in der Anwendung. Eine angenommene Antwort bestätigt allein noch keine erfolgreiche Verarbeitung der Menüdaten.
5. Klären Sie bei Timeout oder bereits abgeschlossenem Befehl das Ergebnis vor erneuter externer Ausführung.

Das interne Command-Schema unten ist von der beim Polling gelieferten ExternalOrder-Hülle zu unterscheiden.

Endpunkte

1. POST /commands/{id}/response — Antwort auf einen bestimmten Befehl senden

1. Auf einen Befehl antworten

POST https://{host}/commands/{commandId}/response

Pfadparameter:

Parameter	Typ	Beschreibung
commandId	long	Die Befehls-ID (aus dem Feld number)

Header:

Header	Erforderlich	Beschreibung
api_key	Ja	API-Schlüssel des Service-Geräts
Content-Type	Ja	text/plain

Request-Body: Zeichenkette im Klartext mit den Antwortdaten. Der Inhalt hängt vom Befehlstyp ab:

Befehlstyp	Antwortinhalt
readTableState	JSON-Zeichenkette, die den aktuellen Tischstatus darstellt (z. B. {"tableNumber":12,"guestCount":2,"total":0.0,"rows":[]})
FETCH_REMOTE_MENU	JSON-Zeichenkette mit Menüdaten

Antwort: 200 OK mit leerem Body.

Tischstatusantwort

Senden Sie für readTableState ein JSON-Objekt als Textbody:

Feld	Typ	Erforderlich	Bedeutung
tableNumber	Ganzzahl	Ja	Angefragte Tischnummer.
guestCount	Ganzzahl	Ja	Von der Kasse gemeldete Gästeanzahl.
total	Zahl	Ja	Aktuelle Tischsumme.
rows	Array	Nein	Standardmäßig leer. Jede Zeile benötigt number, name, factor und price; subrows ist optional.

Das folgende Beispiel gilt für einen Tisch ohne gebuchte Artikel. Übermitteln Sie bei einem belegten Tisch die tatsächlichen Zeilen und die Summe der Kasse.

Curl-Beispiel: Erfolg

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d '{"tableNumber":12,"guestCount":2,"total":0.0,"rows":[]}' \
  "https://{host}/commands/99/response"

Antwort:

HTTP/1.1 200 OK

Curl-Beispiel: Befehl bereits abgeschlossen

Wenn der Befehl bereits verarbeitet wurde:

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d 'response-data' \
  "https://{host}/commands/99/response"

Antwort:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Command already completed.

Curl-Beispiel: Befehl nicht gefunden

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d 'response-data' \
  "https://{host}/commands/99999/response"

Antwort:

HTTP/1.1 404 Not Found

Vollständiger Befehlsverarbeitungsablauf

Wenn Polling ein Element mit einem Befehlstypmerkmal liefert:

1. Identifizieren Sie den Befehlstyp, indem Sie prüfen, welches Feld nicht null ist:

   • readTableState: true — Es ist ein Tischstatus lesen Befehl
   • exportMainData: true — Es ist ein Daten exportieren / Remote-Menü abrufen Befehl
   • paymentNumber: <int> — Es ist ein Rechnung anfordern Befehl

2. Verarbeiten Sie den Befehl entsprechend seinem Typ:

   • Tischstatus lesen: Fragen Sie Ihr lokales System nach dem aktuellen Tischstatus ab und senden Sie das Ergebnis an /commands/{commandId}/response.
   • Daten exportieren / Remote-Menü abrufen: Exportieren Sie Ihre Menüdaten. Der Server verwendet diese, um Menüelemente mit externen Systemen zu synchronisieren.
   • Rechnung anfordern: Dieser Befehl wird über Polling empfangen und stellt eine Kundenrechnungsanforderung dar. Wenn er über Polling empfangen wird, verarbeiten Sie die Zahlung in Ihrem System.

3. Senden Sie die Antwort über POST /commands/{commandId}/response für Befehle, die eine Antwort benötigen (Tischstatus lesen, Remote-Menü abrufen).

Befehlsobjekt-Schema

Wenn von der API zurückgegeben, hat das Command-Objekt diese Felder:

Feld	Typ	Beschreibung
id	long	Befehls-ID
commandType	string	Befehlstyp (ASK_FOR_BILL, READ_TABLE_STATE, FETCH_REMOTE_MENU)
orderState	string	Aktueller Status (NEW oder COMPLETED)
json	string	Payload als rohe JSON-Zeichenkette. Inhalt hängt vom Befehlstyp ab
created	string (ISO datetime)	Zeitpunkt der Befehlserstellung
locationName	string	Standort, zu dem der Befehl gehört
jsonResponse	string oder null	Vom Client nach der Verarbeitung gesetzte Antwort
configurationName	string oder null	Konfigurationsname (für FETCH_REMOTE_MENU-Befehle)

Nächste Schritte

• Fehlerbehandlung — Fehlerantwortformate und Randfälle verstehen
• Sicherheit & Best Practices — Ihre Integration absichern