Entwicklerdokumentation

Gäste vom Tisch aus bestellen lassen

Einen QR-Code pro Tisch drucken, Gäste per Scan auf eine Rechnung bestellen lassen und diese an der Bar oder per Karte begleichen – ohne API-Schlüssel.

Ein QR-Code auf dem Tisch macht das Handy des Gastes zum Bestellblock: scannen, aus der Karte wählen, bestellen, die Rechnung wachsen sehen, am Ende bezahlen. Dieses Tutorial richtet es ein und führt die Seite des Gastes durch die API, die keinen Schlüssel braucht – das Token im QR-Code ist das Zugangsmerkmal.

Die QR-Bestellung braucht den Tarif Pro oder höher. Die Rechnung per Karte zu bezahlen braucht Premium, eingeschaltete Online-Zahlungen und ein verbundenes Stripe-Auszahlungskonto; ein Gast kann stattdessen immer an der Bar zahlen.

1. Menüs und Ressourcen vorbereiten

Ein Gast bestellt aus den Menüs der Ressource, die er gescannt hat. Ein Menü ist Food oder Drinks, aufgebaut aus Gruppen und Artikeln mit Preisen; Artikelnamen müssen innerhalb eines Menüs eindeutig sein, weil eine Bestellung ihre Artikel beim Namen nennt. Welche Menüs ein Tisch anbietet, hängt von der Ressource ab: Ein Restaurant-Tisch darf aus beiden bestellen, ein Billardtisch nur aus dem Getränkemenü. Prüfen Sie die Bestelleinstellung jeder Ressource in der Konsole, bevor Sie Codes drucken, und siehe Menüs und Ressourcen.

2. Die Codes erzeugen

Wählen Sie im QR-Bereich der Konsole QR-Codes erzeugen (qr_codes_generate über MCP): Jede Ressource der Location bekommt einen aktiven Code, und ein erneuter Lauf ergänzt nur Ressourcen, die noch keinen haben. Drucken Sie sie von dort. Ein Code zeigt auf eine Seite auf app.bookdineplay.com mit dem Token in der Adresse.

Behandeln Sie einen gedruckten Code wie einen Schlüssel zu genau diesem Tisch:

  • Neu erzeugen, wenn ein Code durchgesickert ist oder ein Aufkleber kopiert wurde; das alte Token funktioniert sofort und für immer nicht mehr, und das neue muss gedruckt werden. Das Neuerzeugen verlangt über MCP zuerst eine Bestätigung.
  • Nie ein Token in Analytics, Logs oder eine Seite schreiben, die andere Gäste sehen.

3. Was ein Gast sieht

Die Abfolge hinter der Seite, die Sie auf Ihrer eigenen Seite nachbauen können – keine dieser Routen nimmt einen Schlüssel:

Schritt Aufruf Hinweise
Scannen GET /api/qr/{token} Location, Tischname und -typ, genug für „Tisch 4 im The Neon Tap“. 404 bei unbekanntem oder widerrufenem Token oder einer Location ohne Berechtigung
Karte öffnen GET /api/qr/{token}/session Die Menüs dieses Tisches und die laufende Rechnung. isOpen ist false bis zur ersten Bestellung
Bestellen POST /api/qr/{token}/orders Eine oder mehrere Positionen. Die erste Bestellung öffnet die Rechnung; der Preis jeder Position steht in diesem Moment fest
Bezahlen POST /api/qr/{token}/payment Kartenzahlung der ganzen Rechnung über Stripe
Schließen POST /api/qr/{token}/close Die Rechnung: Positionen, Zwischensumme, enthaltene Steuer, Summe

Eine Bestellung nennt ein Menü über seine id und einen Artikel über seinen name, wie sie in der Sitzung stehen:

curl

curl -X POST "https://api.bookdineplay.com/api/qr/<token>/orders" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [ { "menuId": "kitchen", "itemName": "Smash burger", "quantity": 2 }, { "menuId": "bar", "itemName": "House lager", "quantity": 1 } ] }'

JavaScript

const updated = await (await fetch(`https://api.bookdineplay.com/api/qr/${encodeURIComponent(token)}/orders`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ lines: [{ menuId: 'kitchen', itemName: 'Smash burger', quantity: 2 }] })
})).json();
console.log(updated.runningTotal, updated.currency);

C#

var updated = await client.PlaceOrderAsync(token, new PlaceOrderRequest([
    new OrderLineRequest("kitchen", "Smash burger", 2),
    new OrderLineRequest("bar", "House lager", 1)
]), cancellationToken);

PHP

<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/qr/' . rawurlencode( $token ) . '/orders', [
    'headers' => [ 'Content-Type' => 'application/json' ],
    'body'    => wp_json_encode( [ 'lines' => [ [ 'menuId' => 'kitchen', 'itemName' => 'Smash burger', 'quantity' => 2 ] ] ] ),
] ); // sends no key
$updated = json_decode( wp_remote_retrieve_body( $response ), true );

Die ganze Bestellung wird mit 400 abgelehnt, wenn eine Position ein Menü oder einen Artikel nennt, der an diesem Tisch nicht bestellbar ist: Es wird nichts aufgegeben. Eine Rechnung, die zwischen dem letzten Lesen des Gastes und der Bestellung geschlossen wurde, antwortet 409; lesen Sie die Sitzung neu, und die nächste Bestellung öffnet eine frische Rechnung.

4. Was das Personal sieht

Bestellungen erscheinen in der Bestellansicht der Konsole pro Tisch (orders_list), mit den Positionen, Mengen und der laufenden Summe.

5. Die Rechnung bezahlen

An der Bar. Das Personal schließt die Rechnung in der Konsole, oder der Gast schließt sie mit POST …/close und erhält die Rechnung. Das Schließen wird nie durch eine noch offene Kartenzahlung blockiert, weil ein Gast immer Bargeld auf den Tisch legen kann.

Per Karte. POST /api/qr/{token}/payment friert die Rechnung 31 Minuten lang auf ihrer aktuellen Summe ein, öffnet eine Stripe-Checkout-Sitzung auf dem eigenen Konto der Location und liefert die checkoutUrl, an die der Gast geschickt wird:

curl

curl -X POST "https://api.bookdineplay.com/api/qr/<token>/payment"

JavaScript

const payment = await (await fetch(`https://api.bookdineplay.com/api/qr/${encodeURIComponent(token)}/payment`, { method: 'POST' })).json();
location.href = payment.checkoutUrl;

C#

var payment = await client.StartTabPaymentAsync(token, null, cancellationToken);

PHP

<?php
$response = wp_remote_post( 'https://api.bookdineplay.com/api/qr/' . rawurlencode( $token ) . '/payment' ); // sends no key
$payment = json_decode( wp_remote_retrieve_body( $response ), true );

Drei Verhaltensweisen sind Absicht:

  • Die Rechnung ist eingefroren, solange eine Zahlung läuft. Der Betrag, den Stripe einzieht, steht fest, wenn Checkout sich öffnet; eine danach hinzugefügte Bestellung bliebe unbezahlt. POST …/orders antwortet 409, und die Sitzung meldet paymentPending mit derselben paymentUrl, sodass ein zweites Handy am Tisch die laufende Zahlung sieht. Bricht der Gast den Checkout ab, endet das Einfrieren von selbst, und die Rechnung nimmt wieder Bestellungen an.
  • Zwei Taps ergeben eine Zahlung. Ruft man die Route erneut auf, während eine Zahlung läuft, kommt derselbe Checkout zurück. Die Rechnung selbst ist der Anspruch, das Handy des Gastes braucht also keinen Idempotenz-Header.
  • Eine abgeschlossene Zahlung schließt die Rechnung. Sie rufen nicht zusätzlich …/close auf. Hat ein Gast auch an der Bar bezahlt, wird die Kartenzahlung trotzdem erfasst, weil sie echt und erstattbar ist; die Location kann dann doppelt bezahlt worden sein und entscheidet, was sie zurückgibt.

Mit einem Geschenkgutschein. Fügen Sie dem Body voucherCode hinzu, und ein Betrags- oder Prozentgutschein zahlt, was er kann; die Karte zahlt den Rest, nie unter Stripes Minimum. Ein Gutschein, der die ganze Rechnung deckt, öffnet keine Stripe-Sitzung: Die Rechnung wird sofort beglichen und geschlossen, und paidInFull ist true (Gutscheine). Das Personal kann einen Gutschein auch am Tisch anwenden; die Sitzung zeigt dann das Guthaben und den amountDue.

6. Grenzen und Fehlerfälle

  • Keine Berechtigung der Location, gesperrte Location, widerrufener Code: Das Token antwortet überall 404. Der Gast sieht „Dieser Tisch ist nicht verfügbar“.
  • Kartenzahlung gerade nicht möglich – Zahlungen aus, Tarif oder Auszahlungskonto nicht fertig: Die Zahlungsroute antwortet 409. Bieten Sie das Bezahlen an der Bar an.
  • Eine Rechnung von 0,50 € oder weniger, die ein Gutschein nicht deckt, lässt sich nicht per Karte bezahlen: 409 mit reason below-card-minimum.

Nächste Schritte