Vai al contenuto
vokse.
Sfoglia il riferimento
Torna al riferimento API
Guida

Cronologia, annulla e ripeti nell'API

vokse tiene un registro delle modifiche per nucleo: una riga per ogni modifica atomica con il payload esatto per invertirla, chi l’ha fatta e quando. L’API espone le righe prodotte da una scrittura, elenca la cronologia con gli autori e inverte qualsiasi modifica registrata, con precisione, da qualsiasi client.

L’header X-Vokse-History-Events

Ogni scrittura riuscita (inclusi i DELETE 204) restituisce gli id delle righe di cronologia prodotte, separati da virgola. Un’azione massiva espone solo l’id del suo gruppo. Conservali per offrire Annulla ai tuoi utenti; le ripetizioni idempotenti non portano l’header perché la prima risposta l’ha già fatto.

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

Leggere la cronologia

GET /households/{id}/history restituisce le modifiche dalla più recente con paginazione a cursore. Filtra per membro (userId), famiglia (budget, transaction, category…), tipo (budget.assign, transaction.update…), finestra temporale, gruppo (i suoi membri) o id espliciti. Anche le inversioni sono modifiche e vengono elencate salvo 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_…"

Annulla e ripeti

POST /history/{eventId}/undo applica l’inverso esatto di una modifica attraverso la stessa logica di dominio della scrittura originale, registra l’inversione come nuova riga di cronologia e segna la modifica come annullata. POST /history/{eventId}/redo inverte quell’inversione. Entrambi richiedono Idempotency-Key e restituiscono l’inversione, il target aggiornato e cosa è stato toccato.

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"
  • Solo owner o editor; una modifica riservata all’owner (reset del mese, eliminazioni) richiede un owner per essere invertita.
  • Una API key richiede write:history E lo scope di scrittura dei dati invertiti (write:budgets per il budget, write:transactions per una transazione, …).
  • L’inversione è rifiutata con 409 HISTORY_STALE quando i dati non corrispondono più allo stato registrato; nulla viene modificato.
  • Due client in gara per lo stesso annulla: esattamente uno vince, l’altro riceve 409 HISTORY_ALREADY_UNDONE.
  • I rifiuti di dominio passano invariati, ad es. INSUFFICIENT_CATEGORY_FUNDS quando non è più possibile rispostare il denaro.
  • Le modifiche registrate con undoable=false (chiudere o riconciliare un conto) sono elencate per revisione ma non invertibili.

Codici di errore

  • HISTORY_STALE: l’entità è cambiata nel frattempo; vedi details.reason.
  • HISTORY_ALREADY_UNDONE: un altro client l’ha invertita prima.
  • HISTORY_NOT_UNDONE: ripeti richiesto su una modifica in vigore.
  • HISTORY_NOT_UNDOABLE: registrata solo per revisione.
  • HISTORY_PARTIAL: un’inversione di gruppo ha applicato alcuni membri e rifiutato altri; vedi partial.failed.