Bestellungen & Befehle abrufen (Polling)

Nach dem Empfang eines message-Ereignisses im SSE-Stream ruft der Client GET /orders/location auf, um alle ausstehenden Bestellungen und Befehle abzurufen. Dieser Endpunkt gibt sowohl normale Bestellungen als auch Befehlsobjekte in einer einzigen Antwort zurück.

Endpunkt

text

GET https://{host}/orders/location

Header:

Header	Erforderlich	Beschreibung
`api_key`	Ja	API-Schlüssel des Service-Geräts

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`orderNumber`	`long`	`0`	Nur Bestellungen mit einer Nummer größer als dieser Wert zurückgeben
`commandNumber`	`long`	`0`	Nur Befehle mit einer ID größer als dieser Wert zurückgeben

Antwort: 200 OK mit Body ExternalOrder[] (JSON-Array)

Antwort-Schema

Der Endpunkt gibt ein JSON-Array von ExternalOrder-Objekten zurück. Jedes Objekt kann entweder eine Speise-/Getränkebestellung oder einen Befehl darstellen (z. B. Tischstatus lesen, Rechnung anfordern, Daten exportieren).

ExternalOrder

json

{
  "number": 12345,
  "orderTime": "10:30:00",
  "tableNumber": 12,
  "userNumber": 5,
  "guestCount": 1,
  "rows": [
    {
      "category": {
        "order": 0,
        "id": 0,
        "description": "Beverages"
      },
      "itemType": "Beverages",
      "name": "Espresso",
      "number": 1,
      "factor": 2,
      "price": 3.50,
      "subrows": []
    }
  ],
  "state": "PLACED"
}

Felder, die nicht gesetzt sind, werden weggelassen — null-Werte werden nie serialisiert. Das obige Beispiel zeigt eine normale Bestellung; Befehle verwenden dieselbe Hülle, ersetzen aber rows durch einen einzelnen Typmarker (siehe Unterscheidung zwischen Bestellungen und Befehlen).

Felder der obersten Ebene

Feld	Typ	Beschreibung
`number`	`long`	Eindeutige Bestell-/Befehls-ID. Für Idempotenz und Offset-Verfolgung verwenden
`orderTime`	`string`	Zeitpunkt der Bestellung (bei Befehlen: Zeitpunkt der Befehlserstellung), Format `HH:mm:ss`
`tableNumber`	`long` oder `null`	Tischnummer (fehlt bei Mitnahmebestellungen)
`userNumber`	`long` oder `null`	Benutzernummer des Bestellers (fehlt ohne Benutzersitzung)
`guestCount`	`int`	Anzahl der Gäste. Aktuell bei Bestellungen immer `1`
`readTableState`	`boolean`	Nur bei Tischstatus-lesen-Befehlen vorhanden (`true`)
`paymentNumber`	`int`	Nur bei Rechnung-anfordern-Befehlen vorhanden (immer `1`)
`exportMainData`	`boolean`	Nur bei Daten-exportieren-/Remote-Menü-abrufen-Befehlen vorhanden (`true`)
`rows`	`array`	Bestellpositionen. Nur bei Bestellungen vorhanden; Befehle haben keine Zeilen
`state`	`string`	Bestellstatus. Immer vorhanden; Befehle melden immer `PLACED`

Das DTO definiert außerdem togo, moveTableTo, receipt, paymentDiscount und customer, aber das aktuelle Backend füllt sie nie aus, daher erscheinen sie nie in Antworten.

OrderRow

Feld	Typ	Beschreibung
`category`	`object` oder `null`	Produktkategorie mit `order`, `id` und `description` (`order`/`id` sind aktuell immer `0`)
`itemType`	`string`	Artikeltyp. Einer von `Menu item`, `Food`, `Takeout`, `Condiments`, `Beverages`, `Arrangement`
`name`	`string`	Produktname
`infotext`	`string`	Besondere Anweisungen oder Hinweise (bei Leere weggelassen)
`number`	`int`	Zeilennummer
`factor`	`int`	Menge
`price`	`number`	Einzelpreis
`priceTogo`	`number`	Mitnahmepreis, falls abweichend (aktuell nie befüllt)
`discount`	`array`	Rabatte, die auf diese Zeile angewendet wurden (aktuell nie befüllt)
`subrows`	`array`	Unterpositionen (Modifikatoren, Beilagen). Immer ein Array; `[]`, wenn keine vorhanden

Feld	Typ	Beschreibung
`order`	`int`	Sortierreihenfolge
`id`	`int`	Kategorie-ID
`description`	`string` oder `null`	Kategoriename

Unterscheidung zwischen Bestellungen und Befehlen

Das Antwort-Array enthält Bestellungen und Befehle. Erkennen Sie Befehle anhand ihrer Typmerkmale, statt von einem berechneten isCommand-Flag abhängig zu sein:

readTableState ist true
exportMainData ist true
paymentNumber ist nicht null

Das DTO definiert außerdem ein Feld moveTableTo für einen möglichen Tisch-verschieben-Befehl, aber das aktuelle Backend erzeugt es nie.

Erkennungs-Pseudocode:

javascript

function isCommand(item) {
  return item.readTableState === true
      || item.exportMainData === true
      || item.paymentNumber != null;
}

function processResponse(items) {
  for (const item of items) {
    if (isCommand(item)) {
      handleCommand(item);
    } else {
      handleOrder(item);
    }
  }
}

Befehlstypen

Erkennungsfeld	Befehlstyp	Was zu tun ist
`readTableState: true`	Tischstatus lesen	Ihren lokalen Tischstatus abfragen und Antwort an `/commands/{id}/response` senden
`exportMainData: true`	Remote-Menü abrufen / Daten exportieren	Ihre Menüdaten exportieren (z. B. für Vectron-Integration)
`paymentNumber: 1`	Rechnung anfordern	Die Rechnungsanforderung des Kunden verarbeiten (`paymentNumber` ist immer `1`)

Befehls-Payloads

Jeder Befehl trägt dieselbe Hülle wie eine Bestellung (number, orderTime, state) plus genau einen Typmarker:

Rechnung anfordern (paymentNumber):

json

{
  "number": 42,
  "orderTime": "14:32:05",
  "tableNumber": 12,
  "paymentNumber": 1,
  "state": "PLACED"
}

Remote-Menü abrufen / Daten exportieren (exportMainData):

json

{
  "number": 43,
  "orderTime": "14:33:10",
  "exportMainData": true,
  "state": "PLACED"
}

Tischstatus lesen (readTableState):

json

{
  "number": 44,
  "orderTime": "14:34:22",
  "tableNumber": 7,
  "readTableState": true,
  "state": "PLACED"
}

Das Feld number ist die Befehls-ID — verwenden Sie es beim Antworten über POST /commands/{id}/response.

OrderState-Enum

Das Feld state bei Bestellungen verwendet diese Werte:

text

SELECTING  — Kunde wählt noch Artikel aus (noch nicht aufgegeben)
NEW        — Bestellung wurde gerade von einer Client-Anwendung erstellt
PLACED     — Kunde hat die Bestellung aufgegeben, bereit zur Verarbeitung
ABORTED    — Bestellung wurde storniert (z. B. Sitzung geschlossen)
FAILED     - Bestellverarbeitung im Backend fehlgeschlagen
COMPLETED  — Bestellung wurde erfolgreich abgeschlossen

Beim Polling gibt der Endpunkt Bestellungen mit dem Status PLACED zurück. Befehle haben immer den Status PLACED.

Polling-Hinweise

Fragen Sie bei message sowie nach Verbindungsaufbau oder Wiederverbindung ab. Nutzen Sie ein begrenztes Fallback-Intervall, etwa fünf Sekunden, für offene Vorgänge.
Verhindern Sie überlappende Abrufschleifen desselben Workers. Koordinieren Sie mehrere Worker vor externer Verarbeitung.
Klassifizieren Sie jedes Element vor der Nutzung von number: Bestellnummern und Befehlskennungen sind getrennte Folgen.
Speichern Sie das externe Verarbeitungsergebnis dauerhaft und bestätigen Sie über den passenden Endpunkt.
Erhöhen Sie Offsets nur über geklärte Vorgänge hinweg. Schlägt eine niedrigere Nummer fehl, kann ein Offset auf eine spätere erfolgreiche Nummer den früheren Vorgang aus weiteren Abrufen ausblenden.
Eine leere Liste bedeutet keine zurückgegebenen offenen Vorgänge für diese Offsets. Sie bestätigt nicht den Abschluss aller früheren Vorgänge.

Prüfen Sie eine Bestellung und einen unterstützten Befehl an einem Teststandort vor kontinuierlicher Verarbeitung.

Curl-Beispiele

Erfolgsantwort mit mehreren Bestellungen

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Antwort:

http

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "number": 12345,
    "orderTime": "10:30:00",
    "tableNumber": 12,
    "userNumber": 5,
    "rows": [
      {
        "category": { "order": 0, "id": 0, "description": "Beverages" },
        "itemType": "Beverages",
        "name": "Espresso",
        "number": 1,
        "factor": 2,
        "price": 3.50
      }
    ],
    "state": "PLACED"
  },
  {
    "number": 12346,
    "orderTime": "10:32:00",
    "tableNumber": 5,
    "userNumber": 3,
    "rows": [
      {
        "category": { "order": 0, "id": 0, "description": "Main Course" },
        "itemType": "Food",
        "name": "Caesar Salad",
        "number": 1,
        "factor": 1,
        "price": 12.90
      }
    ],
    "state": "PLACED"
  }
]

Mit Offset-Parametern (nach der Verarbeitung)

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location?orderNumber=12346&commandNumber=42"

Leere Antwort (keine ausstehenden Elemente)

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Antwort:

http

HTTP/1.1 200 OK
Content-Type: application/json

[]

Antwort mit einem Befehl

bash

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Antwort:

json

[
  {
    "number": 99,
    "orderTime": "11:05:00",
    "readTableState": true,
    "tableNumber": 12,
    "state": "PLACED"
  }
]

Dies ist ein Tischstatus lesen Befehl für Tisch 12. Das Feld readTableState: true zeigt an, dass es sich um einen Befehl handelt, nicht um eine Bestellung.

Fehlerbehandlung

Status	Bedeutung
200	Erfolg (kann leeres Array `[]` zurückgeben)
401	Nicht autorisiert (ungültiger oder abgelaufener API-Schlüssel)
500	Interner Serverfehler (mit Backoff wiederholen)

Nächste Schritte

Bestellstatus aktualisieren — Bestellungen als abgeschlossen oder storniert markieren
Auf Befehle antworten — Antworten auf Befehle senden

Bestellungen & Befehle abrufen (Polling) ​

Endpunkt ​

Antwort-Schema ​

ExternalOrder ​

Felder der obersten Ebene ​

OrderRow ​

Category ​

Unterscheidung zwischen Bestellungen und Befehlen ​

Befehlstypen ​

Befehls-Payloads ​

OrderState-Enum ​

Polling-Hinweise ​

Curl-Beispiele ​

Erfolgsantwort mit mehreren Bestellungen ​

Mit Offset-Parametern (nach der Verarbeitung) ​

Leere Antwort (keine ausstehenden Elemente) ​

Antwort mit einem Befehl ​

Fehlerbehandlung ​

Nächste Schritte ​

Bestellungen & Befehle abrufen (Polling)

Endpunkt

Antwort-Schema

ExternalOrder

Felder der obersten Ebene

OrderRow

Category

Unterscheidung zwischen Bestellungen und Befehlen

Befehlstypen

Befehls-Payloads

OrderState-Enum

Polling-Hinweise

Curl-Beispiele

Erfolgsantwort mit mehreren Bestellungen

Mit Offset-Parametern (nach der Verarbeitung)

Leere Antwort (keine ausstehenden Elemente)

Antwort mit einem Befehl

Fehlerbehandlung

Nächste Schritte