Anmelden um den Slug und den veröffentlichbaren Schlüssel Ihrer Location in jedem Beispiel zu sehen.
Ihr Konto hat noch keine Location, die Beispiele behalten daher ihre Platzhalter. Abmelden
Angemeldet als · . Legen Sie in der Konsole einen veröffentlichbaren Schlüssel an und laden Sie die Seite neu, um ihn hier zu sehen. Abmelden
Angemeldet als · . Die Beispiele zeigen den veröffentlichbaren Schlüssel Ihrer Location. Abmelden
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,AppoderSystem), 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,WebhookoderSystem, 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
actionwiereservation.moved,deposit.refundedodervoucher.redeemed; das Objekt, dem es geschah (entityType,entityId, die lesbareentityReferencewieBDP-7Q2M3Kund diegroupReferenceeiner 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 einemfailureCode) oderRefused(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
- Fehler für jeden Problemtyp.
- Was die MCP-Werkzeuge tun für
audit_list,booking_historyundvoucher_history. - .NET-SDK für
BookDinePlayOperatorClient.