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 vom Polling-Endpunkt GET /orders/location als ExternalOrder-Objekte zurückgegeben, bei denen isCommand() true zurückgibt. Sie werden anhand dieser Felder von regulären Bestellungen unterschieden:

• readTableState: true — Aktuellen Status eines Tisches lesen
• moveTableTo: <int> — Bestellung auf einen anderen Tisch verschieben
• 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.

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,"occupied":true,"orders":[12345]})
FETCH_REMOTE_MENU	JSON-Zeichenkette mit Menüdaten

Antwort: 200 OK mit leerem Body.

Curl-Beispiel: Erfolg

curl -i -X POST \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: text/plain" \
  -d '{"tableNumber":12,"occupied":true,"orders":[12345,12346]}' \
  "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 Ihr Client GET /orders/location abfragt und ein Element erhält, bei dem isCommand() true zurückgibt:

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

   • readTableState: true — Es ist ein Tischstatus lesen Befehl
   • moveTableTo: <int> — Es ist ein Tisch verschieben 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.
   • Tisch verschieben: Verschieben Sie die Bestelldaten in Ihrem System auf den angegebenen Tisch.
   • 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