Zum Inhalt springen
vokse.
In der Referenz stöbern
Zurück zur API-Referenz
Leitfaden

Verlauf, Rückgängig und Wiederholen in der API

vokse führt pro Haushalt ein Änderungsbuch: eine Zeile pro atomarer Änderung mit der exakten Nutzlast, um sie zurückzunehmen, wer sie wann gemacht hat. Die API legt die Zeilen eines Schreibvorgangs offen, listet den Verlauf mit Urhebern und nimmt jede aufgezeichnete Änderung präzise zurück, von jedem Client.

Der Header X-Vokse-History-Events

Jeder erfolgreiche Schreibvorgang (auch DELETE 204) liefert die Ids der erzeugten Verlaufszeilen, kommagetrennt. Eine Massenaktion legt nur die Id ihrer Gruppe offen. Behalten Sie sie, um Ihren Nutzern Rückgängig anzubieten; idempotente Wiederholungen tragen keinen Header, die erste Antwort tat es bereits.

bash
PATCH /households/current/budgets/2026-08/categories/01J8… HTTP/1.1Authorization: Bearer vokse_sk_…Idempotency-Key: 3f1c…{"assignedCents":"10000"}HTTP/1.1 200 OKX-Vokse-History-Events: 01M0G0W2879NYKEG8CY3RH42XN

Den Verlauf lesen

GET /households/{id}/history liefert Änderungen neueste zuerst mit Cursor-Paginierung. Filtern Sie nach Mitglied (userId), Familie (budget, transaction, category…), Art (budget.assign, transaction.update…), Zeitfenster, Gruppe (ihre Mitglieder) oder expliziten Ids. Rücknahmen sind ebenfalls Änderungen und werden gelistet, außer mit includeReversals=false.

bash
curl "https://api.vokse.ai/households/current/history?family=budget&from=2026-07-17T00:00:00Z&limit=50" \     -H "Authorization: Bearer vokse_sk_…"

Rückgängig und Wiederholen

POST /history/{eventId}/undo wendet die exakte Umkehrung einer Änderung über dieselbe Domänenlogik wie der ursprüngliche Schreibvorgang an, zeichnet die Rücknahme als neue Verlaufszeile auf und markiert die Änderung als rückgängig gemacht. POST /history/{eventId}/redo nimmt diese Rücknahme zurück. Beide benötigen einen Idempotency-Key und liefern die Rücknahme, das aktualisierte Ziel und das Betroffene.

bash
curl -X POST https://api.vokse.ai/households/current/history/01M0G0W2879NYKEG8CY3RH42XN/undo \     -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: 7c2f9b1e-4a8d-4e3a-9c1b-2f6e8d0a1b3c"
  • Nur Eigentümer oder Bearbeiter; eine Eigentümer-Änderung (Monats-Reset, Löschungen) braucht einen Eigentümer zur Rücknahme.
  • Ein API-Schlüssel braucht write:history UND den Schreib-Scope der zurückgenommenen Daten (write:budgets für Budget, write:transactions für eine Transaktion, …).
  • Die Rücknahme wird mit 409 HISTORY_STALE abgelehnt, wenn die Daten nicht mehr dem aufgezeichneten Zustand entsprechen; nichts wird geändert.
  • Zwei Clients im Wettlauf um dasselbe Rückgängig: genau einer gewinnt, der andere erhält 409 HISTORY_ALREADY_UNDONE.
  • Fachliche Ablehnungen werden unverändert durchgereicht, z. B. INSUFFICIENT_CATEGORY_FUNDS, wenn Geld nicht mehr zurückbewegt werden kann.
  • Mit undoable=false aufgezeichnete Änderungen (Konto schließen oder abstimmen) werden zur Durchsicht gelistet, sind aber nicht rücknehmbar.

Fehlercodes

  • HISTORY_STALE: die Entität hat sich seither geändert; siehe details.reason.
  • HISTORY_ALREADY_UNDONE: ein anderer Client war zuerst.
  • HISTORY_NOT_UNDONE: Wiederholen für eine Änderung, die in Kraft ist.
  • HISTORY_NOT_UNDOABLE: nur zur Durchsicht aufgezeichnet.
  • HISTORY_PARTIAL: eine Gruppen-Rücknahme hat manche Mitglieder angewandt und andere abgelehnt; siehe partial.failed.