POST/businesses/{bid}/documents/{id}/validate

Check a draft without issuing it

POST /businesses/{bid}/documents/{id}/validate

Requires the documents scope.

A dry run of issue. Runs every check issuing runs (account standing, the dealer type, totals, payments against the total, the allocation-number rule, the exchange rate, what a receipt settles) and stops before the first write: no number is taken, nothing is signed, the draft is unchanged. Answers what the issued document would be, or the exact refusal issuing would give, with its hint and param.

Call it before issue whenever the caller cannot afford a permanent mistake: an issued document is corrected only by a credit note.

Path parameters

Name	Type		Description
`bid`	string	required	Business id, from `POST /businesses`.
`id`	string	required	Document id.

Body (optional)

Field	Type		Description
`branding`	Branding		Appearance of the rendered PDF. Stored once per business; a logo is stored as a file and referenced by hash, never re-frozen into each document.

Response

200: { "ok": true, … }

Field	Type		Description
`ok`	boolean	required
`valid`	boolean	required
`wouldIssue`	object	required	The figures the issued document would carry.
`wouldIssue.docType`	integer		Document type code.
`wouldIssue.currency`	string		ISO currency of the document.
`wouldIssue.totalExVat`	integer		Total before VAT, as the ledger would record it. Integer agorot (₪1 = 100).
`wouldIssue.vatAmount`	integer		VAT. Integer agorot (₪1 = 100).
`wouldIssue.totalIncVat`	integer		Total including VAT. Integer agorot (₪1 = 100).
`wouldIssue.fxRate`	number		On a foreign-currency document: the rate that would be used (ILS per 1 unit).
`wouldIssue.fxTotalIncVat`	integer		On a foreign-currency document: the total in that currency's minor unit.
`wouldIssue.allocation`	string		Whether an allocation number (מספר הקצאה) is in play. One of: `not_required`, `will_be_requested`, `missing`.
`warnings`	array of string		What issue would warn about (`allocation_missing`, `check_details_missing`, `unsigned`).

Errors: 400, 401, 403, 404, 409, 422, 429. Every failure answers { "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }: branch on reason, and read hint for what to change (https://docs.billos.co.il/errors.md).

const res = await fetch(`${BASE}/businesses/${BID}/documents/${DOC_ID}/validate`, { method: 'POST', headers: { 'X-Api-Key': KEY, }, }) const data = await res.json() if (!data.ok) throw new Error(data.reason)