Sfoglia il riferimento

Scontrini (OCR)

16 endpoint · Le descrizioni degli endpoint sono in inglese.

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

Parametri

Nome	Posizione	Obbligatorio	Descrizione
cursor	query	Facoltativo	-
limit	query	Facoltativo	-
sort	query	Facoltativo	date (default, paged) \| unitPrice \| total
transactionId	query	Facoltativo	-
receiptId	query	Facoltativo	-
dateTo	query	Facoltativo	Purchase day, inclusive (YYYY-MM-DD)
dateFrom	query	Facoltativo	Purchase day, inclusive (YYYY-MM-DD)
merchant	query	Facoltativo	-
q	query	Facoltativo	Matches product name, description and brand; terms are ANDed

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio	Descrizione
merchant	query	Facoltativo	-
dateTo	query	Facoltativo	-
dateFrom	query	Facoltativo	-
bucket	query	Facoltativo	month (default) \| week
q	query	Obbligatorio	Product to follow, e.g. "manzana"

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio	Descrizione
limit	query	Facoltativo	-
sort	query	Facoltativo	spend (default) \| unitPrice \| frequency \| name
dateTo	query	Facoltativo	-
dateFrom	query	Facoltativo	-
merchant	query	Facoltativo	-
q	query	Facoltativo	-

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio	Descrizione
cursor	query	Facoltativo	nextCursor of the previous page; only valid for the same sort and dateBasis
limit	query	Facoltativo	-
sort	query	Facoltativo	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	Facoltativo	true = not yet linked to a transaction
linked	query	Facoltativo	true = linked to a transaction, false = still in the tray
transactionId	query	Facoltativo	-
status	query	Facoltativo	Comma-separated: pending, processing, extracted, failed
kind	query	Facoltativo	receipt \| invoice \| product \| other
q	query	Facoltativo	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Facoltativo	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	Facoltativo	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Facoltativo	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Facoltativo	Inclusive lower bound on the read total, integer cents
amountMax	query	Facoltativo	Inclusive upper bound on the read total, integer cents
merchant	query	Facoltativo	Comma-separated merchant keys (from the facets); any of them
tag	query	Facoltativo	Comma-separated tags; all of them

Richiesta di esempio

bash

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

Risposta200 · Success

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

POST/households/{householdId}/receipts

write:receipts

Richiesta di esempio

bash

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

Risposta201 · Success

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

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

read:receipts

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · Success

Soft-delete a receipt

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

write:receipts

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta204 · No content

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

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

write:receipts

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · Success

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

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

write:receipts

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · Success

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

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

write:receipts

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · Success

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

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

read:receipts

Parametri

Nome	Posizione	Obbligatorio	Descrizione
receiptId	path	Obbligatorio	-
download	query	Facoltativo	Set to 1 to receive an attachment instead of an inline image.

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio
receiptId	path	Obbligatorio

Richiesta di esempio

bash

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

Risposta200 · Success

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

GET/households/{householdId}/receipts/counts

read:receipts

Richiesta di esempio

bash

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

Risposta200 · 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

Richiesta di esempio

bash

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

Risposta200 · 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

Parametri

Nome	Posizione	Obbligatorio	Descrizione
inboxOnly	query	Facoltativo	true = not yet linked to a transaction
linked	query	Facoltativo	true = linked to a transaction, false = still in the tray
transactionId	query	Facoltativo	-
status	query	Facoltativo	Comma-separated: pending, processing, extracted, failed
kind	query	Facoltativo	receipt \| invoice \| product \| other
q	query	Facoltativo	Free text over what was read (merchant, items, tags, summary); terms are ANDed
dateBasis	query	Facoltativo	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	Facoltativo	Inclusive (YYYY-MM-DD) on the chosen dateBasis
dateTo	query	Facoltativo	Inclusive (YYYY-MM-DD) on the chosen dateBasis
amountMin	query	Facoltativo	Inclusive lower bound on the read total, integer cents
amountMax	query	Facoltativo	Inclusive upper bound on the read total, integer cents
merchant	query	Facoltativo	Comma-separated merchant keys (from the facets); any of them
tag	query	Facoltativo	Comma-separated tags; all of them

Richiesta di esempio

bash

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

Risposta200 · Success