Aller au contenu
vokse.
Parcourir la référence
Retour à la référence de l'API
Guide

Historique, annuler et rétablir dans l'API

vokse tient un registre des changements par foyer : une ligne par changement atomique avec la charge exacte pour l’inverser, son auteur et l’instant. L’API expose les lignes produites par une écriture, liste l’historique avec ses auteurs et inverse tout changement enregistré, précisément, depuis n’importe quel client.

L’en-tête X-Vokse-History-Events

Toute écriture réussie (DELETE 204 compris) renvoie les ids des lignes d’historique produites, séparés par des virgules. Une action groupée n’expose que l’id de son groupe. Conservez-les pour proposer Annuler à vos utilisateurs ; les rejeux idempotents ne portent pas l’en-tête, la première réponse l’a déjà fait.

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

Lire l’historique

GET /households/{id}/history renvoie les changements du plus récent au plus ancien, paginés par curseur. Filtrez par membre (userId), famille (budget, transaction, category…), type (budget.assign, transaction.update…), fenêtre temporelle, groupe (ses membres) ou ids explicites. Les inversions sont des changements comme les autres et sont listées sauf avec 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_…"

Annuler et rétablir

POST /history/{eventId}/undo applique l’inverse exact d’un changement via la même logique métier que l’écriture d’origine, enregistre l’inversion comme nouvelle ligne d’historique et marque le changement annulé. POST /history/{eventId}/redo inverse cette inversion. Les deux exigent une Idempotency-Key et renvoient l’inversion, la cible mise à jour et ce qui a été touché.

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"
  • Propriétaire ou éditeur uniquement ; un changement réservé au propriétaire (réinitialisation d’un mois, suppressions) exige un propriétaire pour l’inverser.
  • Une clé API a besoin de write:history ET du scope d’écriture des données inversées (write:budgets pour le budget, write:transactions pour une transaction, …).
  • L’inversion est refusée avec 409 HISTORY_STALE si les données ne correspondent plus à l’état enregistré ; rien n’est modifié.
  • Deux clients en course pour la même annulation : un seul gagne, l’autre reçoit 409 HISTORY_ALREADY_UNDONE.
  • Les refus métier passent tels quels, p. ex. INSUFFICIENT_CATEGORY_FUNDS quand remettre l’argent n’est plus possible.
  • Les changements enregistrés avec undoable=false (clôture ou rapprochement d’un compte) sont listés pour revue mais ne s’inversent pas.

Codes d’erreur

  • HISTORY_STALE: l’entité a changé depuis ; voir details.reason.
  • HISTORY_ALREADY_UNDONE: un autre client l’a inversé en premier.
  • HISTORY_NOT_UNDONE: rétablir demandé sur un changement en vigueur.
  • HISTORY_NOT_UNDOABLE: enregistré pour revue seulement.
  • HISTORY_PARTIAL: une inversion de groupe a appliqué certains membres et refusé d’autres ; voir partial.failed.