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,
  "togo": null,
  "guestCount": 1,
  "moveTableTo": null,
  "readTableState": null,
  "paymentNumber": null,
  "receipt": null,
  "exportMainData": null,
  "paymentDiscount": null,
  "customer": null,
  "rows": [
    {
      "category": {
        "order": 1,
        "id": 1,
        "description": "Beverages"
      },
      "itemType": "MENU_ITEM",
      "name": "Espresso",
      "number": 1,
      "factor": 2,
      "price": 3.50,
      "priceTogo": null,
      "discount": null,
      "subrows": null
    }
  ],
  "state": "PLACED"
}

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, Format `HH:mm:ss`
`tableNumber`	`long` oder `null`	Tischnummer
`userNumber`	`long` oder `null`	Benutzernummer des Bestellers
`togo`	`int` oder `null`	Kennzeichen für Mitnahme
`guestCount`	`int` oder `null`	Anzahl der Gäste
`moveTableTo`	`int` oder `null`	Wenn gesetzt, repräsentiert dieses Objekt einen Tisch verschieben Befehl
`readTableState`	`boolean` oder `null`	Wenn `true`, repräsentiert dieses Objekt einen Tischstatus lesen Befehl
`paymentNumber`	`int` oder `null`	Wenn gesetzt, repräsentiert dieses Objekt einen Rechnung anfordern Befehl
`receipt`	`boolean` oder `null`	Wenn `true`, repräsentiert dieses Objekt einen Quittung drucken Befehl
`exportMainData`	`boolean` oder `null`	Wenn `true`, repräsentiert dieses Objekt einen Hauptdaten exportieren / Remote-Menü abrufen Befehl
`paymentDiscount`	`array` oder `null`	Array von Rabattobjekten, die auf die Bestellung angewendet wurden
`customer`	`object` oder `null`	Kundeninformationen (für Rechnungsbestellungen)
`rows`	`array` oder `null`	Bestellpositionen. `null` bei Befehlen
`state`	`string` oder `null`	Bestellstatus. `null` oder `"PLACED"` bei Befehlen

OrderRow

Feld	Typ	Beschreibung
`category`	`object` oder `null`	Produktkategorie mit `order`, `id` und `description`
`itemType`	`string`	Artikeltyp (`MENU_ITEM`, `FOOD`, `TAKEOUT`, `CONDIMENTS`, `BEVERAGES`, `ARRANGEMENT`)
`name`	`string`	Produktname
`infotext`	`string` oder `null`	Besondere Anweisungen oder Hinweise
`number`	`int`	Zeilennummer
`factor`	`int`	Menge
`price`	`number` oder `null`	Einzelpreis
`priceTogo`	`number` oder `null`	Mitnahmepreis, falls abweichend
`discount`	`array` oder `null`	Rabatte, die auf diese Zeile angewendet wurden
`subrows`	`array` oder `null`	Unterpositionen (Modifikatoren, Beilagen)

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. Verwenden Sie die isCommand()-Logik zur Unterscheidung. Ein ExternalOrder ist ein Befehl, wenn eines dieser Felder gesetzt ist:

readTableState ist true
moveTableTo ist nicht null
exportMainData ist true
paymentNumber ist nicht null

Erkennungs-Pseudocode:

javascript

function isCommand(item) {
  return item.readTableState === true
      || item.moveTableTo !== null
      || 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
`moveTableTo: <int>`	Tisch verschieben	Positionen zur angegebenen Tischnummer verschieben
`exportMainData: true`	Remote-Menü abrufen / Daten exportieren	Ihre Menüdaten exportieren (z. B. für Vectron-Integration)
`paymentNumber: <int>`	Rechnung anfordern	Die Rechnung für die angegebene Zahlungsnummer senden

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": 1, "id": 1, "description": "Beverages" },
        "itemType": "MENU_ITEM",
        "name": "Espresso",
        "number": 1,
        "factor": 2,
        "price": 3.50
      }
    ],
    "state": "PLACED"
  },
  {
    "number": 12346,
    "orderTime": "10:32:00",
    "tableNumber": 5,
    "userNumber": 3,
    "rows": [
      {
        "category": { "order": 2, "id": 3, "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 ​

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

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