HTTP-API

Basis lokal: http://127.0.0.1:8765/orca/api. Auf dem Hosting relativ zum Portal: api/. POST-Anfragen verwenden JSON und Content-Type: application/json. Standard: gemeinsame Simulation für alle Besucher. Optional ORCA_DEMO_MODE=session für getrennte Browserwelten. HttpOnly-Cookie orca_demo, keine Benutzeranmeldung.

OpenAPI 3.1 herunterladen

Methode / Pfad	Inhalt / Wirkung
POST /session	`{}` – Sitzung starten oder vorhandene laden, vollständiger Zustand
GET /state	Artikel, Aufträge, Verkäufe, Nachrichten, Demo-Uhr
GET /tech	Die letzten 100 Ereignisse, auch während laufender Roboterdialoge abrufbar
POST /cart	`{"persona":"guest","article":"2119478","quantity":2}` – unverbindliche Warenkorbmenge; 0 entfernt; keine Roboterdialoge
POST /reserve	`{"order_id":"…"}` – gesamten Warenkorb verbindlich reservieren; Checkout-Frist beginnt
POST /pay	`{"order_id":"…","mode":"normal"}`; normal / delayed (ca. 10 Sekunden, serverseitig) / decline
GET /qr/{order_id}	SVG-Abholcode der Simulation
POST /pickup	`{"token":"ORCA:…"}` – Ausgabe starten oder vorhandenen Zustand zurückliefern
POST /cancel	`{"order_id":"…"}` – unbezahlte Reservation freigeben und Warenkorb bearbeiten; unverbindlichen Warenkorb leeren
POST /recover	`{}` – unsichere Ausgabe abfragen, ausstehende Commit-/Buchungsschritte wiederholen
POST /reset	`{}` – Simulation inklusive Roboterbestand, Aufträgen, Zahlungen, Verkäufen, Fehlerfällen und Uhr zurücksetzen
POST /journal/archive	`{"ids":["EVENT_ID"]}` – markiert Einträge als archiviert. Puffer: maximal 300 inklusive Archiv; älteste entfallen.
POST /advance	`{"seconds":900}`; erlaubt 60 / 300 / 900 / 1200 / 1680
POST /fault	`{"role":"gollmann","value":"lost_output_reply"}`

Vollständiges Beispiel in PowerShell

$base = 'http://127.0.0.1:8765/orca/api'
$state = Invoke-RestMethod "$base/session" -Method Post -ContentType 'application/json' -Body '{}' -SessionVariable demo
Invoke-RestMethod "$base/cart" -Method Post -ContentType 'application/json' -WebSession $demo -Body '{"persona":"guest","article":"2119478","quantity":2}'
$state = Invoke-RestMethod "$base/state" -WebSession $demo
$order = $state.orders | Select-Object -Last 1
Invoke-RestMethod "$base/reserve" -Method Post -ContentType 'application/json' -WebSession $demo -Body (@{order_id=$order.id} | ConvertTo-Json)
$body = @{order_id=$order.id; mode='normal'} | ConvertTo-Json
Invoke-RestMethod "$base/pay" -Method Post -ContentType 'application/json' -WebSession $demo -Body $body
$state = Invoke-RestMethod "$base/state" -WebSession $demo
$order = $state.orders | Select-Object -Last 1
$body = @{token=('ORCA:' + $order.pickup_token)} | ConvertTo-Json
Invoke-RestMethod "$base/pickup" -Method Post -ContentType 'application/json' -WebSession $demo -Body $body
(Invoke-RestMethod "$base/state" -WebSession $demo).sales

Beispieldatei auch in den Paketen unter integrations/demo-api.ps1. Preise werden serverseitig aus den simulierten Preisen des Beta-Katalogs berechnet; keine vom Client vorgegebene Summe wird übernommen.

Fehler und Wiederholung

400 ungültige Eingabe; 401 fehlende Sitzung; 404 unbekannter Auftrag/Code; 409 Zustandskonflikt oder unzureichender Bestand; 415 falscher Inhaltstyp; 429 Demolimit; 503 Verbindung oder Ergebnis ausstehend. Antwort: {"error":"…"}. Bei 503 erst Zustand lesen und recover verwenden. Nicht einen neuen Auftrag mit neuer Kennung erzeugen.

cart setzt absolute Mengen des aktiven Kundenkorbs. pay und pickup erkennen bekannte Vorgänge. Wiederholte ProPharma-Schritte haben dieselben dauerhaften Schrittkennungen. Nach vollständigem Abschluss beginnt ein erneutes cart bewusst einen neuen Kauf.

Demo-Steuerung Gollmann: none, partial, lost_output_reply, reserve_fail. ProPharma: none, offline, lost_booking_reply. Im Standardmodus wirken Steuerungen auf alle Besucher. Teilabgaben benötigen manuelle Klärung.

Interner WebSocket-Vertrag

Der Adapter verbindet sich mit /orca/adapter; Bearer-Schlüssel in .var/adapter-token. Eine Verbindung, Nachrichten mit Korrelationskennung:

{"id":"request-id","world":"demo-world-id","action":"reserve",
 "data":{"order_id":"order-id","items":{"2119478":2}}}

{"id":"request-id","ok":true,"result":{"ok":true,"packs":[]},"trace":[]}

Aktionen: inventory, reserve, release, commit, pickup, output_status, book. inspect und fault gehören nur zur Demo. Auf dem Hoststar-Hosting wird dieser interne Socket nicht veröffentlicht: Die PHP-Queue vermittelt nur die erlaubten HTTP-API-Aufträge zum lokal laufenden Kern.