Entwicklerdokumentation

Highlights

Die Highlight-Karten einer Location für ihre Website lesen – Bild, Titel, Kurztext und optional ein Link auf Gericht, Event, Gutscheinangebot oder Seite.

Die Highlight-Karten, die eine Location für ihre Website pflegt: ein Bild mit Titel, einem kurzen Text und optional einem Link auf ein Gericht der Speisekarte, ein Event, ein Gutscheinangebot oder eine beliebige andere Seite. Sie sind ein eigener Inhaltstyp, getrennt von den Specials: ein Highlight hat keinen Preis, keine Wochentage und kein Zeitfenster, nur einen ersten und einen letzten Tag, an dem es gezeigt wird. Es erscheinen nur veröffentlichte Karten innerhalb dieses Zeitraums. Der Lesezugriff folgt denselben Schlüsselregeln wie der Rest von /api/venues/** (Schlüssel und Header), steht jedem Tarif offen und antwortet mit 404 und einem Problem-Body, wenn keine Location diesen Slug hat.

Endpunkte

GET /api/venues/{venueSlug}/highlights

Hat keine Abfrageparameter: Die Antwort enthält immer die Karten, die heute in der Zeitzone der Location sichtbar sind.

Antwort 200 OK

Feld Typ Bedeutung
slug string Die Location
timezone string IANA-ID der Zeitzone der Location; der Sichtbarkeitszeitraum wird in ihr beurteilt
highlights[] object[] Die sichtbaren Karten in Anzeigereihenfolge; die Liste kann leer sein

Jeder Eintrag in highlights[]:

Feld Typ Bedeutung
id string Die ID der Karte
title string Die Überschrift
text string Ein optionaler Kurztext (nullable)
imageUrl string Das Bild der Karte
linkKind string Worauf die Karte verweist: None, MenuItem, Event, VoucherProduct oder External
linkTarget string Die ID der Speisekartenposition, der Slug des Events, die ID des Gutscheinangebots oder die externe URL, je nach linkKind (nullable)
linkUrl string Die absolute https-URL eines External-Links; null bei jeder anderen Art (nullable)

Die Karten sind nach der Sortierung des Betreibers geordnet, dann nach Titel.

Eine Karte verweist auf eines von vier Zielen oder auf nichts:

  • External – eine vollständige https-URL, direkt in linkUrl verwendbar.
  • Event, MenuItem und VoucherProduct – ein Verweis über linkTarget. Die API weiß nicht, wo Events, Speisekartenpositionen oder der Gutscheinshop auf Ihrer Website liegen; die Adresse bauen Sie selbst, zum Beispiel /events/ plus den Slug. renderHighlights nimmt dafür je eine URL-Vorlage entgegen.

Ein Verweis wird beim Speichern der Karte und bei jedem Lesen geprüft. Ist das Event nicht mehr veröffentlicht, die Position gelöscht oder das Gutscheinangebot beendet, kommt die Karte trotzdem zurück, aber als linkKind: "None" ohne linkTarget, sodass nie ein Link ins Leere führt.

Sichtbarkeit und Zeitzone

Der Betreiber legt je Karte einen optionalen ersten und letzten Tag fest, als Kalendertage in der Zeitzone der Location, beide einschließlich. Die Karte erscheint an jedem Tag in diesem Zeitraum. Ohne ersten Tag wird sie ab der Veröffentlichung gezeigt, ohne letzten Tag, bis sie zurückgezogen oder gelöscht wird. „Heute“ ist das Heute der Location, nie das des Aufrufers: Eine Anfrage um 23:30 UTC im Winter ist für eine Location in Berlin schon morgen, und eine Karte, deren letzter Tag gestern war, ist verschwunden.

Eine Antwort für demo-sportsbar könnte so aussehen:

{
  "slug": "demo-sportsbar",
  "timezone": "Europe/Berlin",
  "highlights": [
    {
      "id": "7c1f0a2be9d44c3a8b5e6d7f8a9b0c11",
      "title": "Derby-Abend",
      "text": "Jedes Tor auf der Großleinwand, dazu ein Krug Bier für den Tisch.",
      "imageUrl": "https://cdn.bookdineplay.com/media/demo-sportsbar/01JD3Z8Q6V5T2N4M7K9R1S0XYA.webp",
      "linkKind": "Event",
      "linkTarget": "derby-night",
      "linkUrl": null
    },
    {
      "id": "7c1f0a2be9d44c3a8b5e6d7f8a9b0c12",
      "title": "Unsere neue Herbstkarte",
      "text": null,
      "imageUrl": "https://cdn.bookdineplay.com/media/demo-sportsbar/01JD3Z8Q6V5T2N4M7K9R1S0XYB.webp",
      "linkKind": "External",
      "linkTarget": "https://example.com/herbstkarte.pdf",
      "linkUrl": "https://example.com/herbstkarte.pdf"
    }
  ]
}

Fehler

  • 401 – kein Schlüssel oder ein unbekannter.
  • 403 – der Schlüssel gehört zu einer anderen Location, ein veröffentlichbarer Schlüssel kam von einer Origin, die nicht auf seiner Allowlist steht, oder ein veröffentlichbarer Schlüssel wurde ohne Origin-Header gesendet. Siehe Was die API ablehnt.
  • 404 – keine Location mit diesem Slug.

curl

curl "https://api.bookdineplay.com/api/venues/your-venue/highlights" \
  -H "X-BookDinePlay-Key: bdp_pk_your_publishable_key" \
  -H "Origin: https://www.your-venue.example"

JavaScript

const client = BookDinePlay.createClient({
  apiBaseUrl: 'https://api.bookdineplay.com', venueSlug: 'your-venue', publishableKey: 'bdp_pk_your_publishable_key'
});
const response = await client.highlights(); // null bei unbekannter Location
for (const card of response?.highlights ?? []) {
  console.log(card.title, card.linkKind, card.linkTarget);
}

C#

// `client` ist der IBookDinePlayClient aus AddBookDinePlayClient, registriert mit dem GEHEIMEN Schlüssel der Location
// aus der Konfiguration (builder.Configuration["BookDinePlay:ApiKey"]). Ein Server sendet keinen Origin-Header.
var response = await client.GetHighlightsAsync("your-venue", cancellationToken);
foreach (var card in response?.Highlights ?? [])
{
    Console.WriteLine($"{card.Title} ({card.LinkKind}: {card.LinkTarget})");
}

PHP

<?php
// Server-side: the secret key is a constant in wp-config.php, never in a template or in JavaScript.
$response = wp_remote_get( 'https://api.bookdineplay.com/api/venues/your-venue/highlights', [ 'headers' => [ 'X-BookDinePlay-Key' => BOOKDINEPLAY_SECRET_KEY ] ] );
$response = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $response['highlights'] ?? [] as $card ) {
    echo "{$card['title']} ({$card['linkKind']}: {$card['linkTarget']})
";
}

Das JavaScript-Beispiel nutzt den veröffentlichbaren Schlüssel. Das C#-Beispiel läuft auf einem Server und nutzt deshalb einen geheimen Schlüssel (bdp_sk_…) aus der Konfiguration und sendet keinen Origin-Header; liefern Sie einen geheimen Schlüssel nie an einen Browser aus. client.highlights und GetHighlightsAsync antworten bei einer unbekannten Location mit null, wo der reine HTTP-Aufruf ein 404 ist. renderHighlights zeichnet dieselben Daten ganz ohne eigenen Code.

Betreiber: Highlights speichern

Betreiber pflegen Highlights über die Betreiber-API (Bearer-Token des Betreibers der Location), nicht über die öffentliche Oberfläche /api/venues/**: GET, POST, PUT und DELETE auf /api/operator/venue/highlights. Ein PUT ersetzt alles, senden Sie daher immer status und linkKind: Ein fehlender status wird zu Draft und nimmt die Karte zurück, ein fehlendes linkKind zu None, und ein fehlendes visibleFrom oder visibleTo entfernt diese Grenze. Eine Location hält höchstens 30 Highlights; das 31. wird mit 409 abgelehnt. Das Bild laden Sie zuerst mit einem POST auf /api/operator/venue/menus/media hoch, das die Adresse zurückgibt, die Sie als imageUrl senden. Highlights stehen jedem Tarif offen und werden mit DELETE gelöscht, nicht archiviert.

Nächste Schritte

  • Venue – die anderen sieben Lesezugriffe für diese Location.
  • Specials – die täglichen Gerichte und Angebote, ein eigener Inhaltstyp.
  • JavaScript-Highlights – das Widget, das diese Karten rendert.