Saltar al contenido
vokse.
Explorar la referencia
Volver a la referencia de la API
Guía

Historial, deshacer y rehacer en la API

vokse mantiene un libro de cambios por hogar: una fila por cambio atómico con la carga exacta para revertirlo, quién lo hizo y cuándo. La API expone las filas que produce una escritura, lista el historial con sus autores y revierte cualquier cambio registrado, con precisión y desde cualquier cliente.

La cabecera X-Vokse-History-Events

Toda escritura correcta (incluidos los DELETE 204) devuelve los ids de las filas de historial que produjo, separados por comas. Una acción masiva expone solo el id de su grupo. Guárdalos si quieres ofrecer Deshacer a tus usuarios; las repeticiones idempotentes no llevan cabecera porque la primera respuesta ya la llevó.

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

Leer el historial

GET /households/{id}/history devuelve los cambios de más nuevo a más antiguo con paginación por cursor. Filtra por miembro (userId), familia (budget, transaction, category…), tipo (budget.assign, transaction.update…), ventana temporal, grupo (sus miembros) o ids explícitos. Las reversiones también son cambios y se listan salvo con 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_…"

Deshacer y rehacer

POST /history/{eventId}/undo aplica el inverso exacto de un cambio a través de la misma lógica de dominio que la escritura original, registra la reversión como nueva fila de historial y marca el cambio como deshecho. POST /history/{eventId}/redo revierte esa reversión. Ambos requieren Idempotency-Key y devuelven la reversión, el evento actualizado y qué se vio afectado.

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; un cambio reservado al owner (reset de mes, borrados) necesita un owner para revertirse.
  • Una API key necesita write:history Y el scope de escritura de los datos revertidos (write:budgets para presupuesto, write:transactions para una transacción, …).
  • La reversión se rechaza con 409 HISTORY_STALE cuando los datos ya no coinciden con el estado que el cambio registró; no se modifica nada.
  • Dos clientes compitiendo por el mismo undo: exactamente uno gana, el otro recibe 409 HISTORY_ALREADY_UNDONE.
  • Los rechazos de dominio pasan sin cambios, p. ej. INSUFFICIENT_CATEGORY_FUNDS cuando ya no es posible devolver el dinero.
  • Los cambios registrados con undoable=false (cerrar o conciliar una cuenta) se listan para revisión pero no se pueden revertir.

Códigos de error

  • HISTORY_STALE: la entidad cambió desde entonces; ver details.reason.
  • HISTORY_ALREADY_UNDONE: otro cliente lo revirtió antes.
  • HISTORY_NOT_UNDONE: se pidió rehacer un cambio que está en vigor.
  • HISTORY_NOT_UNDOABLE: registrado solo para revisión.
  • HISTORY_PARTIAL: una reversión de grupo aplicó unos miembros y rechazó otros; ver partial.failed.