Entwicklerdokumentation

.NET-SDK

BookDinePlay.Sdk installieren, den Client mit einem geheimen Schlüssel registrieren und Verfügbarkeit und Reservierungen aus der eigenen Anwendung nutzen.

BookDinePlay.Sdk ist ein typisierter Client für die öffentliche API – für alles, was auf einem Server läuft: Ihre eigene Buchungsseite, ein internes Werkzeug, ein Dienst, der Reservierungen synchronisiert. Er gibt dieselben DTOs zurück wie die API und fügt nichts hinzu, was Sie nicht verlangt haben – keine Wiederholungen, kein Caching, keine Hintergrundarbeit.

Installation

dotnet add package BookDinePlay.Sdk

Zielplattform .NET 10. Die Contracts und die Schnittstelle IBookDinePlayClient liegen in BookDinePlay.Shared, das als Abhängigkeit mitkommt.

Client registrieren

Das SDK läuft auf einem Server und verwendet daher einen geheimen Schlüssel (bdp_sk_…), angelegt in der Konsole unter Location → API-Schlüssel und einmalig angezeigt. Halten Sie ihn in der Konfiguration oder einem Secret-Store, nie im Quelltext:

builder.Services.AddBookDinePlayClient(
    new Uri("https://api.bookdineplay.com"),
    builder.Configuration["BookDinePlay:ApiKey"]!);

Das registriert einen typisierten HttpClient, der den Schlüssel bei jeder Anfrage als X-BookDinePlay-Key sendet, und IBookDinePlayClient für die Injektion. Ein veröffentlichbarer Schlüssel funktioniert hier nicht: Die API lehnt ihn ohne Browser-Origin ab, und ein Server hat keine.

Location-Daten lesen

Jeder Lesezugriff gibt für eine unbekannte Location null zurück, statt eine Ausnahme zu werfen:

var venue = await client.GetVenueAsync("your-venue", cancellationToken);
var hours = await client.GetOpeningHoursAsync("your-venue", cancellationToken);
var menus = await client.GetMenusAsync("your-venue", cancellationToken);
var resources = await client.GetResourcesAsync("your-venue", cancellationToken);

GetBusinessInfoAsync und GetFloorPlanAsync vervollständigen den Satz.

Verfügbarkeit prüfen und buchen

Die Verfügbarkeit nimmt das lokale Datum der Location, die Personenzahl, den Ressourcentyp und eine optionale Dauer; eine Reservierung sendet den vom Gast gewählten Slot plus Kontaktdaten:

var availability = await client.GetAvailabilityAsync(
    "your-venue",
    DateOnly.FromDateTime(DateTime.Today),
    partySize: 4,
    BookableResourceType.RestaurantTable,
    cancellationToken: cancellationToken);

var slot = availability?.Slots.FirstOrDefault(s => s.Available);
if (slot is null)
{
    return; // an diesem Tag ist nichts frei
}

var reservation = await client.CreateReservationAsync("your-venue", new CreateReservationRequest
{
    ResourceType = BookableResourceType.RestaurantTable,
    ResourceId = slot.ResourceId,
    Date = availability.Date,
    Start = slot.Start,
    PartySize = 4,
    CustomerName = "Jana Berger",
    Email = "jana@example.com",
    Phone = "+49 30 1234567",
}, cancellationToken);

Console.WriteLine($"Gebucht: {reservation.Reference} um {reservation.Start} ({reservation.Status})");

Date ist yyyy-MM-dd und Start ist HH:mm, beide in der Ortszeit der Location – genau das, was die Verfügbarkeitsantwort geliefert hat. Optionale Felder decken Notizen, eine Spielanzahl bei Preis pro Spiel, buchbare Extras, eine Anzahlungs-Zustimmung und eine Dauer ab.

Fehler

  • Lesezugriffe (Get…Async) geben bei 404 null zurück und werfen bei jedem anderen Fehler BookDinePlayApiException (mit StatusCode).
  • Schreibzugriffe (CreateReservationAsync, CreatePaymentIntentAsync) werfen bei einer Ablehnung BookDinePlayApiException – ein inzwischen vergebener Slot, Validierungsfehler, ein Schlüsselproblem. Die Meldung trägt das Problem-detail der API.
  • Schlüssel-Ablehnungen sind 401/403 mit den Gründen unter Authentifizierung.
try
{
    var reservation = await client.CreateReservationAsync("your-venue", request, cancellationToken);
}
catch (BookDinePlayApiException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // der Slot wurde zwischen Verfügbarkeit und Buchung vergeben – neu prüfen und einen anderen anbieten
}

Weitere Endpunkte

Der Client kapselt außerdem Zahlungsabsichten (CreatePaymentIntentAsync), den QR-/Tischsitzungs-Ablauf für Bestellungen vor Ort (ResolveQrTokenAsync, GetTableSessionAsync, PlaceOrderAsync, CloseTableSessionAsync) und Gäste-Nachrichten (StartConversationAsync). Die Methodennamen folgen den API-Routen eins zu eins.

Resilienz und Tests

Der Client ist ein dünner HttpClient-Wrapper: Wiederholungen oder Timeouts ergänzen Sie mit Ihrer eigenen HttpClient-Konfiguration (etwa Microsoft.Extensions.Http.Resilience) auf der Registrierung, die AddBookDinePlayClient zurückgibt. In Tests injizieren Sie ein Fake-IBookDinePlayClient – die Schnittstelle liegt in BookDinePlay.Shared, Testprojekte brauchen das SDK-Paket also gar nicht.

Nächste Schritte