Vorbestellte Positionen lesen und abrechnen

Set-Menüs und Anlassangebote wie eine Geburtstagstorte stehen als `lineItems` an der Reservierung; eine Kasse rechnet jede Position genau einmal ab.

Für Entwickler

Voraussetzungen

Recht `reservations:read` zum Lesen, `reservations:write` zum Abrechnen
Telefon-Agent für die Umgebung freigeschaltet – sonst gibt es weder `lineItems` noch die Route
Plan-Merkmal „Reservierungen"

NUR MIT TELEFON-AGENT. Ist er für die Umgebung freigeschaltet, trägt jede Reservierung in jeder Antwort zusätzlich `lineItems` — auch leer, dann heisst das „keine Positionen“. Eine Position ist etwas, das der Gast zur Reservierung bestellt hat, etwa ein Set-Menü (`kind: SET_MENU`) oder eine Geburtstagstorte (`kind: PRODUCT`): Menge, Preis- und Steuersnapshot vom Zeitpunkt der Bestellung (`unitPriceGrossCents`, `unitPriceNetCents`, `vatRateBps`, `totalGrossCents`, alle Beträge ganze Cent), wo und wann der Gast zugestimmt hat (`consentChannel` `WIDGET`, `PHONE_AGENT` oder `STAFF`, `consentAt`) und ihr Stand: `ACTIVE` ist offen und noch abzurechnen, `SETTLED` ist abgerechnet (dann mit `settlementRef` und `settledAt`), `CANCELED` ist storniert. Ohne Freischaltung fehlt das Feld ganz. Eine Kasse rechnet eine Position genau einmal über `POST …/line-items/{itemId}/settle` ab; eine Übergabe an eine bestimmte Kasse ist darüber hinaus nicht eingebaut.

GENAU EINMAL, AUCH BEI WIEDERHOLUNG. `settle` setzt eine offene Position per Vergleich-und-Tausch auf `SETTLED`. Dieselbe `settlementRef` noch einmal ist ein Erfolg ohne Änderung (`changed: false`) – so übersteht eine Kasse einen Netzabbruch, ohne doppelt zu buchen. Eine andere Nummer für eine schon abgerechnete Position ist 409 `conflict` mit `reason: other_reference`, eine stornierte Position 409 mit `reason: canceled`.

POSITIONEN ENTSTEHEN NICHT ÜBER DIE API. Sie legt der Gast im Buchungs-Widget, der Telefon-Agent mit Zustimmung des Gastes oder das Team im Reservierungsdetail an. Die API liest sie (`lineItems` in jeder Reservierungsantwort) und hält die Abrechnung fest – Geld bewegt sie nicht.

Die Route

POST/api/v1/reservations/{id}/line-items/{itemId}/settle

Eine vorbestellte Position (Set-Menü, Torte) genau einmal als abgerechnet markieren, mit der Beleg- oder Bonnummer der Kasse.

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. Eine fremde Kennung ergibt 404.
`{itemId}`Pflicht	UUID	Kennung der Position aus `lineItems[].id`. Gehört sie nicht zu dieser Reservierung, ist das 404.

Kopfzeilen

Name	Typ	Bedeutung
`Idempotency-Key`	string bis 255 Zeichen	Freiwillig. Eine Wiederholung mit demselben Schlüssel bekommt dieselbe Antwort; dieselbe `settlementRef` ist ohnehin harmlos.
`X-TacticTable-Dry-Run`	1	Prüft, ohne zu schreiben. Die Antwort nennt unter `would` den Übergang (`from` → `to: SETTLED`).

Felder im Rumpf

Name	Typ	Bedeutung
`settlementRef`Pflicht	string, 1–128 druckbare ASCII-Zeichen	Beleg- oder Bonnummer der Kasse, unter der die Position bezahlt wurde. Sie macht den Vorgang wiederholbar: dieselbe Nummer noch einmal ist ein Erfolg ohne Änderung, eine andere ein Konflikt.

Mögliche Fehler

validation — Rumpf fehlt, unbekanntes Feld, oder `settlementRef` leer, zu lang bzw. mit nicht druckbaren Zeichen.
not_found — Reservierung oder Position gehört nicht zu diesem Betrieb – oder der Telefon-Agent ist auf dieser Umgebung nicht freigeschaltet; dann gibt es die Route nicht.
conflict — Die Position ist storniert (`reason: canceled`) oder schon mit einer anderen Nummer abgerechnet (`reason: other_reference`).
forbidden — Dem Schlüssel fehlt `reservations:write`.
plan_upgrade_required — Der Plan des Betriebs enthält Reservierungen nicht.
idempotency_key_reuse — Derselbe `Idempotency-Key` wurde bereits für eine andere Anfrage benutzt.

Antwortet mit 200 und `{ "lineItem": { … }, "changed": true }`; war die Position mit derselben Nummer schon abgerechnet, mit `changed: false`.
Die Abrechnung bewegt kein Geld – sie hält fest, dass die Kasse es getan hat. Deshalb genügt `reservations:write`.
Nur mit freigeschaltetem Telefon-Agenten; ohne ihn antwortet die Route mit 404 und Reservierungen tragen kein `lineItems`.

Codebeispiele

curl — eine vorbestellte Torte abrechnen

curl

1curl -sS -X POST \2  https://tactictable.com/api/v1/reservations/31061d44-ac33-550d-b4d0-a16973e270f5/line-items/c4a1f8e2-5b3d-4f6a-9e7c-2d8b0a1f3e95/settle \3  -H "Authorization: Bearer tt_live_if3u5vp6maf67xmw_PT1xP8EQF7reKUtLcZ7v9z5qaRKmoxeHmd27JpaDvfM" \4  -H "Content-Type: application/json" \5  -H "Idempotency-Key: 0b8e6f5a-2c1d-4e7b-9a3f-5d2c8b1e4f60" \6  -d '{"settlementRef": "BON-2026-004711"}'

Die Nummer ist die des Kassenbons. Schickt Ihre Kasse den Aufruf nach einem Netzabbruch noch einmal, kommt `changed: false` zurück – abgerechnet ist die Position trotzdem nur einmal.

Antwort — die abgerechnete Position

JSON

1{2  "lineItem": {3    "id": "c4a1f8e2-5b3d-4f6a-9e7c-2d8b0a1f3e95",4    "kind": "PRODUCT",5    "name": "Geburtstagstorte Schokolade",6    "quantity": 1,7    "unitPriceGrossCents": 3900,8    "unitPriceNetCents": 3545,9    "vatRateBps": 1000,10    "totalGrossCents": 3900,11    "dietTag": null,12    "productId": "b79f086d-d89e-53c5-81dc-888d3d93ce3b",13    "setMenuId": null,14    "variantId": null,15    "offerRuleId": null,16    "serviceDate": "2026-09-20",17    "consentChannel": "PHONE_AGENT",18    "consentAt": "2026-09-14T09:31:07.220Z",19    "state": "SETTLED",20    "settledAt": "2026-09-20T21:48:12.004Z",21    "settlementRef": "BON-2026-004711",22    "createdAt": "2026-09-14T09:31:07.220Z"23  },24  "changed": true25}

Preis und Steuersatz sind der Stand bei der Bestellung, nicht der heutige Katalog. `consentChannel: "PHONE_AGENT"` heisst: Der Gast hat am Telefon zugestimmt.

TypeScript — abrechnen mit Wiederholung nach Netzabbruch

TypeScript

1const BASIS = 'https://tactictable.com/api/v1'2 3export async function abrechnen(reservierung: string, position: string, bon: string): Promise<boolean> {4    const antwort = await fetch(`${BASIS}/reservations/${reservierung}/line-items/${position}/settle`, {5        method: 'POST',6        headers: {7            Authorization: `Bearer ${process.env.TACTICTABLE_TOKEN}`,8            'Content-Type': 'application/json',9            'Idempotency-Key': `settle-${position}-${bon}`,10        },11        body: JSON.stringify({ settlementRef: bon }),12    })13    if (antwort.status === 409) throw new Error('Position storniert oder schon mit anderem Bon abgerechnet')14    if (!antwort.ok) throw new Error(`HTTP ${antwort.status}`)15    const { changed } = await antwort.json()16    return changed17}

Der `Idempotency-Key` hängt an Position und Bon: Eine Wiederholung desselben Vorgangs bekommt dieselbe Antwort, ein anderer Bon ist ein neuer Vorgang.

Python — offene Positionen eines Tages abrechnen

Python

1import os2import requests3 4BASIS = "https://tactictable.com/api/v1"5KOPF = {"Authorization": f"Bearer {os.environ['TACTICTABLE_TOKEN']}"}6 7seite = requests.get(f"{BASIS}/reservations", headers=KOPF,8                     params={"date": "2026-09-20", "status": "CONFIRMED"}, timeout=10).json()9for reservierung in seite["data"]:10    rid = reservierung["id"]11    for position in reservierung.get("lineItems", []):12        if position["state"] != "ACTIVE":13            continue14        pid = position["id"]15        antwort = requests.post(16            f"{BASIS}/reservations/{rid}/line-items/{pid}/settle",17            headers={**KOPF, "Idempotency-Key": f"settle-{pid}"},18            json={"settlementRef": "BON-2026-004711"}, timeout=10)19        antwort.raise_for_status()

`lineItems` fehlt ganz, wenn der Telefon-Agent auf der Umgebung nicht freigeschaltet ist – deshalb `get(…, [])`. Nur `ACTIVE` ist noch abzurechnen. Die Bonnummer liefert Ihre Kasse; mehrere Positionen auf einem Bon tragen dieselbe Nummer. Die Liste blättert in der Praxis über `nextCursor` (siehe Blätterung).

Siehe auch

← Zurück zu REST-API