Buchungsablauf

Das Widget ist ein Client der öffentlichen API und nicht mehr: Es hält keinen Zustand auf unserer Seite, und jeder Bildschirm, den ein Gast sieht, ist das Ergebnis eines von vier Aufrufen. Diese Anleitung geht die Aufrufe in der Reihenfolge durch, in der sie passieren – was das Widget in jedem Schritt zeigt und sendet und was Ihre Seite beobachten kann und was nicht. Wenn Sie statt des Widgets eine eigene Oberfläche bauen, ist das die Abfolge, die Sie nachbilden.

Die vier Aufrufe, in ihrer Reihenfolge

Jeder Aufruf trägt den übergebenen publishableKey als X-BookDinePlay-Key, und die API antwortet nur, wenn die Origin der Seite auf der Liste dieses Schlüssels steht (Origins). Das Widget legt nie einen Payment Intent an – siehe Anzahlungen.

Schritt für Schritt

Das Widget rendert fünf Schritte unter einer Fortschrittsleiste. Während die Verfügbarkeit lädt, zeigt der Schritt einen Ladezustand; während die Reservierung läuft, zeigt der Button „Confirming...“ und ist deaktiviert; die Aufrufe für Location und Tischplan zeigen nichts an. Eine fehlgeschlagene Anfrage zeigt ein rotes Banner über dem aktuellen Schritt und lässt den Gast, wo er war.

1. Was buchen

Eine Karte pro Typ aus resourceTypes. Die Wahl setzt zugleich die Standard-Buchungsdauer der Location für diesen Typ, sodass eine für Darts gewählte Dauer nie auf einen Restauranttisch übergeht. Bei einem einzigen Typ ist er vorausgewählt, der Schritt erscheint trotzdem.

2. Datum und Personenzahl

Ein Datum (heute oder später), eine Personenzahl von 1 bis 12 (Standard 2) und – nur wenn die Location Gäste für diesen Typ eine Dauer wählen lässt und mehr als eine anbietet – eine Auswahl „How long?“, vorbelegt mit dem Standard der Location. „See available times“ prüft das Datum und sendet die Verfügbarkeitsabfrage.

3. Freie Zeiten

Die von der API gelieferten Slots, nur die freien, jeweils mit Zeitspanne, Name der Ressource und einem „from“-Preis, wenn der Slot einen trägt. Ein Tag ohne freie Zeiten zeigt „No open times for this date and party size.“ und den Hinweis, ein anderes Datum oder eine kleinere Gruppe zu versuchen. Hat die Location einen Tischplan mit platzierten Ressourcen dieses Typs veröffentlicht und ist mindestens ein Slot frei, wählt der Gast stattdessen eine Uhrzeit und dann einen Tisch auf dem Plan; „List view“ wechselt zurück zur Liste. Die Wahl eines Slots und „Continue“ – oder das Antippen eines Tisches auf dem Tischplan – führt zu Schritt 4.

4. Kontaktdaten und die optionale Anzahlung

Name und E-Mail müssen ausgefüllt sein, damit der Button aktiv wird; Telefon und Notizen sind im Formular optional. Wo zutreffend, zeigt der Schritt zusätzlich eine Auswahl „Spiele pro Person“ (1–10) für einen Slot mit Preis pro Spiel und die Extras der Location für diesen Ressourcentyp mit je einer Menge. Zuletzt ein Kontrollkästchen – „Secure my spot with a deposit“ –, standardmäßig nicht angekreuzt. „Confirm reservation“ sendet die Reservierung.

5. Bestätigung

„Reservation confirmed“ – oder „Reservation received“, wenn die Reservierung als Pending zurückkam – mit der Referenz (BDP-XXXX), der Location, dem Was und Wann der Buchung, der Personenzahl, dem Namen, der Preisschätzung und, falls zutreffend, dem Anzahlungsbetrag. Die API hat dem Gast bis dahin Referenz und Status per E-Mail geschickt. „Make another booking“ setzt auf Schritt 1 zurück; Profil und Tischplan der Location bleiben erhalten und werden nicht erneut geladen.

Was das Widget sendet

Der Query-String der Verfügbarkeitsabfrage, gebildet aus den Schritten 1 und 2:

Der Reservierungs-Body, gebildet aus dem gewählten Slot und Schritt 4. Jedes Feld ist immer vorhanden; was nicht zutrifft, ist null:

{
  "resourceType": "RestaurantTable",
  "resourceId": "table-4a",
  "date": "2026-10-16",
  "start": "19:00",
  "end": "21:00",
  "partySize": 4,
  "games": null,
  "durationMinutes": null,
  "extras": null,
  "customerName": "Ada Lovelace",
  "email": "ada@example.com",
  "phone": "+49 30 1234567",
  "notes": "",
  "depositOptIn": false
}

Was Ihre Seite beobachten kann

renderBookingWidget gibt die Widget-Instanz zurück – oder null, wenn es das Rendern verweigert hat (Wenn es nicht rendert). Das ist die ganze Schnittstelle: Das Widget löst keine DOM-Events aus, nimmt keine Callbacks entgegen, und die Felder der Instanz gehören nicht zum Vertrag. Um auf Ihrer Seite auf eine abgeschlossene Buchung zu reagieren – Analytics, eine Dankeseite, Ihr eigenes CRM –, bauen Sie mit window.BookDinePlay.createClient – dem Headless-Client, auf dem das Widget selbst läuft – einen eigenen Ablauf auf denselben vier Aufrufen (Eigene Formulare).

Anzahlungen

Das Ankreuzen sendet depositOptIn: true. Eine Anzahlung ist dann nur erforderlich, wenn die Location Anzahlungen aktiviert hat und die Ressource – oder der Standard der Location für Spielressourcen – einen Anzahlungsbetrag trägt; alle drei oder keins (Anzahlungen). Ist sie erforderlich, kommt die Reservierung als Pending mit depositRequired: true und einem depositAmount zurück; das Widget zeigt „Reservation received“ und die Anzahlungszeile, und die E-Mail an den Gast nennt den Status Pending. Das Widget zieht das Geld nicht ein: Die Location bestätigt die Buchung in ihrer Konsole, oder eine serverseitige Integration legt einen Payment Intent über depositAmount an. Ohne Anzahlung – Kästchen nicht angekreuzt oder Location nicht dafür eingerichtet – ist die Reservierung sofort Confirmed.

Wenn ein Aufruf fehlschlägt

• Profil oder Tischplan – das Widget macht ohne sie weiter: keine Extras, keine Dauerauswahl, die Liste statt des Plans.
• Verfügbarkeit – „We could not load available times. Please check your connection and try again.“ Der Gast bleibt in Schritt 2.
• Reservierung – „We could not confirm your reservation. Please review your details and try again.“ Der Gast bleibt in Schritt 4. Es ist dasselbe Banner für einen Validierungsfehler (400), einen inzwischen vergebenen Slot (409) und einen abgelehnten Schlüssel (401/403); der Netzwerk-Tab des Browsers zeigt den Problem-type – Fehler erklärt jeden.
• Eine überholte Anfrage – klickt der Gast erneut, bevor eine Antwort da ist, wird die frühere Anfrage abgebrochen und ihre Antwort ignoriert.

Nächste Schritte

• Azure Static Web Apps – das Widget auf eine Live-Seite bringen, von null bis zur eigenen Domain.
• Reservierungen – jedes Feld der Buchung, die das Widget anlegt, und die 409, die es bekommen kann.
• JavaScript-SDK – Optionen, Isolation und CSP-Regeln für die Seite, die es einbettet.