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",
  "isCommand": false
}

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`
`isCommand`	`boolean`	`true` bei Befehlen, `false` bei Bestellungen. Zum Verteilen anhand des Payload-Typs verwenden

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 eine Mischung aus normalen Bestellungen und Befehlen. Jedes Objekt trägt einen isCommand-Boolean — true bei Befehlen, false bei Bestellungen — sodass Clients direkt darauf verteilen können. Die gleichwertige Ableitung, falls Sie sich nicht auf das Flag verlassen möchten: Ein ExternalOrder ist ein Befehl, wenn eines dieser Felder vorhanden ist:

isCommand ist true
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.isCommand === true
      || 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, isCommand) plus genau einen Typmarker:

Rechnung anfordern (paymentNumber):

json

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

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

json

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

Tischstatus lesen (readTableState):

json

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

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

Bei SSE message-Ereignis abrufen — Wenn der SSE-Stream ein message-Ereignis sendet, diesen Endpunkt sofort aufrufen.
Fallback-Intervall-Polling — Als Sicherheitsnetz in einem angemessenen Intervall (alle 5 Sekunden) abrufen, auch ohne SSE-Benachrichtigungen.
Bestell-Offset verwenden — Die höchste verarbeitete number verfolgen und als orderNumber übergeben, um bereits verarbeitete Bestellungen zu vermeiden.
Befehls-Offset verwenden — Ebenso die höchste Befehls-ID verfolgen und als commandNumber übergeben.
Stapelverarbeitung — Sie können mehrere Bestellungen in einer Antwort erhalten. Diese nacheinander verarbeiten und den Status für jede aktualisieren.

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",
    "isCommand": false
  },
  {
    "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",
    "isCommand": false
  }
]

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",
    "isCommand": true
  }
]

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