POST/businesses/{bid}/documents

Create a draft

POST /businesses/{bid}/documents

Requires the documents scope.

A draft is a קובץ זמני, not a tax document: no number is consumed and any rendering of it is watermarked "טיוטה". Patch and delete it freely until you issue.

Always send an idempotency key. A double-click or a network retry then returns the same draft with deduped: true instead of opening a second one.

Path parameters

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

Headers

Name	Type		Description
`Idempotency-Key`	string		Your own stable id for this call. A retry returns the same row with `deduped: true` instead of creating a duplicate. Interchangeable with `externalRef` in the body.

Body

Field	Type		Description
`docType`	integer	required	305 / 320 / 400. A 330 is created only through the credit-note endpoint. One of: `305`, `320`, `400`.
`party`	object		`{partyId}` to reference a saved party, or an inline `{name, taxId?, phone?, email?, address?}`. Omit entirely for an anonymous cash receipt.
`party.partyId`	string
`party.name`	string
`party.taxId`	string
`party.phone`	string
`party.email`	string
`party.address`	string
`priceMode`	string		`net` (the default: line prices are ex-VAT) or `gross` (line prices include VAT; the total anchors to the gross sum and VAT is derived). Gross is what a consumer-facing price list wants. One of: `net`, `gross`. Default `net`.
`lines`	array of DocumentLine		Required for 305/320.
`payments`	array of Payment		Required for 320/400.
`note`	string		≤500 chars.
`documentDate`	string		Defaults to today, Asia/Jerusalem.
`valueDate`	string		Defaults to today.
`discountAmount`	integer		Document-level discount. Integer agorot (₪1 = 100).
`withholdingAmount`	integer		ניכוי במקור. Integer agorot (₪1 = 100).
`allocationNumber`	string		מספר הקצאה, when you already hold one.
`externalRef`	string		Idempotency key, interchangeable with the `Idempotency-Key` header.

Response

201: { "ok": true, … }

Field	Type		Description
`ok`	boolean	required
`document`	Document	required	A draft is freely mutable. An issued document is immutable forever, blocked at the database engine, not merely in application code.
`deduped`	boolean		Present and true when this call matched an earlier one.

Errors: 400, 401, 403, 404, 429. Every failure answers { "error": …, "reason": … }. Branch on reason.

curl -X POST "$BASE/businesses/$BID/documents" \ -H "X-Api-Key: $KEY" \ -H "Content-Type: application/json" \ -d '{ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 190000 } ], "externalRef": "order-8812" }'

const res = await fetch(`${BASE}/businesses/${BID}/documents`, { method: 'POST', headers: { 'X-Api-Key': KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 190000 } ], "externalRef": "order-8812" }), }) const data = await res.json() if (!data.ok) throw new Error(data.reason)

import requests res = requests.post( f"{BASE}/businesses/{BID}/documents", headers={"X-Api-Key": KEY}, json={ "docType": 320, "party": { "name": "דנה לוי", "taxId": "514667426", "phone": "0521111111", "email": "dana@example.com", "address": "הרצל 12, תל אביב" }, "priceMode": "gross", "lines": [ { "description": "איפור כלה", "quantity": 1, "unitPriceExVat": 120000 } ], "payments": [ { "method": 3, "amount": 190000 } ], "externalRef": "order-8812" }, ) data = res.json()