BillOS v1
Console llms.txt OpenAPI

Expenses (ספר תקבולים ותשלומים)

The purchase side of the ledger: record supplier invoices/receipts so the business's books are complete:

# create-and-record in one call (or draft first with POST .../expenses, then .../record)
curl -X POST "$BASE/businesses/$BID/expenses/$EXP_ID/record" -H "X-Api-Key: $KEY" -H "Content-Type: application/json" -d '{}'

curl -X POST "$BASE/businesses/$BID/expenses" -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: supplier-inv-4471" -d '{
  "supplierName": "קוסמטיקס בע\"מ",
  "supplierTaxId": "514256461",
  "docType": 305, "docNumber": "4471",
  "documentDate": "2026-07-10",
  "amountIncVat": 82600, "vatAmount": 12600,
  "categoryKey": "supplies"
}'

Fields: supplierName* · amountIncVat* (agorot) · categoryKey* (your own category slug, e.g. supplies/rent/fuel) · supplierTaxId · docType/docNumber (the supplier's document) · documentDate, vatReportDate · vatAmount · taxDeductPct, vatDeductPct (deductibility %). *Required at record time.

Like documents: drafts (POST → PATCH) are mutable, POST .../record makes the row immutable with a gapless record number, and corrections go through POST .../expenses/:id/correction (a linked storno row that reverses it, per הוראה 23).

Read them back with:

# list, filterable: status=draft|recorded, categoryKey=, from=/to= (document date):
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/expenses?status=recorded&from=2026-07-01&to=2026-07-31"
# single expense (includes the raw OCR extraction when the row came from a scan):
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/expenses/$EXP_ID"

The list omits each row's raw ocr payload to stay light; GET .../expenses/:id includes it.

6.1 OCR: open an expense draft from a receipt photo

POST /businesses/:bid/expenses/ocr takes the raw bytes of a receipt photo or PDF, extracts the fields with AI vision, stores the file (scanned-original retention), and returns a draft expense pre-filled with the extraction:

curl -X POST "$BASE/businesses/$BID/expenses/ocr" -H "X-Api-Key: $KEY" \
  -H "Content-Type: image/jpeg" -H "Idempotency-Key: receipt-scan-991" \
  --data-binary @receipt.jpg
# 201 → {"ok":true,
#        "expense":{ "id":"...", "status":"draft", "supplierName":"...", "amountIncVat":8260, ... },
#        "extracted":{ ..., "confidence":"high", "notes":"" },
#        "fileId":"..." }
PreviousDocuments NextWebhooks