Bestellstatus aktualisieren

Nach der Verarbeitung einer Bestellung (z. B. Senden an die Küche, Abschluss der Erfüllung) aktualisieren Sie den Bestellstatus auf dem iorder-Server. Dies speichert das Ergebnis; doppelte externe Verarbeitung muss die Integration selbst verhindern.

Verarbeitete Bestellung bestätigen

1. Prüfen Sie Bestellnummer und Verarbeitungsergebnis an der Kasse.
2. Speichern Sie das Ergebnis dauerhaft in der Integration.
3. Senden Sie den passenden Zustand und einen hilfreichen Kommentar ohne sensible Angaben.
4. Prüfen Sie HTTP-Antwort und zurückgegebenen state. Eine gemeldete Fehlverarbeitung kann unterhalb der Fehlergrenze wieder PLACED ergeben.
5. Klären Sie bei verlorener Antwort das Ergebnis, bevor Sie extern erneut verarbeiten.

Endpunkt

PUT https://{host}/orders/{orderId}/statusupdate

Pfadparameter:

Parameter	Typ	Beschreibung
orderId	string	Die Bestell-number (als Zeichenkette)

Header:

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

Request-Body: OrderUpdate

{
  "newState": "COMPLETED",
  "comment": "Bestellung an Tisch A12 geliefert"
}

Request-Schema

OrderUpdate

Feld	Typ	Erforderlich	Beschreibung
newState	string	Ja	Ziel-Bestellstatus (siehe gültige Werte unten)
comment	string oder null	Nein	Optionaler Kommentar oder Nachricht (wird als Bestellnachricht gespeichert)

Gültige newState-Werte

Wert	Beschreibung
SELECTING	Kunde wählt Artikel
NEW	Neu erzeugte Bestellung
PLACED	Bestellung wurde vom Kunden aufgegeben
COMPLETED	Bestellung wurde erfolgreich erfüllt
ABORTED	Bestellung wurde storniert
FAILED	Bestellverarbeitung ist fehlgeschlagen

Lebenszyklus und Fehlerbehandlung

Integrationen bestätigen eine aufgegebene Bestellung normalerweise mit COMPLETED, stornieren sie mit ABORTED oder melden FAILED. Der Endpunkt nimmt einen OrderState an, ohne den bisherigen Zustand gegen eine Übergangstabelle zu prüfen. Eine Statusänderung ist keine Reservierung oder atomare Besitzprüfung.

FAILED erhöht den Fehlerzähler. Unterhalb der konfigurierten Lizenzgrenze wird sofort wieder PLACED zurückgegeben; an der Grenze bleibt FAILED mit Mitarbeiterhinweis. Prüfen Sie den zurückgegebenen Zustand.

Mit passendem Zugriff stehen GET /orders/failed, POST /orders/{orderId}/retry und POST /commands/{id}/retry für die Wiederherstellung bereit. Eine manuelle Wiederholung setzt den Zähler zurück. Der Personalablauf steht unter Nachrichten.

Antwort

Erfolg: 200 OK mit dem aktualisierten Order-DTO:

{
  "number": 12345,
  "userNumber": 5,
  "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": "COMPLETED",
  "orderTime": "10:30:00",
  "completeTime": "10:35:00",
  "tableNumber": "A12",
  "deviceNames": "service-device-1",
  "message": "Bestellung an Tisch A12 geliefert",
  "version": 2
}

Das Feld state zeigt den neuen Status an. Die completeTime wird automatisch vom Server gesetzt, wenn in den Status COMPLETED oder ABORTED gewechselt wird.

Curl-Beispiele

Erfolg: Bestellung als abgeschlossen markieren

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "COMPLETED", "comment": "Bestellung an Tisch A12 geliefert"}' \
  "https://{host}/orders/12345/statusupdate"

Antwort:

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

{
  "number": 12345,
  "state": "COMPLETED",
  ...
}

Erfolg: Bestellung stornieren

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "ABORTED", "comment": "Kunde storniert"}' \
  "https://{host}/orders/12345/statusupdate"

Ungültiger Zustandsname

Verwenden Sie die oben aufgeführten Enum-Namen. Ein unbekannter Name wie NOT_A_STATE ist ungültig. Prüfen Sie die Fehlerantwort Ihrer eingesetzten API-Version.

Bestellung nicht gefunden

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "COMPLETED"}' \
  "https://{host}/orders/99999/statusupdate"

Antwort:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "about:blank",
  "title": "Illegal argument",
  "status": 400,
  "detail": "Order does not exist",
  "instance": "/orders/99999/statusupdate"
}

Wiederholte und gleichzeitige Aktualisierungen

Eine wiederholte Statusänderung wird nicht automatisch wegen des bereits geänderten Zustands abgelehnt. Speichern Sie Bestellnummer und Verarbeitungsergebnis dauerhaft und koordinieren Sie mehrere Worker vor der externen Übergabe. Eine erfolgreiche Aktualisierung bestätigt keinen exklusiven Besitz. Eine verlorene Antwort beweist keinen Fehlschlag.

Setzen Sie keine automatische Wiederholung von Sperrkonflikten durch diesen Endpunkt voraus. Prüfen und gleichen Sie das Ergebnis ab, bevor Sie eine externe Aktion wiederholen.

Fehlerbehandlung

Status	Bedeutung
200	Bestellstatus erfolgreich aktualisiert
400	Ungültiger Zustandsübergang, ungültiger Enum-Wert oder Bestellung nicht vorhanden
401	Nicht autorisiert (ungültiger oder abgelaufener API-Schlüssel)
409	Optimistischer Sperrkonflikt (ein anderes Gerät hat die Bestellung gleichzeitig geändert)

Behandeln Sie Konflikte anhand der tatsächlichen Antwort Ihrer API-Version. Setzen Sie keine automatische dreifache Wiederholung dieses Endpunkts voraus.

Nächste Schritte

• Auf Befehle antworten — Antworten auf Befehle senden, die über Polling empfangen wurden
• Fehlerbehandlung — Fehlerantwortformate und Randfälle verstehen