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.

GET /api/qr/{token} und die Tischsitzungs-Endpunkte darunter brauchen keinen Schlüssel: Das Token in der URL ist bereits ein an die Location gebundenes, widerrufbares Zugangsmerkmal, das auf dem Tisch gedruckt ist.

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, 404 keine solche Location, Reservierung, kein solches 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), 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. Seien Sie ein guter Nachbar: Cachen Sie Antworten zu Location, Speisekarten und Öffnungszeiten auf Ihrer Seite (sie ändern sich selten) und fragen Sie die Verfügbarkeit für das Datum ab, das ein Gast gerade ansieht, nicht für einen ganzen Monat. Ein Limit wird, wenn es kommt, vorab angekündigt und mit 429 und einem Retry-After-Header signalisiert.

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.