Reservierungen lesen, anlegen und ändern

Das Reservierungsbuch: Liste mit zwanzig Filtern, Einzelabruf mit ETag, Anlegen durch dieselbe Torwache wie das Widget und Teiländerung ohne Datenverlust.

Für Entwickler

Voraussetzungen

Recht `reservations:read` zum Lesen, `reservations:write` zum Anlegen und Ändern
Handlung `action:guests.personal` für `internalNotes`
Plan-Merkmal „Reservierungen"

Vier Operationen auf einer Ressource: Liste, Einzelabruf, Anlegen, Teiländerung. Es gibt bewusst KEIN `PUT` und KEIN `DELETE`. Ein `PUT` würde jedes ausgelassene Feld leeren — die häufigste Folge wäre eine Reservierung ohne Telefonnummer, gemerkt am Abend des Besuchs. Ein `DELETE` gäbe es nicht zurück: an einer Reservierung hängen Auslastungsstatistik, Berichte, Mailprotokoll, Zahlungen und die Risikozähler des Gastes. Storniert wird über den Statuswechsel.

DIE ZEITFELDER, UND WARUM ES DREI SIND. `date` ist der KALENDERTAG des Betriebs (`"2026-09-20"`) — eine Buchung um 02:00 gehört zum Vortag, weil der Betriebstag so gezählt wird. `time` und `endTime` sind naive Ortszeiten (`"19:30"`); `endTime` darf `"25:00"` lauten, wenn der Tisch nach Mitternacht frei wird. `startsAt` und `endsAt` sind daraus abgeleitete echte Zeitpunkte MIT Zonenversatz (`"2026-09-20T19:30:00+02:00"`) und nur lesbar. `timezone` steht an jeder Zeile, damit sie allein reisen kann.

DER STATUS SAGT, WORAUF DER GAST SICH VERLASSEN DARF. `PENDING` — die Anfrage liegt vor, der Betrieb hat noch nicht zugesagt. `CONFIRMED` — zugesagt, der Tisch steht. `OPTION` — unverbindliche Vormerkung, die der Betrieb wieder auflösen kann. `CANCELED` — storniert, gleich von welcher Seite. `NOSHOW` — der Gast ist nicht erschienen; dieser Wert zieht eine hinterlegte Gebühr ein und erhöht das Risikoprofil des Gastes. `COMPLETED` — der Besuch ist abgeschlossen. Beim ANLEGEN sind nur `PENDING`, `CONFIRMED` und `OPTION` erlaubt; die anderen drei sind Endpunkte eines Lebenslaufs und laufen ausschliesslich über die Statusroute.

`source` SAGT, WOHER DIE BUCHUNG KAM: `API` (dieser Weg, Vorgabe), `PHONE` (Telefonanlage), `MANUAL` (jemand hat sie von Hand eingetragen), `WALKIN` (Laufkundschaft am Tresen), `WIDGET` (die Buchungsstrecke des Gastes), `WAITLIST` (aus der Warteliste nachgerückt). Die Spalte ist frei, angenommen wird trotzdem nur diese Liste — damit die Auswertungen im Dashboard nicht mit Fantasiewerten zulaufen.

BEIM ANLEGEN LÄUFT DIESELBE TORWACHE WIE IM WIDGET, einschliesslich `requireOnlineBookable`. Geprüft werden Sperren, Öffnungszeiten, Vorlauf, Personenzahl, Gruppenschwelle und Kapazität. Es gibt KEIN `force`: die Doppelbuchung, die der Wirt im Dashboard bewusst bestätigt, hat in einer maschinellen Schnittstelle keine Entsprechung — ein Fremdsystem kann nicht beurteilen, ob eine Ausnahme gerechtfertigt ist. Wo eine nötig ist, führt der Weg über das Dashboard.

TISCHE MÜSSEN SIE NICHT NENNEN. Lassen Sie `tableIds` weg, sucht der Tischplan selbst — dieselbe Rechnung wie im Widget, samt Zusammenlegen mehrerer Tische. Nennen Sie welche, werden genau diese geprüft und belegt. `tableIds: []` in einem `PATCH` heisst ausdrücklich „Zuordnung löschen"; das Feld ganz wegzulassen heisst „unverändert".

ÜBER DIE API WIRD KEINE GÄSTEPOST AUSGELÖST. Weder beim Anlegen noch beim Ändern noch beim Stornieren geht eine Mail an den Gast. Die Felder `notify` und `sendEmail` werden mit 400 `read_only_field` abgewiesen. Eine gestohlene Erweiterung soll nicht allen Gästen im Namen des Wirts schreiben können.

`internalNotes` IST EIN PERSÖNLICHES MERKMAL. Dort steht der Vermerk zu einem gesperrten Gast und stehen Sätze wie „zahlt schlecht". Das Feld wird nur ausgeliefert, wenn der Schlüssel die Handlung `action:guests.personal` trägt — sonst steht dort in JEDER Antwort `null`. Auch die Volltextsuche `q` durchsucht es nur mit dieser Handlung, sonst wäre die Trefferliste ein Leseweg in genau das Feld, das die Ausgabe verschweigt.

FINANZFELDER GEHEN NICHT HINAUS. Anzahlung, No-Show-Gebühr, Zahlungsstatus und die Kennung des Zahlungsvorgangs sind in keiner Antwort enthalten, und sie lassen sich nicht setzen. `reservations:read` ist dafür zu grob — jede Rolle mit Leserecht sähe sonst Anzahlungen mit. Ebenfalls nie enthalten: `changeHash`, der Geheimniswert des Storno-Links aus den Gästemails. Wer ihn hätte, könnte jede Reservierung des Hauses ohne Anmeldung stornieren.

Die Routen

GET/api/v1/reservations

Das Reservierungsbuch lesen — gefiltert nach Tag, Zeitraum, Status, Bereich, Uhrzeit, Personenzahl oder Änderungszeitpunkt.

Rechte

reservations:read

Plan-Merkmal reservations — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Abfrageparameter

Name	Typ	Bedeutung
`date`	YYYY-MM-DD	Genau ein Kalendertag des Betriebs. Schliesst `dateFrom`/`dateTo` aus.
`dateFrom`	YYYY-MM-DD	Erster Tag eines Zeitraums, einschliesslich.
`dateTo`	YYYY-MM-DD	Letzter Tag eines Zeitraums, einschliesslich. Muss `dateFrom` sein oder danach liegen.
`status`	Kommaliste aus PENDING, CONFIRMED, OPTION, CANCELED, NOSHOW, COMPLETED	Nur Reservierungen in diesen Zuständen. Ohne Angabe: alle, auch stornierte — für einen Tagesplan also fast immer `status=CONFIRMED,PENDING,OPTION` setzen.
`source`	Kommaliste aus API, PHONE, MANUAL, WALKIN, WIDGET, WAITLIST	Nur Buchungen dieser Herkunft. `WIDGET` ist das Buchungsfenster auf der Website des Betriebs, `API` alles über diese Schnittstelle, `PHONE` und `MANUAL` das vom Personal Eingetragene (telefonisch bzw. am Tresen), `WALKIN` die Laufkundschaft ohne Voranmeldung, `WAITLIST` eine aus der Warteliste nachgerückte Buchung.
`areaId`	UUID	Bereich SAMT seiner Unterbereiche. Eine Kennung, die nicht zu diesem Betrieb gehört, ist 400 — nicht eine leere Liste.
`timeFrom`	HH:mm	Frühester Beginn, einschliesslich. Verglichen wird die naive Ortszeit.
`timeTo`	HH:mm	Spätester Beginn, einschliesslich.
`partyMin`	integer 1–9999	Mindestens so viele Personen.
`partyMax`	integer 1–9999	Höchstens so viele Personen.
`updatedSince`	ISO-8601 mit Zone	Nur Zeilen, die seit diesem Zeitpunkt geändert wurden — der Filter für den inkrementellen Abgleich.
`ids`	Kommaliste von UUIDs, höchstens 100	Genau diese Reservierungen. Unbekannte Kennungen fehlen still in der Antwort; die Liste ist kein Nachschlagewerk.
`q`	string, 2–200 Zeichen	Volltext über GASTNAME und Anmerkungen — nie über E-Mail oder Telefon. Verlangt ein Datumsfenster von höchstens 400 Tagen (`date` oder `dateFrom`+`dateTo`), weil die Suche durch keinen Index gedeckt ist.
`email`	E-Mail	EXAKTER Treffer auf die vollständige Adresse, nie ein Teilstring. Kein Treffer ist eine leere Liste — nie ein anderer Status.
`phone`	string, höchstens 32 Zeichen	EXAKTER Treffer auf die gespeicherte Form in internationaler Schreibweise, z. B. `+4366412345678`.
`hasTable`	true \| false	`true`: nur Reservierungen mit zugeordnetem Tisch. `false`: nur die ohne — genau die Liste, die der Wirt am Morgen durchgeht.
`limit`	integer 1–200Vorgabe: 50	Zeilen je Seite. Ein Wert über 200 ist 400 und nicht etwa stillschweigend gekappt — sonst hielte der Aufrufer eine halbe Antwort für eine ganze.
`cursor`	undurchsichtiger Zeiger	`nextCursor` der vorigen Antwort, unverändert. Gilt nur mit unveränderten Filtern und unveränderter Sortierung.
`sort`	date \| updatedAt \| createdAtVorgabe: date	Sortierfeld. `date` sortiert nach Tag, dann Uhrzeit; für einen Abgleich ist `updatedAt` richtig.
`dir`	asc \| descVorgabe: asc	Richtung. Sie ist Teil des Zeigers und darf sich zwischen zwei Seiten nicht ändern.
`includeTotal`	true \| falseVorgabe: false	Ergänzt `total`. Kostet eine zweite Abfrage über dieselbe Menge.

Mögliche Fehler

validation — Unbekannter Parameter, `date` zusammen mit `dateFrom`/`dateTo`, Enddatum vor Startdatum, `q` ohne Datumsfenster, fremde `areaId`, unlesbarer oder fremder `cursor`.
forbidden — Dem Schlüssel fehlt `reservations:read`.
plan_upgrade_required — Der Plan des Betriebs enthält Reservierungen nicht.
trial_expired — Die Testphase ist beendet und kein Plan gewählt.
rate_limited — 600 Leseaufrufe je Minute und Schlüssel bzw. 1 200 je Minute und Betrieb überschritten.

Ohne `status`-Filter enthält die Liste AUCH stornierte und No-Show-Reservierungen. Für einen Tagesplan ist `status=CONFIRMED,PENDING,OPTION` fast immer gemeint.
Die Antwort trägt den flachen Umschlag: `data`, `nextCursor`, `hasMore`, `limit` und bei `includeTotal=true` zusätzlich `total`.

POST/api/v1/reservations

Eine Reservierung anlegen — durch dieselbe Verfügbarkeitsprüfung, die auch der Gast im Widget durchläuft.

Rechte

reservations:write

Plan-Merkmal reservations — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`	string bis 255 Zeichen	Nicht Pflicht, aber dringend empfohlen: ohne ihn legt ein Netzwiederholversuch eine zweite Reservierung an. Eine UUIDv4 je fachlichem Vorgang.
`X-TacticTable-Dry-Run`	1	Rechnet alles durch und schreibt nichts. Die Antwort enthält unter `would`, was entstanden wäre.

Felder im Rumpf

Name	Typ	Bedeutung
`guestName`Pflicht	string, 1–100 Zeichen	Der Name, unter dem der Tisch geführt wird.
`partySize`Pflicht	integer 1–200	Personenzahl. Sie steuert die Tischsuche und wird gegen die Online-Grenzen des Betriebs geprüft.
`date`Pflicht	YYYY-MM-DD	Kalendertag des Betriebs. Ein Zeitstempel wird abgewiesen, nicht gekürzt.
`time`Pflicht	HH:mm	Beginn als naive Ortszeit. Muss eine Uhrzeit sein, die die Verfügbarkeitsrechnung für diesen Tag anbietet.
`email`	E-Mail oder null	Kontaktadresse des Gastes. `null` und `""` bedeuten beide „nicht gesetzt".
`phone`	Rufnummer oder null	Wird nach E.164 normalisiert gespeichert (`+4366412345678`). Eine unlesbare Nummer ist 400.
`endTime`	HH:mm oder null	Nur nötig, wenn für diese Startzeit eine Sloteinstellung greift — dann nennt `GET /api/v1/availability` unter `endTimes` die zulässigen Werte. Sonst bestimmt der Betrieb die Dauer.
`areaId`	UUID oder null	Gewünschter Bereich. Er muss zu diesem Betrieb gehören, online buchbar und in der Saison sein.
`tableIds`	Liste von UUIDs, höchstens 30	Genau diese Tische belegen. Weglassen heisst: der Tischplan sucht selbst — das ist der Normalfall.
`notes`	string bis 1000 Zeichen oder null	Wunsch des Gastes. Erscheint im Dashboard und in der Bestätigung.
`internalNotes`	string bis 2000 Zeichen oder null	Interner Vermerk. Verlangt die Handlung `action:guests.personal` — sonst ist er in keiner Antwort lesbar.
`tableGuaranteed`	booleanVorgabe: false	Der Tisch ist dem Gast fest zugesagt und wird nicht umgelegt.
`source`	API \| PHONE \| MANUAL \| WALKIN \| WIDGET \| WAITLISTVorgabe: API	Herkunft der Buchung, für die Auswertung im Dashboard. Die Vorgabe `API` ist fast immer richtig. Setzen Sie stattdessen `PHONE`, wenn Ihr System eine telefonische Buchung weiterreicht, `WALKIN` für Laufkundschaft ohne Voranmeldung, `WIDGET` für ein eigenes Buchungsfenster, `WAITLIST` für eine nachgerückte Buchung. `MANUAL` bleibt dem Eintrag im Dashboard vorbehalten.
`status`	PENDING \| CONFIRMED \| OPTIONVorgabe: CONFIRMED	Zustand bei der Entstehung. `CONFIRMED` ist der ZUGESAGTE Tisch — der Gast darf sich darauf verlassen. `OPTION` ist die unverbindliche Vormerkung mit Zeitfenster, die verfällt, wenn niemand bestätigt. `PENDING` ist die eingegangene Anfrage, die noch jemand ansehen muss. Wer hier `CONFIRMED` setzt, wo er `OPTION` meint, schickt den Gast mit einer Zusage weg, die der Betrieb nie gegeben hat. `CANCELED`, `NOSHOW` und `COMPLETED` sind hier NICHT erlaubt — sonst wäre „direkt als NOSHOW anlegen" der Weg um die Handlung `reservations.status` herum.
`guestId`	UUID oder null	Einen bestehenden Gast verknüpfen, statt ihn über Name und Kontakt suchen zu lassen.

Mögliche Fehler

validation — Schema verletzt, unbekanntes Feld, fremde `areaId`/`tableIds`/`guestId`, oder die Torwache lehnt aus einem Eingabegrund ab (`unknown_area`, `area_not_bookable`, `invalid_time`, `end_time_required`, `party_size`).
read_only_field — Der Rumpf setzt ein Feld, das der Server bestimmt — `startsAt`, `durationMin`, `depositAmount`, `notify`, `force` und weitere.
conflict — Die Torwache lehnt aus einem Zustandsgrund ab: `closed`, `blocked`, `limit`, `capacity`, `advance` oder `table_conflict`.
forbidden — Dem Schlüssel fehlt `reservations:write`.
forbidden_action — `internalNotes` ohne die Handlung `action:guests.personal`.
idempotency_key_reuse — Derselbe `Idempotency-Key` wurde bereits für eine andere Anfrage benutzt.
idempotency_in_progress — Eine Anfrage mit diesem Schlüssel läuft noch.

Antwortet mit 201 und dem Körper `{ "reservation": { … } }`.
Ein Gast wird bei Bedarf automatisch angelegt oder gefunden — genau wie im Dashboard. Sie müssen ihn nicht vorher erzeugen.
Es geht KEINE Mail an den Gast. Wer eine Bestätigung verschicken will, tut das aus seinem eigenen System.

GET/api/v1/reservations/{id}

Eine Reservierung vollständig lesen, samt ETag für ein späteres Schreiben ohne Überfahren.

Rechte

reservations:read

Plan-Merkmal reservations — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Reservierung. Eine fremde Kennung ergibt 404 — nie 403, das verriete, dass es die Zeile gibt.

Mögliche Fehler

not_found — Die Kennung gehört zu keiner Reservierung DIESES Betriebs.
forbidden — Dem Schlüssel fehlt `reservations:read`.

Antwortet mit `{ "reservation": { … } }` und der Kopfzeile `ETag` (schwach, z. B. `W/"1789412460123"`).
Listen liefern KEIN ETag — heben Sie es aus dem Einzelabruf auf.

PATCH/api/v1/reservations/{id}

Einzelne Felder ändern. Ein fehlendes Feld bleibt unverändert; ein ausdrückliches `null` leert es.

Rechte

reservations:write

Plan-Merkmal reservations — fehlt es dem Betrieb, antwortet die Route mit 402 plan_upgrade_required.

Pfad

Name	Typ	Bedeutung
`{id}`Pflicht	UUID	Kennung der Reservierung.

Kopfzeilen

Name	Typ	Bedeutung
`If-Match`	ETag-Wert	Schreibt nur, wenn sich die Zeile seit Ihrem Lesen nicht geändert hat. Sonst 412. `*` heisst „nur, wenn es die Zeile gibt".
`Idempotency-Key`	string bis 255 Zeichen	Freiwillig. Bei einer Wiederholung nach Netzabbruch kommt dieselbe Antwort zurück statt einer zweiten Änderung.

Felder im Rumpf

Name	Typ	Bedeutung
`guestName`	string, 1–100 Zeichen	Neuer Name.
`partySize`	integer 1–200	Neue Personenzahl. Löst die Verfügbarkeitsprüfung und gegebenenfalls eine neue Tischsuche aus.
`date`	YYYY-MM-DD	Verschieben auf einen anderen Tag. Die Torwache läuft erneut.
`time`	HH:mm	Neue Startzeit. Die eigene bisherige Belegung wird dabei ausgeklammert — eine Verschiebung um 15 Minuten blockiert sich nicht selbst.
`endTime`	HH:mm oder null	Neue Endzeit, wenn eine Sloteinstellung greift.
`areaId`	UUID oder null	Anderer Bereich; `null` hebt die Zuordnung auf.
`tableIds`	Liste von UUIDs, höchstens 30	ERSETZT die Zuordnung vollständig. `[]` löscht sie und verhindert, dass der Plan selbst wieder einen Tisch sucht. Das Feld wegzulassen heisst „unverändert".
`notes`	string bis 1000 Zeichen oder null	Gastwunsch; `null` oder `""` leert ihn.
`internalNotes`	string bis 2000 Zeichen oder null	Interner Vermerk. Verlangt `action:guests.personal`.
`tableGuaranteed`	boolean	Feste Tischzusage setzen oder aufheben.
`guestId`	UUID oder null	Verknüpfung zum Gastprofil setzen oder lösen.

Mögliche Fehler

nothing_to_write — Der Rumpf enthält kein änderbares Feld. Ein Aufruf, der nichts ändert, wird nicht als Erfolg beantwortet.
read_only_field — Der Rumpf enthält `status` (das läuft über die eigene Route) oder ein anderes vom Server bestimmtes Feld.
validation — Schema verletzt, fremde Kennung im Rumpf oder Eingabegrund der Torwache.
conflict — Die neue Zeit ist nicht verfügbar oder einer der genannten Tische ist belegt.
precondition_failed — `If-Match` passt nicht mehr — jemand anderes war schneller.
not_found — Die Kennung gehört zu keiner Reservierung dieses Betriebs.

`status` steht ausdrücklich auf der Sperrliste. Ohne das wäre `PATCH` der Weg um die Handlung `reservations.status` herum: ein Schlüssel mit blossem `reservations:write` könnte NOSHOW setzen und damit eine Gebühr einziehen lassen.
Antwortet mit 200, `{ "reservation": { … } }` und einem frischen `ETag`.

Codebeispiele

curl — der Tagesplan

curl

1curl -sS -G https://tactictable.com/api/v1/reservations \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  --data-urlencode "date=2026-09-20" \4  --data-urlencode "status=CONFIRMED,PENDING,OPTION" \5  --data-urlencode "sort=date" \6  --data-urlencode "dir=asc" \7  --data-urlencode "limit=200"

`-G` mit `--data-urlencode` baut den Query-String sauber zusammen — das Komma in `status` und ein `+` in einer Rufnummer sind sonst die zwei Stellen, an denen ein von Hand gebauter Aufruf kippt.

Antwort 200 — GET /api/v1/reservations

JSON

1{2  "data": [3    {4      "id": "31061d44-ac33-550d-b4d0-a16973e270f5",5      "status": "CONFIRMED",6      "source": "WIDGET",7      "date": "2026-09-20",8      "time": "19:30",9      "endTime": "21:30",10      "durationMin": 120,11      "startsAt": "2026-09-20T19:30:00+02:00",12      "endsAt": "2026-09-20T21:30:00+02:00",13      "timezone": "Europe/Vienna",14      "partySize": 4,15      "guestName": "Familie Berger",16      "email": "anna.berger@example.at",17      "phone": "+4366412345678",18      "notes": "Fensterplatz, wenn möglich",19      "internalNotes": null,20      "tableGuaranteed": false,21      "isPlanned": true,22      "isPlaced": false,23      "areaId": "ce2038c4-0bb6-51d7-b705-dc831177a2d8",24      "area": { "id": "ce2038c4-0bb6-51d7-b705-dc831177a2d8", "name": "Gastraum" },25      "tableIds": ["653d49c8-cd70-53ea-839f-d3131a574417"],26      "tables": [{ "id": "653d49c8-cd70-53ea-839f-d3131a574417", "name": "7" }],27      "guestId": "fb69190b-e35f-5a2e-be8a-b7c272782903",28      "answers": [29        { "fieldId": "anlass", "label": "Anlass", "value": "Geburtstag" }30      ],31      "seatedAt": null,32      "finishedAt": null,33      "confirmedAt": "2026-09-13T17:02:11.004Z",34      "canceledAt": null,35      "cancelReason": null,36      "anonymizedAt": null,37      "createdAt": "2026-09-13T17:02:10.887Z",38      "updatedAt": "2026-09-13T17:02:11.004Z"39    }40  ],41  "nextCursor": null,42  "hasMore": false,43  "limit": 20044}

`internalNotes` ist `null`, weil dieser Schlüssel die Handlung `guests.personal` nicht trägt — das heisst NICHT, dass keine Notiz da ist. `isPlanned` sagt, dass ein Tisch zugeordnet ist; `isPlaced`, dass der Gast bereits sitzt. `answers` sind die Antworten auf die Zusatzfragen des Betriebs, roh und unmaskiert — wer sie anzeigt, muss selbst maskieren.

curl — Reservierung anlegen

curl

1curl -sS -X POST https://tactictable.com/api/v1/reservations \2  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \3  -H "Content-Type: application/json" \4  -H "Idempotency-Key: 6b2f0d18-4f0a-4f6b-9a91-0c4a2d8e7f51" \5  -d '{6    "guestName": "Familie Berger",7    "email": "anna.berger@example.at",8    "phone": "+4366412345678",9    "partySize": 4,10    "date": "2026-09-20",11    "time": "19:30",12    "notes": "Fensterplatz, wenn möglich",13    "source": "PHONE",14    "status": "CONFIRMED"15  }'

Ohne `tableIds` sucht der Tischplan selbst. `source: "PHONE"` sagt der Auswertung, dass diese Buchung am Telefon entstanden ist — der Vorgabewert wäre `API`.

Antwort 201 — angelegt

JSON

1{2  "reservation": {3    "id": "7a8425f8-bf97-5d1e-b9bd-49193c662c2f",4    "status": "CONFIRMED",5    "source": "PHONE",6    "date": "2026-09-20",7    "time": "19:30",8    "endTime": "21:30",9    "durationMin": 120,10    "startsAt": "2026-09-20T19:30:00+02:00",11    "endsAt": "2026-09-20T21:30:00+02:00",12    "timezone": "Europe/Vienna",13    "partySize": 4,14    "guestName": "Familie Berger",15    "email": "anna.berger@example.at",16    "phone": "+4366412345678",17    "notes": "Fensterplatz, wenn möglich",18    "internalNotes": null,19    "tableGuaranteed": false,20    "isPlanned": true,21    "isPlaced": false,22    "areaId": "ce2038c4-0bb6-51d7-b705-dc831177a2d8",23    "area": { "id": "ce2038c4-0bb6-51d7-b705-dc831177a2d8", "name": "Gastraum" },24    "tableIds": ["bfdfcf1b-8d9b-5708-8a65-9f553849dfae"],25    "tables": [{ "id": "bfdfcf1b-8d9b-5708-8a65-9f553849dfae", "name": "12" }],26    "guestId": "fb69190b-e35f-5a2e-be8a-b7c272782903",27    "answers": [],28    "seatedAt": null,29    "finishedAt": null,30    "confirmedAt": "2026-09-14T09:31:07.220Z",31    "canceledAt": null,32    "cancelReason": null,33    "anonymizedAt": null,34    "createdAt": "2026-09-14T09:31:07.220Z",35    "updatedAt": "2026-09-14T09:31:07.220Z"36  }37}

`durationMin` und `endTime` hat der Server gesetzt — sie folgen aus den Einstellungen des Betriebs und lassen sich nicht mitschicken. `guestId` zeigt auf den Gast, der dabei gefunden oder angelegt wurde.

Antwort 409 — der Zeitraum gibt nichts her

JSON

1{2  "error": "conflict",3  "message": "Für diese Personenzahl ist zu dieser Zeit kein Tisch mehr frei.",4  "reason": "capacity",5  "docs": "https://tactictable.com/dokumentation/api/fehler/conflict",6  "requestId": "req_8f31c0a94d2b47e6ba05"7}

`reason` benennt die Ursache maschinenlesbar: `closed` (an diesem Tag keine Online-Reservierung), `blocked` (gesperrt), `limit` (Kontingent der Uhrzeit ausgeschöpft), `capacity` (kein Tisch), `advance` (ausserhalb des Buchungszeitraums), `table_conflict` (ein genannter Tisch ist belegt). Zeigen Sie dem Anrufer die Uhrzeiten aus `GET /api/v1/availability` statt einer Fehlermeldung.

TypeScript — Tagesplan holen und anzeigen

TypeScript

1interface Reservierung {2    id: string3    status: string4    date: string5    time: string6    endTime: string | null7    partySize: number8    guestName: string9    phone: string | null10    tables: { id: string; name: string }[]11    timezone: string12}13 14interface Liste {15    data: Reservierung[]16    nextCursor: string | null17    hasMore: boolean18    limit: number19}20 21export async function tagesplan(token: string, tag: string): Promise<Reservierung[]> {22    const parameter = new URLSearchParams({23        date: tag,24        status: 'CONFIRMED,PENDING,OPTION',25        sort: 'date',26        dir: 'asc',27        limit: '200',28    })29 30    const antwort = await fetch('https://tactictable.com/api/v1/reservations?' + parameter, {31        headers: { Authorization: 'Bearer ' + token, Accept: 'application/json' },32    })33    if (!antwort.ok) throw new Error('HTTP ' + antwort.status)34 35    const seite = (await antwort.json()) as Liste36    // Ein Haus mit mehr als 200 Reservierungen an einem Tag blaettert weiter;37    // siehe „Blaetterung".38    return seite.data39}

`URLSearchParams` kodiert das Komma in `status` korrekt. Die Schnittstelle nimmt Kommalisten an — das ist im Haus schon die Form, nicht etwa `status[]=`.

Python — Reservierung anlegen

Python

1import json2import uuid3 4import requests5 6 7def reservierung_anlegen(token: str, daten: dict) -> dict:8    rumpf = json.dumps(daten)9    antwort = requests.post(10        "https://tactictable.com/api/v1/reservations",11        data=rumpf,12        headers={13            "Authorization": "Bearer " + token,14            "Content-Type": "application/json",15            "Idempotency-Key": str(uuid.uuid4()),16        },17        timeout=30,18    )19 20    ergebnis = antwort.json()21 22    if antwort.status_code == 409:23        # Nicht als Ausfall behandeln: der Zeitraum gibt nichts her.24        # Dem Anrufer stattdessen freie Uhrzeiten anbieten.25        raise ValueError("nicht buchbar: " + ergebnis.get("reason", "conflict"))26 27    if antwort.status_code != 201:28        raise RuntimeError("{}: {}".format(ergebnis["error"], ergebnis["message"]))29 30    return ergebnis["reservation"]31 32 33# reservierung_anlegen(token, {34#     "guestName": "Familie Berger",35#     "phone": "+4366412345678",36#     "partySize": 4,37#     "date": "2026-09-20",38#     "time": "19:30",39#     "source": "PHONE",40# })

409 ist kein Ausfall, sondern eine Antwort: „zu dieser Zeit geht es nicht". Wer das als Fehler protokolliert, hat ein Protokoll voller Meldungen, die keine sind.

PHP — Reservierung ändern, ohne Fremdes zu überfahren

PHP

1<?php2 3function reservierung_aendern(string $token, string $id, array $felder): array4{5    // 1. Lesen — der ETag steht in den Kopfzeilen.6    $ch = curl_init('https://tactictable.com/api/v1/reservations/' . rawurlencode($id));7    curl_setopt_array($ch, [8        CURLOPT_RETURNTRANSFER => true,9        CURLOPT_HEADER => true,10        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token],11    ]);12    $roh = curl_exec($ch);13    $kopflaenge = curl_getinfo($ch, CURLINFO_HEADER_SIZE);14    curl_close($ch);15 16    $kopf = substr($roh, 0, $kopflaenge);17    $etag = null;18    if (preg_match('/^etag:\s*(.+)$/mi', $kopf, $treffer)) {19        $etag = trim($treffer[1]);20    }21 22    // 2. Schreiben mit genau diesem Wert.23    $kopfzeilen = [24        'Authorization: Bearer ' . $token,25        'Content-Type: application/json',26    ];27    if ($etag !== null) {28        $kopfzeilen[] = 'If-Match: ' . $etag;29    }30 31    $ch = curl_init('https://tactictable.com/api/v1/reservations/' . rawurlencode($id));32    curl_setopt_array($ch, [33        CURLOPT_RETURNTRANSFER => true,34        CURLOPT_CUSTOMREQUEST => 'PATCH',35        CURLOPT_HTTPHEADER => $kopfzeilen,36        CURLOPT_POSTFIELDS => json_encode($felder, JSON_THROW_ON_ERROR),37    ]);38    $rumpf = curl_exec($ch);39    $status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);40    curl_close($ch);41 42    $json = json_decode($rumpf, true, 512, JSON_THROW_ON_ERROR);43 44    if ($status === 412) {45        throw new RuntimeException('Zwischenzeitlich geaendert — neu lesen und erneut versuchen.');46    }47    if ($status !== 200) {48        throw new RuntimeException($json['error'] . ': ' . $json['message']);49    }50 51    return $json['reservation'];52}

`CURLOPT_CUSTOMREQUEST => "PATCH"` — cURL kennt keinen eigenen Schalter dafür. Ohne `If-Match` gewinnt der letzte Schreiber, und die Änderung des Kellners von vor einer Minute ist weg.

Go — inkrementeller Abgleich des Buchs

1package tactictable2 3import (4    "encoding/json"5    "fmt"6    "net/http"7    "net/url"8)9 10// Geaendert holt alle Reservierungen, die sich seit "seit" geaendert haben.11// Sortiert nach updatedAt aufsteigend: eine Zeile, die waehrend des Blaetterns12// geschrieben wird, wandert ans ENDE und faellt nicht durch.13func Geaendert(klient *http.Client, token, seit string) ([]Reservierung, error) {14    gesammelt := []Reservierung{}15    cursor := ""16 17    for seite := 0; seite < 1000; seite++ {18        frage := url.Values{}19        frage.Set("updatedSince", seit)20        frage.Set("sort", "updatedAt")21        frage.Set("dir", "asc")22        frage.Set("limit", "200")23        if cursor != "" {24            frage.Set("cursor", cursor)25        }26 27        anfrage, err := http.NewRequest("GET", "https://tactictable.com/api/v1/reservations?"+frage.Encode(), nil)28        if err != nil {29            return nil, err30        }31        anfrage.Header.Set("Authorization", "Bearer "+token)32 33        antwort, err := klient.Do(anfrage)34        if err != nil {35            return nil, err36        }37        defer antwort.Body.Close()38 39        if antwort.StatusCode != http.StatusOK {40            return nil, fmt.Errorf("HTTP %d", antwort.StatusCode)41        }42 43        var gelesen Liste44        if err := json.NewDecoder(antwort.Body).Decode(&gelesen); err != nil {45            return nil, err46        }47        gesammelt = append(gesammelt, gelesen.Data...)48 49        if gelesen.NextCursor == nil {50            return gesammelt, nil51        }52        cursor = *gelesen.NextCursor53    }54 55    return nil, fmt.Errorf("mehr als 1000 Seiten — Zeitfenster verkleinern")56}

Merken Sie sich den höchsten `updatedAt` aus dem Ergebnis, nicht die Uhrzeit Ihres Laufs. Sonst verlieren Sie jede Zeile, die zwischen der Abfrage und dem Ende Ihres Laufs geschrieben wurde.

Siehe auch

← Zurück zu REST-API