Explorar a referência

Movimentos

20 endpoints · As descrições dos endpoints estão em inglês.

List transactions, newest date first (date DESC, id DESC), with cursor pagination and filters

GET/households/{householdId}/transactions

read:transactions

Parâmetros

Nome	Local	Obrigatório	Descrição
limit	query	Opcional	1..100, default 50
cursor	query	Opcional	Opaque cursor from the previous page (nextCursor)
maxAmountCents	query	Opcional	Cents
minAmountCents	query	Opcional	Cents
search	query	Opcional	-
dateTo	query	Opcional	YYYY-MM-DD
dateFrom	query	Opcional	YYYY-MM-DD
source	query	Opcional	-
statuses	query	Opcional	Comma-separated statuses (any-of); supersedes `status` when both are sent
status	query	Opcional	-
attention	query	Opcional	Rows waiting on the user: needs-review, plus actionable uncategorized outflows that are not reconciled (the account attention count’s predicate)
uncategorized	query	Opcional	Only rows in the budget’s uncategorized bucket: bare outflows on on-budget accounts (cleared or reconciled), never transfer legs or system rows
needsReview	query	Opcional	true = rows awaiting a category decision, false = the rest
hasFlag	query	Opcional	Only transactions that carry a flag
flagIds	query	Opcional	Comma-separated flag ULIDs (any-of), max 20
hasTag	query	Opcional	-
tagMode	query	Opcional	-
tagIds	query	Opcional	Comma-separated tag ULIDs, max 20
tagId	query	Opcional	-
payeeId	query	Opcional	-
categoryId	query	Opcional	-
accountId	query	Opcional	-

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions

Resposta200 · Success

Create a transaction (with optional splits and tags)

POST/households/{householdId}/transactions

write:transactions

Corpo do pedido

json

{  "accountId": "01J8ME9AZ2K3W7X4V5T6R7Q8S9",  "date": "2026-06-22",  "amountCents": -4250,  "currency": "EUR",  "payeeName": "Local supermarket",  "categoryId": "01J8ME9B7QW3ZK5X2V8T4R6S1D",  "memo": "Weekly groceries"}

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions \     -d '{"accountId":"01J8ME9AZ2K3W7X4V5T6R7Q8S9","date":"2026-06-22","amountCents":-4250,"currency":"EUR","payeeName":"Local supermarket","categoryId":"01J8ME9B7QW3ZK5X2V8T4R6S1D","memo":"Weekly groceries"}'

Resposta201 · Success

Get one transaction with its splits

GET/households/{householdId}/transactions/{transactionId}

read:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}

Resposta200 · Success

Update a transaction (replaces splits and tagIds when provided)

PATCH/households/{householdId}/transactions/{transactionId}

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Corpo do pedido

json

{  "categoryId": "01J8ME9B7QW3ZK5X2V8T4R6S1D",  "status": "cleared"}

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/transactions/{transactionId} \     -d '{"categoryId":"01J8ME9B7QW3ZK5X2V8T4R6S1D","status":"cleared"}'

Resposta200 · Success

Soft-delete a transaction

DELETE/households/{householdId}/transactions/{transactionId}

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/transactions/{transactionId}

Resposta204 · No content

Accept the AI-suggested category and clear the suggestion fields. The accepted row becomes ground truth for future kNN predictions.

POST/households/{householdId}/transactions/{transactionId}/accept-suggestion

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/accept-suggestion

Resposta200 · Success

"Not a duplicate": clear the possible-duplicate flag an ambiguous auto-match left on a bank import.

POST/households/{householdId}/transactions/{transactionId}/dismiss-match

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/dismiss-match

Resposta200 · Success

Link this transaction and a counterpart as the two legs of one transfer. The budget engine then recognises card payments through the shared group (ADR 0099).

POST/households/{householdId}/transactions/{transactionId}/link-transfer

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/link-transfer

Resposta200 · Success

Merge a bank import with the hand-entered row it duplicates: the hand-entered row survives (payee, category, memo, tags, splits) and takes the bank date; the bank row is folded into it. Undoable (ADR 0105).

POST/households/{householdId}/transactions/{transactionId}/match

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/match

Resposta200 · Success

Rows this transaction could be merged with as the same purchase: a bank import lists hand-entered twins, a hand-entered row lists bank twins (same account, amount and currency, within 7 days; ADR 0105)

GET/households/{householdId}/transactions/{transactionId}/match-candidates

read:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}/match-candidates

Resposta200 · Success

Reject the AI-suggested category. The row stays uncategorized.

POST/households/{householdId}/transactions/{transactionId}/reject-suggestion

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/reject-suggestion

Resposta200 · Success

Remove a single tag from a transaction

DELETE/households/{householdId}/transactions/{transactionId}/tags/{tagId}

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório
tagId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X DELETE https://api.vokse.ai/households/current/transactions/{transactionId}/tags/{tagId}

Resposta204 · No content

Counterpart rows this transaction could be linked to as one transfer: exact opposite amount, same currency, another account, within 7 days (ADR 0099)

GET/households/{householdId}/transactions/{transactionId}/transfer-candidates

read:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/{transactionId}/transfer-candidates

Resposta200 · Success

Unlink a two-leg transfer: both legs keep payee and category but drop the shared group. Forbidden while a leg is reconciled.

POST/households/{householdId}/transactions/{transactionId}/unlink-transfer

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/unlink-transfer

Resposta200 · Success

Separate a merged pair again: the bank import comes back as its own row and the hand-entered row gets its previous date and status. Forbidden while reconciled.

POST/households/{householdId}/transactions/{transactionId}/unmatch

write:transactions

Parâmetros

Nome	Local	Obrigatório
transactionId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/{transactionId}/unmatch

Resposta200 · Success

Bulk-create transactions (up to 500 in one shot)

POST/households/{householdId}/transactions/bulk

write:transactions

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/bulk

Resposta201 · Success

Bulk-update a subset of transactions with the same patch

PATCH/households/{householdId}/transactions/bulk-update

write:transactions

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/transactions/bulk-update

Resposta200 · Success

Per-day money in, money out and count for a window of up to 92 days (the calendar): converted to the base currency, plus the face-value totals per currency

GET/households/{householdId}/transactions/daily-summary

read:transactions

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/daily-summary

Resposta200 · Success

How many hand-entered rows are still pending at least N days after their date on bank-fed accounts (the stale pending sweep, ADR 0105)

GET/households/{householdId}/transactions/stale-pending-count

read:transactions

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -X GET https://api.vokse.ai/households/current/transactions/stale-pending-count

Resposta200 · Success

Create a double-entry transfer between two accounts (both legs share a transfer group)

POST/households/{householdId}/transactions/transfer

write:transactions

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/transactions/transfer

Resposta201 · Success