Entwicklerdokumentation

Änderungsprotokoll

Lesen, wer wann was geändert hat und über welchen Kanal: Protokoll von Location und Konto, Historie einer Buchung, CSV-Export und was nie erfasst wird.

Das Änderungsprotokoll (Audit-Log) beantwortet eine Frage: Wer hat wann was getan, über welchen Kanal, und was genau hat sich geändert – vor allem dann, wenn sich die Zeit einer Buchung verschoben hat oder ein Geldbetrag bewegt wurde. Jede Änderung, die eine Person, eine Integration, ein Webhook oder ein geplanter Job an den Buchungen, am Geld, an den Gutscheinen, am Team, an den Schlüsseln und an den Einstellungen einer Location vornimmt, schreibt einen Eintrag, und zwar in derselben Datenbanktransaktion wie die Änderung selbst: Wird die Änderung zurückgerollt, wird es auch ihr Eintrag.

Diese Routen sind nur lesend und gehören zur Betreiber-API unter /api/operator/**. Sie handeln als angemeldete Person (ein Bearer-Token, wie die Konsole), nicht über einen Location-Schlüssel; was zurückkommt, hängt daher von der Team-Rolle dieser Person ab. Dieselben Daten stehen Assistenten über die MCP-Werkzeuge und .NET-Code über das SDK zur Verfügung.

Was erfasst wird

Jeder Eintrag enthält:

  • Wer: die Art des Handelnden (Guest, Operator, PlatformAdmin, ApiClient, App oder System), eine Id und einen Anzeigenamen, wie er damals war, sowie die Team-Rolle eines Betreibers. Ein Aufruf, den ein BookDinePlay-Plattform-Admin ausführt, während er in Ihrem Konto handelt, trägt den Namen des Admins; das Protokoll zeigt dann „BookDinePlay Support“ statt Ihres eigenen Personals.
  • Über welchen Kanal: Console, App, Web, Widget, Api, Mcp, Webhook oder System, dazu das MCP-Werkzeug, das den Aufruf gemacht hat, und die Id des API-Schlüssels (nie sein Wert).
  • Wann: der Zeitpunkt in UTC, die lokale Uhrzeit der Location und der Geschäftstag: der Tag, an dem die Nacht begann, in der Zeitzone der Location – die Nacht auf Sonntag gehört also noch zum Samstag, auch um 01:30.
  • Was: eine action wie reservation.moved, deposit.refunded oder voucher.redeemed; das Objekt, dem es geschah (entityType, entityId, die lesbare entityReference wie BDP-7Q2M3K und die groupReference einer Gruppenbuchung); und das Vorher und Nachher jedes geänderten Feldes.
  • Geld: der Betrag, die Währung, wie er bewegt wurde (Card, Voucher, Cash, Waived, Store, Manual) und die Kennungen, die eine Erstattung braucht. Nie Kartendaten.
  • Zeit: die Ressource, der Beginn, das Ende und die Dauer, zwischen denen sich eine Buchung bewegt hat, und wann eine Spieluhr gestartet und gestoppt wurde.
  • Das Ergebnis: Succeeded, Failed (ein Geldvorgang, der nicht durchging, mit einem failureCode) oder Refused (eine Berechtigungsabweisung). Validierungsfehler werden nicht erfasst.

Auch das Lesen des Protokolls wird erfasst: Ansehen oder Exportieren schreibt einen Eintrag audit.viewed oder audit.exported, ebenso das Öffnen der Historie einer Buchung, wenn sie persönliche Werte gezeigt hat.

Was nie erfasst wird

Ein Credential gelangt nie ins Protokoll: kein API-Schlüssel, kein Gutscheincode, kein Ticketcode, kein Stornolink, kein QR-Token, keine signierte Nutzlast und keine Kartennummer. Ein Eintrag nennt stattdessen die Referenz (BDP-…, GV-…) und die Id. Der Schreibpfad prüft jeden Wert anhand seiner Form und verwirft einen, der wie ein Credential aussieht.

Wer was lesen darf

Leser Protokoll der Location und Export Protokoll des Kontos Historie einer Buchung oder eines Tabs Persönliche Werte
Owner jede Location ja ja ja, mit Client-Adresse und User-Agent
Manager seine Location nein ja ja, mit Client-Adresse und User-Agent
Staff nein (403) nein (403) nur eine Buchung oder ein Tab, die er öffnen kann die Werte der Buchung, nie die Adresse eines Handelnden
Plattform-Admin (nicht im Konto handelnd) jedes Konto über /api/admin/audit — — keine

Ein auf eine Location beschränkter Manager, der das Protokoll einer Nachbar-Location anfordert, bekommt venue-not-permitted; ein Slug, den das Konto nicht besitzt, ist venue-not-found. Eine abgewiesene Rolle ist team-role-required.

Persönliche Daten und Löschung

Die Werte persönlicher Felder (Name, Telefonnummer und Notizen eines Gastes, Client-Adresse und User-Agent dessen, der gehandelt hat) werden mit einem Schlüssel pro Person verschlüsselt gespeichert. Wird ein Gast oder ein Mitarbeiter gelöscht, wird sein Schlüssel vernichtet: Der Eintrag, seine Geld- und Zeitfelder und sein Platz im Protokoll bleiben, und die Werte sind für immer unlesbar.

Sie sehen das als Zustand, nie als Fehler. Jeder Eintrag hat einen personalDataState: None (nichts Persönliches gespeichert), Readable, Withheld (gespeichert, aber Ihre Rolle zeigt es nicht), Erased (die Person wurde gelöscht) oder Tampered (der gespeicherte Chiffretext lässt sich nicht mehr verifizieren; wird gemeldet, nie als Fehler geworfen, damit ein einzelner schlechter Eintrag keine Historie verdeckt). Ein geändertes Feld mit persönlichen Daten steht mit personal: true da; sein before und after sind nur für einen Leser gefüllt, der sie sehen darf, und solange der Schlüssel existiert.

Aufbewahrung und Tarife

Ein Eintrag mit einem Geldbetrag wird 10 Jahre aufbewahrt (handels- und steuerrechtliche Aufzeichnungspflicht), jeder andere 24 Monate. Jeder Tarif schreibt das Protokoll und kann es lesen, aber Historie, die älter als 90 Tage ist, und der CSV-Export brauchen den Tarif Pro oder höher. In Starter meldet eine Seite windowLimited: true mit dem frühesten Zeitpunkt, den sie liest, und der Export antwortet mit feature-not-in-plan und requiredPlan: "Pro".

Endpunkte

Das Protokoll der Location

GET /api/operator/venue/audit: eine Seite des Protokolls der gewählten Location, neueste zuerst (Manager und höher). Wählen Sie die Location in einem Konto mit mehreren Locations mit dem Header X-BookDinePlay-Venue. Alle Filter werden mit UND verknüpft:

Abfrage Bedeutung
from, to ISO-8601-Zeitpunkte, from einschließlich und to ausschließlich; ein reines Datum bedeutet Mitternacht UTC
businessDay yyyy-MM-dd, der Tag, an dem die Nacht begann
actorId, actorKind Die Id des Handelnden; Guest, Operator, PlatformAdmin, ApiClient, App oder System
channel Console, App, Web, Widget, Api, Mcp, Webhook oder System
action Ein Aktionsname wie reservation.moved
entityType, entityId Reservation, TableSession, Voucher, Event, Venue und so weiter; die Id des Objekts
reference Eine Buchungsreferenz; findet auch die Einträge der Gruppe der Buchung
moneyOnly, timeOnly true für nur die Einträge mit einem Betrag oder die die Zeit oder Ressource einer Buchung verschoben haben
cursor, pageSize Seitenweises Lesen, siehe unten; pageSize ist 1 bis 200 (Standard 50)
order desc (Standard, neueste zuerst) oder asc

curl

curl "https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "X-BookDinePlay-Venue: your-venue"

JavaScript

// Serverseitig oder in Ihrer eigenen Konsole: Das Bearer-Token ist das des angemeldeten Betreibers, nie ein Location-Schlüssel.
const response = await fetch('https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50', {
  headers: { Authorization: `Bearer ${operatorToken}`, 'X-BookDinePlay-Venue': 'your-venue' }
});
const page = await response.json();
for (const entry of page.items) {
  console.log(entry.occurredAt, entry.actor.name, entry.action, entry.entityReference);
}

C#

// `operatorClient` ist der BookDinePlayOperatorClient aus AddBookDinePlayOperatorClient und sendet das Bearer-Token des Betreibers.
var page = await operatorClient.GetAuditLogAsync(
    new AuditLogFilter(Action: "reservation.moved", PageSize: 50), "your-venue", cancellationToken);
foreach (var entry in page.Items)
{
    Console.WriteLine($"{entry.OccurredAt:u} {entry.Actor.Name} {entry.Action} {entry.EntityReference}");
}

PHP

<?php
$response = wp_remote_get( 'https://api.bookdineplay.com/api/operator/venue/audit?action=reservation.moved&pageSize=50', [
    'headers' => [ 'Authorization' => 'Bearer ' . $operator_token, 'X-BookDinePlay-Venue' => 'your-venue' ],
] );
$page = json_decode( wp_remote_retrieve_body( $response ), true );
foreach ( $page['items'] ?? [] as $entry ) {
    echo "{$entry['occurredAt']} {$entry['actor']['name']} {$entry['action']} {$entry['entityReference']}\n";
}

Antwort 200 OK: items (die Einträge), nextCursor (null auf der letzten Seite), personalDataIncluded (ob Ihre Rolle persönliche Werte sehen darf), windowLimited und earliestAvailable (der Tarif liest nur 90 Tage zurück).

Das Protokoll des Kontos

GET /api/operator/audit: dieselbe Seite für das ganze Konto, alle Locations, einschließlich der Einträge, die zu keiner Location gehören (Abrechnung, Team, das Konto selbst). Nur Owner; ein an eine Location gebundener Zugang bekommt tenant-operator-required. Der optionale Parameter venue schränkt auf einen Location-Slug ein; ein Slug, den das Konto nicht besitzt, ist 404. Es gelten dieselben Filter wie oben.

Der CSV-Export

GET /api/operator/venue/audit/export: das Protokoll der Location als CSV (Manager und höher, Tarif Pro oder höher; der Export wird selbst erfasst). Es gelten dieselben Filter; cursor und pageSize werden ignoriert, und der Export liest alle Seiten selbst, bis zu 50.000 Zeilen; ein größerer Zeitraum endet dort, und die Antwort trägt den Header X-BookDinePlay-Export-Truncated: true – schränken Sie dann den Filter ein und exportieren Sie erneut.

Die Datei ist UTF-8 mit Byte-Order-Mark (Excel liest Umlaute richtig), kommagetrennt, mit CRLF-Zeilenenden und einer Kopfzeile. Eine Spalte pro Tatsache: sequence, occurredAtUtc, businessDay, venueLocalTime, venue, action, outcome, failureCode, der Handelnde (actorKind, actorId, actorName, actorRole, impersonatedBy), channel, mcpTool, das Objekt (entityType, entityId, reference, groupReference), das Geld (amount, currency, moneyMethod, cardAmount, voucherAmount), die Zeit (oldResource, newResource, oldStartUtc, newStartUtc, oldEndUtc, newEndUtc, oldDurationMinutes, newDurationMinutes), changes (Feld: vorher -> nachher; …), reason, personalDataState, clientAddress, userAgent und source. Jede Textzelle ist gegen Tabellenformeln abgesichert: Ein Wert, der mit =, +, -, @, einem Tabulator oder einem Wagenrücklauf beginnt, bekommt ein vorangestelltes Apostroph, sodass der als =HYPERLINK(…) getippte Name eines Gastes Text bleibt.

Die Historien-Routen

Eine Historie ist das, was die Konsole neben einer Sache als Geschichte zeigt: standardmäßig älteste zuerst (order=desc dreht sie um), seitenweise wie das Protokoll.

Route Rolle Was sie zeigt
GET /api/operator/venue/reservations/{reference}/history Staff und höher Eine Buchung und, bei einer Gruppenbuchung, alle Mitglieder der Gruppe; memberReferences listet sie
GET /api/operator/venue/tabs/{id}/history Staff und höher Ein Tab (Tischsitzung)
GET /api/operator/venue/vouchers/{id}/history Manager und höher Ein Geschenkgutschein: seine Audit-Einträge zusammengeführt mit seinem eigenen Ledger, ohne Seiten
GET /api/operator/team/{id}/history Manager und höher Was ein Zugang in dieser Location getan hat, neueste zuerst; braucht wie die anderen Team-Routen die Team-Funktion des Tarifs

Die Antwort besteht aus entityType, entityId, reference, groupReference, items, nextCursor, personalDataIncluded, windowLimited und memberReferences. Eine unbekannte Buchung, ein unbekannter Tab, Gutschein oder Zugang dieser Location ist 404.

Die Historie eines Gutscheins deckt auch ab, was geschah, bevor es das Protokoll gab: Zeilen des Gutschein-Ledgers haben source: "voucher-ledger" und eine Aktion wie voucher-ledger.redeemed. Eine Ledger-Zeile, die das Protokoll ebenfalls erfasst hat, erscheint einmal, als der reichere audit-Eintrag. Der Gutscheincode ist nie Teil davon.

Filteroptionen

GET /api/operator/venue/audit/filters: die Werte, die ein Filter annimmt, damit eine Konsole ihre Auswahllisten vom Server bezieht: actions, entityTypes, actorKinds, channels, outcomes, maxPageSize, canExport und historyDays (null, wenn der Tarif die ganze Aufbewahrungszeit liest).

Seitenweises Lesen

Die Seiten sind ein Keyset auf der Sequenznummer des Eintrags, dem Zähler pro Konto, den jeder Eintrag innerhalb seiner Transaktion bekommt. Übergeben Sie den nextCursor einer Seite als cursor, um die nächste zu lesen; der Cursor ist undurchsichtig. Da ein neuer Eintrag immer eine höhere Sequenznummer bekommt als jeder vorhandene, verschiebt sich eine Seite nie, während neue Einträge geschrieben werden: Kein Eintrag wird übersprungen oder doppelt geliefert, was ein Offset nicht zusichern kann. Ein Cursor, den diese Version nicht ausgegeben hat, ist 400 invalid-cursor. Ein fehlerhaftes Datum, eine fehlerhafte Art, ein fehlerhafter Kanal oder eine fehlerhafte Seitengröße ist ein 400-Validierungsproblem, das das Feld nennt.

Felder eines Eintrags

Feld Bedeutung
id, sequence Eine eindeutige Id; die Reihenfolge pro Konto, in der Einträge festgeschrieben wurden
occurredAt, businessDay, venueLocalTime Wann, in UTC; der Tag, an dem die Nacht begann; die lokale Uhrzeit der Location
action, outcome, failureCode Was geschah und wie es endete
entityType, entityId, entityReference, groupReference Dem es geschah
actor kind, id, name, role sowie impersonatedById und impersonatedByName für einen im Konto handelnden Plattform-Admin
origin channel, clientId, mcpTool, mcpConfirmed, apiKeyId, apiKeyType, clientClass und für einen Owner oder Manager clientAddress und userAgent
money, time Der Betrag und der verschobene Slot, wie oben beschrieben
changes field, before, after und personal je geändertem Feld
reason Der Grund, den der Handelnde genannt hat; der Grund einer Person kann einen Gast nennen und folgt daher den Regeln der persönlichen Werte
personalDataState, retentionClass, source Siehe oben; Standard oder Money; audit oder voucher-ledger

Plattform-Admins

GET /api/admin/audit?tenantId=… liest das Protokoll eines beliebigen Kontos für den Support, mit denselben Filtern, demselben seitenweisen Lesen und einem optionalen venue. Es zeigt keine persönlichen Werte, keine Client-Adressen und keine Tarifgrenzen, und das Lesen wird im eigenen Protokoll des Kontos als audit.viewed des Admins erfasst. Ein Admin, der im Konto handelt (Impersonation), ist dort Owner, und es gelten die Betreiber-Routen oben.

Fehler

Status Typ Wann
400 invalid-cursor Der cursor wurde von dieser API nicht ausgegeben
400 Validierungsproblem Ein Filterwert ist fehlerhaft oder außerhalb des Bereichs
403 team-role-required Ihre Team-Rolle erreicht die Route nicht
403 venue-not-permitted Ein an eine Location gebundener Manager hat eine andere angefordert
403 feature-not-in-plan Der Export oder die Team-Historie braucht einen höheren Tarif
404 — Eine unbekannte Buchung, ein unbekannter Tab, Gutschein oder Zugang dieser Location; ein Location-Slug, den das Konto nicht besitzt, ist venue-not-found

Nächste Schritte