Parcourir la référence

Reçus (OCR)

16 endpoints · Les descriptions des points de terminaison sont en anglais.

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

Paramètres

Nom	Emplacement	Requis	Description
cursor	query	Optionnel	-
limit	query	Optionnel	-
sort	query	Optionnel	date (default, paged) \| unitPrice \| total
transactionId	query	Optionnel	-
receiptId	query	Optionnel	-
dateTo	query	Optionnel	Purchase day, inclusive (YYYY-MM-DD)
dateFrom	query	Optionnel	Purchase day, inclusive (YYYY-MM-DD)
merchant	query	Optionnel	-
q	query	Optionnel	Matches product name, description and brand; terms are ANDed

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

Nom	Emplacement	Requis	Description
merchant	query	Optionnel	-
dateTo	query	Optionnel	-
dateFrom	query	Optionnel	-
bucket	query	Optionnel	month (default) \| week
q	query	Requis	Product to follow, e.g. "manzana"

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

Nom	Emplacement	Requis	Description
limit	query	Optionnel	-
sort	query	Optionnel	spend (default) \| unitPrice \| frequency \| name
dateTo	query	Optionnel	-
dateFrom	query	Optionnel	-
merchant	query	Optionnel	-
q	query	Optionnel	-

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

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

Exemple de requête

bash

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

Réponse200 · Success

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

POST/households/{householdId}/receipts

write:receipts

Exemple de requête

bash

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

Réponse201 · Success

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

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

read:receipts

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · Success

Soft-delete a receipt

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

write:receipts

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse204 · No content

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

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

write:receipts

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · Success

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

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

write:receipts

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · Success

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

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

write:receipts

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · Success

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

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

read:receipts

Paramètres

Nom	Emplacement	Requis	Description
receiptId	path	Requis	-
download	query	Optionnel	Set to 1 to receive an attachment instead of an inline image.

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

Nom	Emplacement	Requis
receiptId	path	Requis

Exemple de requête

bash

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

Réponse200 · Success

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

GET/households/{householdId}/receipts/counts

read:receipts

Exemple de requête

bash

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

Réponse200 · 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

Exemple de requête

bash

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

Réponse200 · 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

Paramètres

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

Exemple de requête

bash

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

Réponse200 · Success