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 teilt dem System mit, dass die Bestellung bearbeitet wurde, und verhindert doppelte Verarbeitung.

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
PLACED	Bestellung wurde vom Kunden aufgegeben
COMPLETED	Bestellung wurde erfolgreich erfüllt
ABORTED	Bestellung wurde storniert
FAILED	Bestellverarbeitung ist fehlgeschlagen

Gültige Zustandsübergänge

Das iorder-System verfolgt Bestellungen durch einen definierten Lebenszyklus. Nicht alle Übergänge sind gültig.

                     +---> COMPLETED
                     |
   PLACED -----------+
                     |
                     +---> ABORTED

   SELECTING -------> ABORTED

   PLACED ----------> FAILED

   FAILED ----------> PLACED (Wiederholung)

Gültige Übergänge für Service-Clients:

Von	Nach	Beschreibung
PLACED	COMPLETED	Bestellung erfüllt (häufigster Fall)
PLACED	ABORTED	Bestellung nach dem Aufgeben storniert
PLACED	FAILED	Fehler bei der Backend-Verarbeitung
SELECTING	ABORTED	Kundensitzung geschlossen, ohne dass eine Bestellung aufgegeben wurde

Der Status FAILED ist speziell: Bestellungen im Status FAILED werden von einem geplanten Job wiederholt, der sie zurück auf PLACED setzt. Danach kann der Client die Verarbeitung erneut versuchen.

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 Zustandsübergang

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "SELECTING", "comment": "Versuch rückgängig zu machen"}' \
  "https://{host}/orders/12345/statusupdate"

Antwort:

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

{
  "type": "about:blank",
  "title": "Illegal argument",
  "status": 400,
  "detail": "No enum constant com.ridme.pos.model.enums.OrderState.SELECTING",
  "instance": "/orders/12345/statusupdate"
}

Hinweis: Der Fehler verwendet das ProblemDetail (RFC 7807) Format.

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"
}

Doppelte und idempotente Aktualisierungen

Der Statusaktualisierungs-Endpunkt ist nicht von Natur aus idempotent. Wenn Sie dieselbe Statusaktualisierung zweimal senden, schlägt der zweite Aufruf fehl, da sich der Bestellstatus bereits vom ursprünglichen Zustand geändert hat. So gehen Sie damit um:

• Verfolgen Sie, welche Bestellungen Sie bereits verarbeitet haben, indem Sie die Bestell-number als Idempotenz-Schlüssel verwenden.
• Senden Sie Statusaktualisierungen nur für Bestellungen, die Sie noch nicht verarbeitet haben.
• Wenn eine Statusaktualisierung mit einem 400-Fehler fehlschlägt, überprüfen Sie den aktuellen Bestellstatus vor dem erneuten Versuch über Polling.

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)

Bei 409-Konflikten implementiert der Server automatische Wiederholungen mit bis zu 3 Versuchen. Wenn der Konflikt bestehen bleibt, sollte der Client seine Ansicht der Bestellung aktualisieren und es erneut versuchen.

Nächste Schritte

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