Scan receipt (OCR)
Expenses
Scan receipt (OCR)
Upload a receipt or invoice image and get a structured prefill payload ready to feed into Create Expense.
POST
Scan receipt (OCR)
Overview
Send a photo of a Romanian receipt (bon fiscal), chitanță, or supplier invoice and receive a structured prefill payload describing the document — supplier match, dates, totals, per-rate VAT breakdown, optionally per-line items, and a payment-method hint. Use the response to prefill an expense form. Persist viaPOST /expenses once the user confirms — typically with vat = "mix" + amount_vat_manual for receipts flagged as multi-rate.
Request
Content-Type: multipart/form-data
Receipt image — JPEG, PNG, or WebP, up to 10 MB. Mobile clients should compress to JPEG before upload (HEIC is rejected).
Response (200)
The response is a normalized prefill payload, not a stored expense. Persist it viaPOST /expenses once the user confirms.
Opaque token referencing the uploaded image staged on the server. Pass this to the attachment endpoint when posting the expense so the same image gets attached without a re-upload. Expires after 15 minutes.
Resolved supplier match.
id— CzUid of an existing supplier matched by CUI/name, ornullfor a new auto-created onename,cui— best-effort values from the receiptmatchedExisting—truewhen an existing supplier was found
Fuzzy-matched category from the firm’s list (system + custom merged):
{ id, name }. Both may be null when no match is found.Issue date in
YYYY-MM-DD. Falls back to today if unreadable.Due date in
YYYY-MM-DD, or null for receipts paid at the point of sale (bon fiscal). When null, the form should auto-mark the expense as paid with paid_date = date and payment_type derived from paymentMethod (or 1 = Cash as fallback).3-letter ISO code (RON, EUR, USD).
Net subtotal (excluding VAT). On the flat path this is what the user enters in the “Valoarea” field with
with_vat = false.Dominant VAT percent. Rounded to one of the Romanian rates. On
vatMode = "mix", this is informational only — use amount_vat_manual instead.Total VAT amount across all rate tranches. On
vatMode = "mix", send this back as amount_vat_manual when posting the expense."flat" (single rate, send vat = <number>) or "mix" (two or more non-zero rate tranches, send vat = "mix" + amount_vat_manual = vatAmount).Gross total printed on the receipt. Always equal to
amount + vatAmount on the mix path.true when only the gross total was printed (typical bon fiscal). On mix mode this is false because amount is the explicit subtotal.Per-rate breakdown when the receipt mixes more than one rate, otherwise
null. Each entry: { rate, net, gross, vatAmount } — any of net / gross may be null.On vatMode = "mix", send this array back via vat_breakdown when posting so reports keep accurate per-rate totals.Payment method inferred from the document footer. One of
"cash", "card", "transfer", "other", or null (typical for factură furnizor printed before payment). Map to payment_type when posting:cash→1(Cash, “Numerar prin bon fiscal”)card→4(Card)transfer→3(Bank transfer / Ordin de plată)other/null→ caller decides
Document / receipt / invoice number (
reference in the create payload).Free-text description, often
null.Optional. When present, each entry has
name, quantity, unit_price (NET), vat_rate. May be absent depending on document quality and structure — clients that ignore this field still get correct totals via the aggregate fields.Pre-localized Romanian strings safe to surface in the form alert. Examples:
"Furnizor nou"— supplier auto-created"Mai multe cote TVA"— multi-rate detected, switch UI to mix mode"Liniile au fost ignorate ..."— items omitted; rely on the aggregate fields
Mapping the response to Create Expense
amount_wvat = 147.53, amount_vat = 24.15, amount_total = 171.68 exactly.
Errors
- 400
file_missing— noimagepart in the multipart body - 400
invalid_file_type— unsupported extension (must be jpg/jpeg/png/webp) - 400
invalid_mime_type— content sniff didn’t match an accepted image MIME - 400
file_too_large— file exceeds 10 MB - 502
ocr_unavailable— extraction failed; safe to retry - 503
ocr_not_configured— OCR is not enabled on this deployment
Authorizations
Use your API key (sk_live_xxx or sk_test_xxx)
Body
multipart/form-data
Receipt image (JPEG / PNG / WebP, ≤ 10 MB).
Response
Extracted prefill payload
Normalized prefill returned by POST /expenses/ocr-extract. Map to a Create Expense body — see the OCR endpoint guide for the full translation table.
Opaque 15-min token for the staged image; pass through to attachments.
Net subtotal (excluding VAT).
Dominant VAT rate.
Total VAT across all rate tranches.
"flat" = single rate; send vat = <number> on POST.
"mix" = two or more non-zero rate tranches; send vat = "mix"
+ amount_vat_manual = vatAmount on POST.
Available options:
flat, mix Gross total printed on the receipt.
Inferred payment method. Map to payment_type on POST:
cash→1, card→4, transfer→3, other/null→caller decides.
Available options:
cash, card, transfer, other, null Optional. May be absent depending on document quality and structure. Clients that ignore this field still get correct totals via the aggregate fields.
Pre-localized Romanian strings safe to surface in the form alert.