Entwicklerdokumentation

Reservierungen

Eine Reservierung für einen angebotenen Slot anlegen – Anfragefelder, die zurückgegebene Reservierung, Anzahlungen, Gruppenbuchungen und jede Ablehnung.

Ein Aufruf bucht einen Slot. Senden Sie Ressourcentyp, Datum und Beginn, die der Gast aus der Verfügbarkeit gewählt hat, die Gruppengröße und die Kontaktdaten des Gastes; zurück kommt eine Reservierung mit einer Referenz, die der Gast nennen kann, einem Status sowie Preis und Anzahlung, die gelten.

Endpunkte

POST /api/venues/{venueSlug}/reservations

Request-Body (Content-Type: application/json)

Feld Erforderlich Bedeutung
resourceType ja Der Typ des Slots, z. B. RestaurantTable
resourceId nein Die resourceId des Slots, um genau diese Ressource zu bekommen. Weggelassen: die erste freie Ressource des Typs zu dieser Zeit
date ja Ortszeit yyyy-MM-dd
start ja Ortszeit HH:mm, ein start, den die Verfügbarkeit angeboten hat
end nein Ortszeit HH:mm; Standard ist start plus Buchungsdauer
durationMinutes nein 15–1440. Denselben Wert senden, mit dem Sie die Verfügbarkeit abgefragt haben, oder weglassen für den Standard der Location
partySize ja 1–200
games nein 1–10, bei Ressourcen mit Preis pro Spiel; Standard 1
customerName ja 2–120 Zeichen
email ja Eine gültige E-Mail-Adresse – dorthin geht die Bestätigung
phone nein 3–40 Zeichen, wenn angegeben; ein leerer Wert gilt als nicht angegeben
notes nein Bis 500 Zeichen, für die Location sichtbar
depositOptIn nein true, wenn der Gast einer Anzahlung zustimmt; wirkt nur, wenn die Location Anzahlungen aktiviert hat
extras nein [{ "extraId": "…", "quantity": 1 }] – Extras aus dem Profil der Location, die für diesen Ressourcentyp gelten, Menge 1–100

Antwort 201 Created mit einem Location-Header /api/venues/{venueSlug}/reservations/{reference} (informativ – einen öffentlichen Lese-Endpunkt gibt es noch nicht).

Feld Typ Bedeutung
id GUID Interne Id
reference string BDP-XXXX – was der Gast nennt und worauf sich ein Payment Intent bezieht
status string Confirmed, oder Pending, wenn eine Anzahlung nötig und noch nicht bezahlt ist; später Cancelled, Completed, NoShow
venueSlug, resourceType, resourceName string Wo
date, start, end string Wann, in Ortszeit
partySize, customerName Wer
priceEstimate, currency decimal, string Der Preis der Buchung nach dem Modell der Ressource
depositRequired, depositAmount boolean, decimal oder null Ob der Gast zur Bestätigung eine Anzahlung leisten muss, und wie viel
createdAt ISO-8601-Zeitpunkt Wann die Reservierung angelegt wurde
groupReference, groupResources string oder null, object[] oder null Bei einer Gruppenbuchung: die gemeinsame Referenz und jedes Mitglied (resourceId, resourceName, partyShare)
games integer oder null Bei Preis pro Spiel
extras, extrasTotal object[] oder null, decimal oder null Bepreiste Extra-Positionen (extraId, name, unitPrice, quantity, lineTotal, currency, basis) und ihre Summe 
{
  "id": "cad35696-0a75-45b6-b986-8bed7eb00ac5",
  "reference": "BDP-KSQS",
  "status": "Confirmed",
  "venueSlug": "demo-sportsbar",
  "resourceType": "RestaurantTable",
  "resourceName": "Corner table",
  "date": "2026-10-16",
  "start": "15:00",
  "end": "17:00",
  "partySize": 4,
  "customerName": "Ada Lovelace",
  "priceEstimate": 0,
  "currency": "EUR",
  "depositRequired": false,
  "depositAmount": null,
  "createdAt": "2026-09-15T12:55:15.1526956+00:00",
  "groupReference": null,
  "groupResources": null,
  "games": null,
  "extras": null,
  "extrasTotal": null
}

Fehler

Status Wann
400 Ein Feld scheitert an der Validierung (errors nennt es); date/start fehlerhaft; die Location ist dann geschlossen; die Dauer ist keine, die die Location für diesen Typ anbietet; ein Extra gilt nicht
404 Keine Location mit diesem Slug
409 Keine Ressource dieses Typs ist zu dieser Zeit frei – sie wurde seit der Verfügbarkeitsabfrage vergeben. Neu abfragen und den nächsten Slot anbieten

curl

curl -X POST "https://api.bookdineplay.com/api/venues/your-venue/reservations" \
  -H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
  -H "Origin: https://www.your-venue.example" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "RestaurantTable",
    "date": "2026-10-16",
    "start": "19:00",
    "partySize": 4,
    "customerName": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": "+49 30 1234567",
    "notes": "Window seat if possible"
  }'

JavaScript

const response = await fetch('https://api.bookdineplay.com/api/venues/your-venue/reservations', {
  method: 'POST',
  headers: { 'X-BookDinePlay-Key': 'bdp_pk_your_publishable_key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    resourceType: 'RestaurantTable', date: '2026-10-16', start: '19:00', partySize: 4,
    customerName: 'Ada Lovelace', email: 'ada@example.com', phone: '+49 30 1234567',
    notes: 'Window seat if possible'
  })
});
if (response.status === 409) { /* Slot gerade vergeben – Verfügbarkeit neu abfragen */ }
const reservation = await response.json();
console.log(reservation.reference, reservation.status);

C#

try
{
    var reservation = await client.CreateReservationAsync("your-venue", new CreateReservationRequest
    {
        ResourceType = BookableResourceType.RestaurantTable,
        Date = "2026-10-16",
        Start = "19:00",
        PartySize = 4,
        CustomerName = "Ada Lovelace",
        Email = "ada@example.com",
        Phone = "+49 30 1234567",
        Notes = "Window seat if possible"
    }, cancellationToken);
    Console.WriteLine($"{reservation.Reference} {reservation.Status}");
}
catch (BookDinePlayApiException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // Slot gerade vergeben – Verfügbarkeit neu abfragen
}

Anzahlungen

Eine Reservierung braucht eine Anzahlung, wenn drei Dinge zutreffen: Der Gast hat depositOptIn: true gesendet, die Location hat Anzahlungen aktiviert, und die Ressource (oder der Standard der Location für Spielressourcen) trägt einen Anzahlungsbetrag. Dann ist depositRequired true, depositAmount nennt den Betrag, und status bleibt Pending, bis die Location die Buchung bestätigt. Legen Sie als Nächstes einen Payment Intent über diesen Betrag an. Ohne Anzahlung ist die Reservierung sofort Confirmed.

Gruppenbuchungen

Übersteigt partySize die Kapazität einer Ressource und hat die Verfügbarkeit einen Gruppen-Slot angeboten, erstreckt sich die Reservierung über mehrere Ressourcen: groupReference ist die gemeinsame Referenz, und groupResources listet jedes Mitglied mit seinem Anteil an der Gruppe. Extras werden einmal für die ganze Gruppe berechnet.

Nächste Schritte