API-Referenz

API-Schlüssel

Senden Sie den Schlüssel im Header X-API-Key. Im Header Authorization wird er nicht angenommen. Schlüssel beginnen mit plz_live_ und werden im Admin unter Einstellungen, API-Schlüssel erstellt. Ein Schlüssel gehört zu genau einem Restaurant, trägt die Berechtigungen, die Sie ihm geben, und kann ein Ablaufdatum haben. platzeo zeigt ihn nur einmal an, direkt nach dem Erstellen. Ein widerrufener oder abgelaufener Schlüssel wird mit 401 abgelehnt.

curl https://platzeo.de/api/v1/restaurants \
  -H "X-API-Key: plz_live_..."

OAuth-Zugriffstoken

Ein Token aus dem OAuth-Ablauf senden Sie als Authorization: Bearer plz_at_.... Es gilt für das Restaurant, für das es freigegeben wurde.

Anfrage

POST /ihr-endpunkt
Content-Type: application/json
User-Agent: platzeo-Webhooks/1.0
X-platzeo-Event: reservation.created
X-platzeo-Delivery: 0b6f6a52-6c1e-4c0e-9a51-3d8f3f1f2a77
X-platzeo-Attempt: 1
X-platzeo-Timestamp: 1791475200
X-platzeo-Signature: t=1791475200,v1=5d41...
X-platzeo-Payload-Version: 2

{
  "id": "0b6f6a52-6c1e-4c0e-9a51-3d8f3f1f2a77",
  "event": "reservation.created",
  "version": 2,
  "timestamp": 1791475200,
  "restaurantId": "9b206577-1a4b-4497-9378-48b66f49c18c",
  "data": {
    "reservation": {
      "id": "3a4b5c6d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
      "status": "confirmed",
      "date": "2026-04-20",
      "time": "19:30",
      "partySize": 4,
      "durationMinutes": 120,
      "tables": [
        {
          "id": "5f0c2f6e-9d1b-4c1e-8a57-2b1f0c3d4e5f",
          "name": "Tisch 4"
        }
      ],
      "source": "online",
      "occasion": "Geburtstag",
      "notes": "Bitte ein Tisch am Fenster.",
      "customFields": [
        {
          "label": "Kinderstuhl",
          "value": "Ja"
        }
      ],
      "createdAt": "2026-04-15T14:30:00.000Z",
      "updatedAt": "2026-04-15T14:30:00.000Z"
    },
    "guest": {
      "id": "0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a",
      "firstName": "Anna",
      "lastName": "Beispiel",
      "email": "anna.beispiel@example.com",
      "phone": "+49 30 1234567"
    }
  }
}

version ist die Version der Inhalte, zurzeit 2. Sie steht auch im Header X-platzeo-Payload-Version. Neue Felder können jederzeit dazukommen. Fällt ein Feld weg oder ändert es seine Bedeutung, steigt die Version. Mit der Einstellung „Raw (nur Daten)“ besteht der Body nur aus dem Inhalt von data. Statt POST können Sie PUT oder PATCH wählen.

Inhalt der Ereignisse

Gesendet werden genau die folgenden Felder. Reservierungs-Ereignisse tragen data.reservation und data.guest, reservation.cancelled dazu cancelledBy: guest (über den Link in der E-Mail), restaurant oder expired (die E-Mail-Adresse wurde nicht rechtzeitig bestätigt). Gast-Ereignisse tragen data.guest. Treue-Ereignisse tragen data.card, loyalty.stamp.added dazu delta (gutgeschriebene Stempel oder Punkte), loyalty.reward.redeemed delta (abgezogen, negativ) und reward mit id und title; id ist null bei einem Stempelprogramm, dessen Belohnung keine eigene Kennung hat.

{
  "data": {
    "reservation": {
      "id": "3a4b5c6d-7e8f-4a1b-9c2d-3e4f5a6b7c8d",
      "status": "cancelled",
      "date": "2026-04-20",
      "time": "19:30",
      "partySize": 4,
      "durationMinutes": 120,
      "tables": [
        {
          "id": "5f0c2f6e-9d1b-4c1e-8a57-2b1f0c3d4e5f",
          "name": "Tisch 4"
        }
      ],
      "source": "online",
      "occasion": "Geburtstag",
      "notes": "Bitte ein Tisch am Fenster.",
      "customFields": [
        {
          "label": "Kinderstuhl",
          "value": "Ja"
        }
      ],
      "createdAt": "2026-04-15T14:30:00.000Z",
      "updatedAt": "2026-04-15T14:30:00.000Z"
    },
    "guest": {
      "id": "0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a",
      "firstName": "Anna",
      "lastName": "Beispiel",
      "email": "anna.beispiel@example.com",
      "phone": "+49 30 1234567"
    },
    "cancelledBy": "guest"
  }
}

{
  "data": {
    "guest": {
      "id": "0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a",
      "firstName": "Anna",
      "lastName": "Beispiel",
      "email": "anna.beispiel@example.com",
      "phone": "+49 30 1234567",
      "marketingConsent": false,
      "createdAt": "2026-03-02T09:15:00.000Z"
    }
  }
}

{
  "data": {
    "card": {
      "id": "7c6b5a49-3827-4615-a0b9-c8d7e6f5a4b3",
      "cardNumber": "PLZ-4821-7730",
      "guestId": "0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a",
      "programId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
      "status": "active",
      "stamps": 7,
      "points": 0,
      "rewardsRedeemed": 1,
      "issuedAt": "2026-03-02T09:15:00.000Z",
      "expiresAt": null
    },
    "delta": 1
  }
}

{
  "data": {
    "card": {
      "id": "7c6b5a49-3827-4615-a0b9-c8d7e6f5a4b3",
      "cardNumber": "PLZ-4821-7730",
      "guestId": "0d9c8b7a-6f5e-4d3c-9b2a-1f0e9d8c7b6a",
      "programId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
      "status": "active",
      "stamps": 0,
      "points": 0,
      "rewardsRedeemed": 2,
      "issuedAt": "2026-03-02T09:15:00.000Z",
      "expiresAt": null
    },
    "delta": -10,
    "reward": {
      "id": "6b5a4938-2716-4504-b9a8-d7c6e5f4a3b2",
      "title": "Gratis Kaffee"
    }
  }
}

Welche Ereignisse eine Änderung sendet

Ändert eine Reservierung ihren Status, kommt genau ein Ereignis, das des neuen Status. reservation.updated kommt dann nicht zusätzlich. Beginnt eine Reservierung in einem Status mit eigenem Ereignis, folgt es direkt auf reservation.created: bei einer sofort bestätigten Online-Buchung und einer vom Team eingetragenen Reservierung reservation.confirmed, bei Laufkundschaft reservation.seated. Wer alle bestätigten Reservierungen braucht, abonniert also nur reservation.confirmed.

Gehören mehrere Ereignisse zu einer Aktion, sendet platzeo sie nacheinander in fester Reihenfolge: erst der Gast, dann reservation.created, dann der Status. Eine Wiederholung nach einem Fehlschlag kann später ankommen als das nächste Ereignis.

Test

„Testereignis senden“ im Admin schickt ein Beispiel des ersten Ereignisses, das der Webhook abonniert hat, mit erfundenen Daten in genau der Form oben. Der Body trägt zusätzlich "test": true (im Format „raw“ steht es neben den Daten), die Anfrage den Header X-platzeo-Test: true. Prüfen Sie eines von beiden, bevor Sie die Daten verarbeiten. Ein Test wird nicht wiederholt und zählt im Admin nicht zu den zugestellten oder fehlgeschlagenen Ereignissen.

Signatur

Jeder Webhook hat ein Secret, das mit whsec_ beginnt. Der Wert v1 im Header X-platzeo-Signature ist der HMAC-SHA256 über <timestamp>.<body> mit diesem Secret, hexadezimal geschrieben. Rechnen Sie mit dem Body genau so, wie er ankommt.

Zustellung

Als zugestellt gilt eine Antwort mit Status 2xx innerhalb des Zeitlimits (10 Sekunden, einstellbar von 1 bis 30). Weiterleitungen folgt platzeo nicht. Schlägt ein Versuch fehl, wiederholt platzeo die Zustellung nach 1 Minute, 5 Minuten, 30 Minuten und 2 Stunden, danach alle 6 Stunden. Voreingestellt sind drei Wiederholungen, einstellbar sind 0 bis 10. Nach der letzten stellt platzeo das Ereignis nicht erneut zu. Das Protokoll im Admin zeigt jeden Versuch.

Alle Versuche einer Zustellung haben dieselbe Zustell-ID (id im Body, Header X-platzeo-Delivery) und denselben Body. Kommt eine ID ein zweites Mal an, ist es eine Wiederholung: Verarbeiten Sie jede ID nur einmal. X-platzeo-Attempt zählt die Versuche. X-platzeo-Timestamp und die Signatur gehören zum einzelnen Versuch, timestamp im Body ist der Zeitpunkt des Ereignisses.

Snippet

<div data-platzeo-booking="ihr-slug"></div>
<script async src="https://platzeo.de/widget.js"></script>

Der Loader setzt in den Container ein iFrame von https://ihr-slug.platzeo.de/embed. Bis es geladen ist, zeigt er ein kurzes „Lädt…“.

Binden Sie das Skript von platzeo.de ein und nicht als Kopie auf Ihrem Server oder in einem Bundle: Der Loader sucht die Buchungsseite neben der Adresse, von der er geladen wurde, und eine Kopie erhält keine Korrekturen. Aus demselben Grund gehört kein integrity-Attribut an das Skript.

Das Widget ist so breit wie sein Container. Geben Sie ihm mindestens 340 px, mit data-seamless mindestens 300 px. In einer schmaleren Spalte passt das Formular weiter ohne Scrollen zur Seite, die Tage im Kalender sind dann aber schmaler als 40 px.

Optionen

<div
  data-platzeo-booking="ihr-slug"
  data-theme="auto"
  data-primary="#14422b"
  data-lang="de"
  data-compact="1"
  data-id="reservierung"
></div>

Die Werte dürfen groß oder klein geschrieben sein.

JavaScript-API

Für Single-Page-Apps, Tabs und Overlays: Platzeo.mount(element, "ihr-slug", { theme, primary, lang, compact, seamless, sections, id, minHeight, scrollOffset }) bindet das Widget ein oder ersetzt das dort eingebundene und gibt die Instanz-ID zurück. Platzeo.unmount(element) entfernt es wieder, Platzeo.refresh() bindet nachträglich eingefügte Container ein.

Das Skript lädt asynchron, window.Platzeo gibt es also erst danach. Über window.platzeoReady läuft Ihr Code, sobald der Loader bereit ist, egal ob davor oder danach:

<div id="reservierung"></div>
<script>
  (window.platzeoReady = window.platzeoReady || []).push(function (Platzeo) {
    Platzeo.mount("#reservierung", "ihr-slug", { lang: "de", sections: "events" });
  });
</script>
<script async src="https://platzeo.de/widget.js"></script>

Eigenes iFrame

Sie können das iFrame auch selbst setzen. Die URL-Parameter theme, primary (sechsstelliger Hex-Wert ohne #), lang, compact=1, seamless=1, sections und id entsprechen den Data-Attributen. Mit data-platzeo-embed übernimmt widget.js die automatische Höhe.

Ein iFrame kann mit einem Termin öffnen, etwa von einem Link „Heute 19:00“ auf Ihrer Seite: date (JJJJ-MM-TT), time (HH:MM) und partySize (Personen). Ist der Termin für diese Personenzahl frei, ist er ausgewählt, und der Gast tippt nur noch auf „Weiter“. Ist nur der Tag frei, ist der Tag ausgewählt; sonst öffnet der Kalender im Monat des Tages und nichts ist ausgewählt.

<iframe
  data-platzeo-embed
  src="https://ihr-slug.platzeo.de/embed?id=reservierung&theme=auto"
  title="Reservierung"
  style="width:100%;border:0;min-height:560px"
></iframe>
<script async src="https://platzeo.de/widget.js"></script>

Ein selbst gesetztes iFrame mit seamless=1 sieht den Hintergrund Ihrer Seite nicht. Steht widget.js auf der Seite, teilt der Loader ihm mit, ob die Seite dahinter hell oder dunkel ist, und das iFrame nimmt das passende Theme. Ohne widget.js nimmt es das helle Theme, theme=auto eingeschlossen; auf einer dunklen Seite geben Sie dann theme=dark an.

Ist das Theme Ihrer Buchungsseite dunkel und die Adresse nennt keines, behält das iFrame ohne widget.js seinen dunklen Hintergrund, statt helle Schrift auf eine Seite zu setzen, die es nicht kennt. Mit theme=dark oder theme=light ist es immer durchsichtig.

Die Erkennung liest Hintergrundfarben und Farbverläufe. Ein Hintergrundbild ohne Hintergrundfarbe auf demselben Element und ein Verlauf von hell nach dunkel gelten als unbekannt: Das Formular behält dann seinen eigenen Hintergrund, bis Sie das Theme angeben. Deklariert Ihre Seite color-scheme: dark, braucht ein iFrame ohne widget.js zusätzlich style="color-scheme:light", sonst legt der Browser eine weiße Fläche darunter.

Events

widget.js löst auf document zwei Events aus, zum Beispiel für Analytics oder um ein Overlay zu schließen:

document.addEventListener("platzeo:booking-confirmed", (e) => {
  // e.detail = { id, slug, step: "done", status }
  // status: "confirmed" | "pending" | "unverified"
  if (e.detail.status === "confirmed") {
    gtag("event", "reservation", { restaurant: e.detail.slug });
  }
});
document.addEventListener("platzeo:step-changed", (e) => {
  // e.detail.step: "datetime" | "guest" | "confirm" | "done"
});

platzeo:step-changed kommt beim Laden des Formulars mit datetime und danach bei jedem Schritt. Nimmt das Restaurant gerade keine Online-Buchungen an, gibt es kein Formular und kein Event.

platzeo:booking-confirmed kommt, sobald der Gast das Formular abgeschickt hat, auch wenn die Reservierung noch nicht fest ist. detail.status sagt, was der Gast jetzt hat: confirmed ist eine bestätigte Reservierung, pending eine Anfrage, die das Restaurant noch annehmen muss, und bei unverified muss der Gast erst seine E-Mail-Adresse bestätigen. Soll Ihre Statistik nur feste Buchungen zählen, werten Sie confirmed aus.

Content-Security-Policy

Setzt Ihre Website eine Content-Security-Policy, braucht sie zwei Einträge: das Skript von platzeo.de und das iFrame Ihrer Buchungsseite.

Content-Security-Policy: script-src https://platzeo.de; frame-src https://ihr-slug.platzeo.de

Für mehrere Restaurants auf einer Website geht auch frame-src https://*.platzeo.de. Fehlt der Eintrag für das iFrame, zeigt der Loader an seiner Stelle einen Link zu Ihrer Buchungsseite. Fehlt der Eintrag für das Skript, bleibt der Container leer.