Saltar para o conteúdo
vokse.
Explorar a referência
Voltar à referência da API
Guia

Histórico, anular e refazer na API

O vokse mantém um livro de alterações por agregado: uma linha por alteração atómica com a carga exata para a reverter, quem a fez e quando. A API expõe as linhas produzidas por uma escrita, lista o histórico com os autores e reverte qualquer alteração registada, com precisão, a partir de qualquer cliente.

O cabeçalho X-Vokse-History-Events

Toda a escrita bem-sucedida (incluindo DELETE 204) devolve os ids das linhas de histórico produzidas, separados por vírgulas. Uma ação em massa expõe apenas o id do seu grupo. Guarde-os para oferecer Anular aos seus utilizadores; as repetições idempotentes não trazem cabeçalho porque a primeira resposta já o trouxe.

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

Ler o histórico

GET /households/{id}/history devolve as alterações da mais recente para a mais antiga, com paginação por cursor. Filtre por membro (userId), família (budget, transaction, category…), tipo (budget.assign, transaction.update…), janela temporal, grupo (os seus membros) ou ids explícitos. As reversões também são alterações e são listadas salvo com 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_…"

Anular e refazer

POST /history/{eventId}/undo aplica o inverso exato de uma alteração através da mesma lógica de domínio da escrita original, regista a reversão como nova linha de histórico e marca a alteração como anulada. POST /history/{eventId}/redo reverte essa reversão. Ambos exigem Idempotency-Key e devolvem a reversão, o alvo atualizado e o que foi afetado.

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"
  • Apenas owner ou editor; uma alteração reservada ao owner (reposição do mês, eliminações) precisa de um owner para ser revertida.
  • Uma API key precisa de write:history E do scope de escrita dos dados revertidos (write:budgets para orçamento, write:transactions para uma transação, …).
  • A reversão é recusada com 409 HISTORY_STALE quando os dados já não correspondem ao estado registado; nada é alterado.
  • Dois clientes a competir pelo mesmo anular: exatamente um ganha, o outro recebe 409 HISTORY_ALREADY_UNDONE.
  • As recusas de domínio passam inalteradas, p. ex. INSUFFICIENT_CATEGORY_FUNDS quando já não é possível devolver o dinheiro.
  • As alterações registadas com undoable=false (fechar ou reconciliar uma conta) são listadas para revisão mas não podem ser revertidas.

Códigos de erro

  • HISTORY_STALE: a entidade mudou entretanto; ver details.reason.
  • HISTORY_ALREADY_UNDONE: outro cliente reverteu-a primeiro.
  • HISTORY_NOT_UNDONE: refazer pedido para uma alteração em vigor.
  • HISTORY_NOT_UNDOABLE: registada apenas para revisão.
  • HISTORY_PARTIAL: uma reversão de grupo aplicou alguns membros e recusou outros; ver partial.failed.