Regulatory outputs

Your end users (or their accountants) will eventually need these; each returns or references downloadable files served at GET /businesses/:bid/files/:id.

# OPENFRMT (מבנה אחיד) export for a date range: what an accountant/auditor asks for:
curl -X POST "$BASE/businesses/$BID/exports/openfrmt" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"from":"2026-01-01","to":"2026-06-30"}'
# 201 → {"ok":true, "exportRun":{...verification summary...}, "file":{"id":"...","size":...}}
#       one zip (INI.TXT + BKMVDATA under the spec's directory tree), downloaded via /files/:id

# numbering-continuity report (gap check) per document type:
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/continuity?docType=320"

# management reports: הכנסות / הוצאות / רווח והפסד. Default = a rendered Hebrew PDF;
# ?format=json returns the aggregates for your own dashboard. Cash-basis, mirroring the
# OPENFRMT semantics exactly (income = payment-bearing documents; expenses at record):
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/incomes?from=2026-01-01&to=2026-06-30" -o incomes.pdf
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/expenses?from=2026-01-01&to=2026-06-30&format=json"
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/profit?from=2026-01-01&to=2026-06-30" -o profit.pdf
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/full?from=2026-01-01&to=2026-06-30&format=xlsx" -o accountant.xlsx
# profit includes a VAT block (עסקאות / תשומות / נטו) for VAT-registered dealers.
# The rendered PDF picks up the business branding (logo / accent color / footer), same as documents (§4).
# These are management reports; the regulatory filing artifact remains the OPENFRMT export.

# initiated backup (גיבוי יזום):
curl -X POST "$BASE/businesses/$BID/backup" -H "X-Api-Key: $KEY"

# download any produced file:
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/files/$FILE_ID" -o export.zip

These need the export scope.

7.1 The detailed VAT return: POST /businesses/:bid/exports/pcn874

The file a dealer uploads to the Tax Authority with the periodic VAT return (דיווח מפורט, PCN874). Since January 2026 it is mandatory from ₪500,000 of yearly turnover, which is most businesses on BillOS.

# the figures first (nothing written): the four numbers of the return, every entry, the warnings
curl -H "X-Api-Key: $KEY" "$BASE/businesses/$BID/reports/vat?period=2026-08"
# the file: PCN874.TXT as a BkFile, plus an export run carrying the same summary
curl -X POST "$BASE/businesses/$BID/exports/pcn874" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"period":"2026-08","months":1}'
# 201 → { exportRun, file: { id }, totals: { taxableSales, salesVat, exemptSales, otherInputsVat, equipmentInputsVat, vatToPay }, warnings }

period is the reporting month; a bi-monthly filer passes the LAST month of the period with "months": 2. Built from the ledger alone, per שע"ם's specification for software houses: every issued חשבונית מס, חשבונית מס-קבלה and חשבונית זיכוי in the period is a sales entry (identified customers one each, type S; customers with no ת.ז/ח.פ summed into one L entry per month, which the spec allows under ₪5,000 before VAT; a zero-VAT sale to a foreign customer is an export Y); every recorded expense carrying VAT is an input entry with the VAT allowed (vatDeductPct), identified suppliers one each (T), the rest summed as petty cash (K). Equipment (categoryKey equipment / asset) fills the equipment column. A proforma or a receipt never appears: neither is a VAT document. Amounts are whole shekels, a credit note carries a minus sign, dates are YYYYMMDD, lines end in CRLF, exactly the widths the spec fixes.

The warnings are what the Authority's own validator would reject or question: a customer or supplier id that fails the check digit, a supplier number that is the business's own (input VAT on your own invoice is refused at the intake, and one such row can fail the whole return), a sale over ₪5,000 to an unidentified customer, a supplier invoice with no number, petty cash over the 2% / ₪2,000 limit. Fix the rows and regenerate; the file is not signed and carries no state.

The header's four figures are summed from the entries' own rounded shekels, so the details always reconcile with the header exactly: the Authority's intake divides one by the other and reports the quotient as an acceptance percentage.