API-Referenz

Alles, was das Widget, die SDKs und das WordPress-Plugin tun, tun sie über diese API. Sie ist schlichtes HTTPS mit JSON unter https://api.bookdineplay.com, eine Location pro URL, und auf jedem Endpunkt gelten dieselben Regeln: ein Schlüssel bei jedem Aufruf unter /api/venues/**, Datum und Uhrzeit in der Ortszeit der Location und RFC-7807-Problem-Bodys, wenn etwas abgelehnt wird. Diese Seite enthält die Regeln, die Seiten darunter die Endpunkte.

Basis-URL und Versionierung

Die Basis-URL ist https://api.bookdineplay.com. Der Pfad enthält kein Versionssegment: Änderungen sind additiv (neue optionale Felder, neue Endpunkte) und entfernen oder benennen nie um, was hier dokumentiert ist. Jede Antwort ist application/json (application/problem+json bei Fehlern) in UTF-8. Die Beispiele auf diesen Seiten verwenden diese Basis-URL; wenn Sie angemeldet sind, zeigen sie außerdem Ihren eigenen Venue-Slug und veröffentlichbaren Schlüssel statt Platzhaltern.

Schlüssel und Header

Jede Anfrage unter /api/venues/** trägt einen Schlüssel – es gibt keine anonyme Stufe – als X-BookDinePlay-Key: <key> oder Authorization: Bearer <key>, nie im Query-String. Ein veröffentlichbarer Schlüssel (bdp_pk_…) ist für Browser: Die Anfrage muss einen Origin-Header tragen, der auf der Liste des Schlüssels steht. Ein geheimer Schlüssel (bdp_sk_…) ist für Server: Die Anfrage darf keinen Origin tragen. Authentifizierung hat die vollständigen Regeln; Fehler jede Ablehnung.

Einige Routen brauchen keinen Schlüssel, weil die URL selbst ein Zugangsmerkmal trägt, das der Gast außerhalb Ihrer Website erhalten hat: GET /api/qr/{token} und die Tischsitzungs-Endpunkte darunter (das Token ist auf dem Tisch gedruckt); die Event-Routen GET /api/tickets/{code}, GET /api/registrations/{cancelToken} und POST /api/event-registrations/{cancelToken}/cancel sowie die eigene Buchung des Gasts unter GET /api/reservations/{cancelToken} und POST /api/reservations/{cancelToken}/cancel (Code und Tokens kommen per E-Mail); und die Gutscheinabfrage GET /api/vouchers/{code} (der Code steht auf dem Gutschein). Insgesamt elf, jede an eine Location gebunden. Das QR-Token ist widerrufbar und wird bei Bedarf über die Konsole neu gedruckt; die anderen sind an Anmeldung, Buchung oder Gutschein gebundene Berechtigungen – Events erklärt, warum, und Gutscheine, was das für einen Gutscheincode heißt. Nur die Bestellrouten und die Tab-Zahlung hängen vom Tarif der Location ab.

Zwei optionale Header gelten überall: Accept-Language: de liefert ein deutsches detail in Problem-Bodys (Englisch ist der Standard); title wird nie lokalisiert – es ist der Statustext des Frameworks – und Content-Type: application/json ist bei jedem POST erforderlich.

Datum, Uhrzeit und Zeitzonen

Die API spricht die Ortszeit der Location, nie UTC-mit-Offset für etwas, das ein Gast wählt:

Ein start von 19:30 am 2026-10-16 bedeutet 19:30 Uhr in Europe/Berlin an diesem Datum. Rechnen Sie nur auf Ihrer Seite um, wenn Sie einen Zeitpunkt brauchen; senden Sie nie einen Offset in einem Datums- oder Zeitfeld – die API lehnt ihn als ungültig ab.

Aufzählungen (resourceType, status, pricingModel, basis) sind Zeichenketten, genau so geschrieben wie in den Tabellen der Endpunktseiten, und unterscheiden Groß- und Kleinschreibung.

Fehler

Alles, was die API ablehnt, ist ein RFC-7807-Problem-Body mit dem passenden HTTP-Status:

{
  "type": "https://bookdineplay.com/docs/api/errors/origin-not-allowed",
  "title": "Forbidden",
  "status": 403,
  "detail": "This origin is not on the API key's list of allowed origins.",
  "traceId": "0HNOJ52B2L9BD"
}

• type ist eine URL. Bei einem Schlüsselproblem zeigt sie auf den Abschnitt von Fehler, der es erklärt; sonst ist es der allgemeine Link auf den RFC-9110-Abschnitt.
• title ist der Statustext; detail der Satz, den Sie einem Entwickler zeigen (lokalisiert per Accept-Language).
• traceId steht in jedem Problem, sentryId zusätzlich, wenn ein Fehler erfasst wurde – nennen Sie beide, wenn Sie den Support anschreiben.
• Ein Validierungsfehler (400) ergänzt ein Objekt errors mit den Feldnamen als Schlüssel:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "PartySize": [
      "The field PartySize must be between 1 and 200."
    ],
    "CustomerName": [
      "The CustomerName field is required."
    ]
  },
  "traceId": "0HNOJ52B2L9BA"
}

Status, die Sie sehen werden: 400 ungültige Eingabe, 401 kein oder unbekannter Schlüssel, 403 der Schlüssel ist in Ordnung, aber nicht für diese Anfrage, oder der Tarif der Location enthält die Funktion nicht, 404 keine solche Location, Reservierung, kein solches Event, Token oder keine solche Sitzung, 409 die Anfrage war gültig, aber die Welt hat sich weitergedreht (Slot vergeben, Rechnung bereits geschlossen, Zahlungen nicht aktiviert, Event-Anmeldung geschlossen oder ausverkauft), 5xx unser Fehler – mit Backoff wiederholen und die traceId aufheben.

CORS und Preflight

Die API beantwortet den OPTIONS-Preflight eines Browsers für jeden Pfad unter /api/venues/** mit GET, POST, OPTIONS, den Request-Headern X-BookDinePlay-Key, Authorization, Content-Type, Accept-Language und Access-Control-Max-Age: 600 – für jeden Origin und jeden Pfad unter dem Präfix identisch, weil ein Preflight keinen Schlüssel zu prüfen hat. Jede Route unter /api/venues/**, POST /api/venues/{venueSlug}/messages eingeschlossen, verlässt die pauschale CORS-Middleware des Frameworks; ein Access-Control-Allow-Origin: * gibt es nicht. Bei der darauffolgenden tatsächlichen Anfrage setzt die Schlüsselprüfung selbst diesen Header – bei einem veröffentlichbaren Schlüssel nur, wenn sein Origin auf der eigenen Liste des Schlüssels steht (Origins) – und das ist das eigentliche Tor, nicht der Preflight.

Ratenbegrenzung

Es gibt heute keine erzwungene Ratenbegrenzung pro Schlüssel, und das bleibt nicht für immer so. Die eine begrenzte Route ist die schlüssellose Gutscheinabfrage, die keinen Schlüssel zum Zählen hat: 30 Abfragen pro Minute und Client. Ratenbegrenzung hat die großzügigen Richtwerte, auf die Sie trotzdem planen sollten, was wir tun, wenn ein Client wirklich weit darüber liegt, und die Client-Gewohnheiten – Entprellen, Cachen, Backoff bei 5xx – die jede echte Integration bequem darunter halten.

Nächste Schritte

• Venue – die Lesezugriffe, mit denen jede Integration beginnt.
• Verfügbarkeit – die Slots, die ein Gast buchen kann.
• Fehler – jede type-URL, erklärt.