Explorar a referência

Recibos (OCR)

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

Line items read from receipts, newest purchase first; unit prices are also given per base unit (kg, l, unit).

GET/households/{householdId}/receipt-items

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
cursor	query	Opcional	-
limit	query	Opcional	-
sort	query	Opcional	date (default, paged) \| unitPrice \| total
transactionId	query	Opcional	-
receiptId	query	Opcional	-
dateTo	query	Opcional	Purchase day, inclusive (YYYY-MM-DD)
dateFrom	query	Opcional	Purchase day, inclusive (YYYY-MM-DD)
merchant	query	Opcional	-
q	query	Opcional	Matches product name, description and brand; terms are ANDed

Exemplo de pedido

bash

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

Resposta200 · Success

Unit price of a product over time (per base unit, quantity-weighted per bucket) with the merchants it was bought at.

GET/households/{householdId}/receipt-items/price-history

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
merchant	query	Opcional	-
dateTo	query	Opcional	-
dateFrom	query	Opcional	-
bucket	query	Opcional	month (default) \| week
q	query	Obrigatório	Product to follow, e.g. "manzana"

Exemplo de pedido

bash

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

Resposta200 · Success

Per-product summary across receipts: purchases, total spend, quantity-weighted average / min / max / latest unit price over the base unit, where it was bought.

GET/households/{householdId}/receipt-items/summary

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
limit	query	Opcional	-
sort	query	Opcional	spend (default) \| unitPrice \| frequency \| name
dateTo	query	Opcional	-
dateFrom	query	Opcional	-
merchant	query	Opcional	-
q	query	Opcional	-

Exemplo de pedido

bash

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

Resposta200 · Success

List receipts in this household; filter by link state, extraction status, kind, day, amount, merchant, tags or free text; sort by date, amount or merchant.

GET/households/{householdId}/receipts

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
cursor	query	Opcional	nextCursor of the previous page; only valid for the same sort and dateBasis
limit	query	Opcional	-
sort	query	Opcional	date_desc (default) \| date_asc \| amount_desc \| amount_asc \| merchant_asc; dates follow dateBasis, ties break on id, receipts without a total or merchant come last
inboxOnly	query	Opcional	true = not yet linked to a transaction
linked	query	Opcional	true = linked to a transaction, false = still in the tray
transactionId	query	Opcional	-
status	query	Opcional	Comma-separated: pending, processing, extracted, failed
kind	query	Opcional	receipt \| invoice \| product \| other
q	query	Opcional	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Opcional	Which day the date filters and sorts use: receipt (default; the day printed on it, the upload day until it is read) or upload
dateFrom	query	Opcional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Opcional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Opcional	Inclusive lower bound on the read total, integer cents
amountMax	query	Opcional	Inclusive upper bound on the read total, integer cents
merchant	query	Opcional	Comma-separated merchant keys (from the facets); any of them
tag	query	Opcional	Comma-separated tags; all of them

Exemplo de pedido

bash

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

Resposta200 · Success

Upload a receipt image (multipart/form-data); optionally attach it to a transaction

POST/households/{householdId}/receipts

write:receipts

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X POST https://api.vokse.ai/households/current/receipts \     -F "file=@receipt.jpg"

Resposta201 · Success

Get a receipt: extraction, normalised line items and pre-signed URLs (300s TTL) for the image.

GET/households/{householdId}/receipts/{receiptId}

read:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	path	Obrigatório

Exemplo de pedido

bash

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

Resposta200 · Success

Correct what was read (ADR 0111): merchant, date, total, currency, kind, tags, summary merge; items replace. A failed receipt becomes usable this way.

PATCH/households/{householdId}/receipts/{receiptId}

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	path	Obrigatório

Exemplo de pedido

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Idempotency-Key: $(uuidgen)" \     -X PATCH https://api.vokse.ai/households/current/receipts/{receiptId}

Resposta200 · Success

Soft-delete a receipt

DELETE/households/{householdId}/receipts/{receiptId}

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	path	Obrigatório

Exemplo de pedido

bash

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

Resposta204 · No content

Attach an unlinked receipt to an existing transaction (ADR 0108)

POST/households/{householdId}/receipts/{receiptId}/attach

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	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/receipts/{receiptId}/attach

Resposta200 · Success

Materialise the receipt into a Transaction. Body fields override the extraction.

POST/households/{householdId}/receipts/{receiptId}/confirm

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	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/receipts/{receiptId}/confirm

Resposta200 · Success

Detach a receipt from its transaction; it returns to the tray (ADR 0108)

POST/households/{householdId}/receipts/{receiptId}/detach

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	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/receipts/{receiptId}/detach

Resposta200 · Success

The receipt image, served inline (or as a download with ?download=1).

GET/households/{householdId}/receipts/{receiptId}/file

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
receiptId	path	Obrigatório	-
download	query	Opcional	Set to 1 to receive an attachment instead of an inline image.

Exemplo de pedido

bash

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

Resposta200 · Success

Read the receipt again (failed or extracted, attached or not). 409 while a read is in progress, or over a manual correction unless force=true. Returns the receipt with status="pending".

POST/households/{householdId}/receipts/{receiptId}/retry

write:receipts

Parâmetros

Nome	Local	Obrigatório
receiptId	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/receipts/{receiptId}/retry

Resposta200 · Success

How many receipts are unlinked, still being read, or failed (for the receipts page header).

GET/households/{householdId}/receipts/counts

read:receipts

Exemplo de pedido

bash

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

Resposta200 · Success

Empty the tray: soft-delete every receipt not linked to a transaction. Returns how many were deleted.

POST/households/{householdId}/receipts/empty-tray

write:receipts

Exemplo de pedido

bash

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

Resposta200 · Success

Facets of the receipts matching the same filters as the list: total, per-month counts and sums (on dateBasis), top merchants, top tags, status and link split.

GET/households/{householdId}/receipts/facets

read:receipts

Parâmetros

Nome	Local	Obrigatório	Descrição
inboxOnly	query	Opcional	true = not yet linked to a transaction
linked	query	Opcional	true = linked to a transaction, false = still in the tray
transactionId	query	Opcional	-
status	query	Opcional	Comma-separated: pending, processing, extracted, failed
kind	query	Opcional	receipt \| invoice \| product \| other
q	query	Opcional	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Opcional	Which day the date filters and sorts use: receipt (default; the day printed on it, the upload day until it is read) or upload
dateFrom	query	Opcional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Opcional	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Opcional	Inclusive lower bound on the read total, integer cents
amountMax	query	Opcional	Inclusive upper bound on the read total, integer cents
merchant	query	Opcional	Comma-separated merchant keys (from the facets); any of them
tag	query	Opcional	Comma-separated tags; all of them

Exemplo de pedido

bash

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

Resposta200 · Success