Create and issue a document in one call

Creates a draft and finalizes it in a single request — the one-call issuance surface for API customers (the dashboard/bot two-step draft→finalize flow is unchanged). The body is everything POST /documents accepts, plus:

reference — optional caller idempotency key, scoped to YOUR business (stored namespaced internally). Callers may reuse the same reference across different businesses without colliding. A repeat request with the same reference for this business returns the already-issued document with created:false and HTTP 200 (a first issuance returns HTTP 201). While a same-reference request is still being issued concurrently, a competing request gets HTTP 409 reference_in_progress (retry shortly) or, in a narrow race, reference_conflict (retry to receive the issued document) — never a duplicate document.
waitForPdf (default true) — hold the response for a bounded ~8s window until the PDF has rendered (pdfStatus:"completed"); on timeout the document is still issued and pdfUrl is still the stable address (pdfStatus:"processing"). A pdfStatus:"failed" render can be re-requested later at the same pdfUrl.

On finalize failure the just-created draft is removed (no orphan draft) and the original error is returned unchanged — e.g. an unconnected business issuing a B2B document above the SHAAM allocation threshold gets ALLOCATION_CONNECTION_REQUIRED exactly as in the two-call flow.

Authorization

X-Api-Key<token>

Business API key, e.g. vuz_ab12cdef... Created via Settings → Integrations → API Keys. Unlike partner keys, a public API key's STRING does not encode its environment — isolation instead comes from a completely separate sandbox database: a key minted on the Sandbox server (above) only ever reads/writes sandbox data and can never see or affect production, regardless of what the key looks like.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

businessId*string

Business ID (multi-tenant scoping). Document belongs to this business.

Formatuuid

brandId?|

Brand (שם מסחרי) id this document is issued under. Drives the document identity + design (name/logo/colors/template) at finalization — never the document number (numbering stays business-scoped → one continuous series across brands). Omit to use the business default brand.

Formatuuid

clientId?|

Client ID (UUID). Optional - can provide clientName instead for auto-creation.

Client Lookup Flow:

If clientId is provided → use existing client
If only clientName is provided → create new client with that name
At least one of clientId or clientName must be provided

Formatuuid

supplierId?|

Supplier ID (UUID) for PURCHASE-side documents (W3.2 — e.g. PURCHASE_ORDER). When set, the document is addressed to this supplier instead of a client; the supplier name is snapshotted and a PO lifecycle status (poStatus) is initialized. Leave unset for all sales documents.

Formatuuid

clientName?|

Client name for auto-creation. If provided without clientId, a new client will be created.

Auto-Creation Behavior:

Creates new client with type=PRIVATE by default
Client will be linked to the specified businessId
Useful for quick document creation without pre-creating clients

Lengthlength <= 100

client?

Full inline client details for auto-creation (public-API convenience).

Client Lookup Flow (extended):

If clientId is provided → use existing client (client/clientName ignored)
Else if client is provided → create a new client with these details (name, type, email, phone, vatNumber, address)
Else if only clientName is provided → create new client with just that name (legacy behavior, unchanged)
At least one of clientId, clientName, or client.name must be provided

branchId?|

Client branch ID (UUID). Optional - when provided, the branch address and VAT number will override the client's default values on the document. Used for franchise clients with multiple locations.

Formatuuid

clientDisplayName?|

Custom display name for client (overrides clientName on documents). Useful when client wants a different name on the invoice.

Lengthlength <= 500

docType*string

Document type determines tax treatment, numbering, and validation rules.

Value in

"order"
"delivery_note"
"agent_delivery_note"
"return_note"
"tax_invoice"
"consolidated_invoice"
"tax_invoice_receipt"
"credit_note"
"reservation_invoice"
"agent_invoice"
"receipt"
"donation_receipt"
"cash_withdrawal"
"bank_deposit"
"purchase_order"
"purchase_delivery_note"
"purchase_return"
"purchase_tax_invoice"
"purchase_credit_note"
"opening_balance"
"inventory_in"
"inventory_out"
"warehouse_transfer"
"inventory_adjustment"
"production_in"
"production_out"
"quote"
"deal_bill"
"work_order"

issueDate*string

Issue date (YYYY-MM-DD, תאריך הנפקה — placeholder at draft stage). Two-date model (dev_features/2026-07-05-document-date-two-field-model): at FINALIZE time this is ALWAYS forced to today (Israel calendar day) regardless of what is stored here — never user-editable at that point. While the document remains a DRAFT this value is a placeholder only; the real, user-facing fiscal date is documentDate below (defaults to this value when omitted).

Formatdate

documentDate?|

Fiscal date (YYYY-MM-DD, תאריך המסמך) — the date the customer/PDF/lists see, and the date fiscal-period logic (VAT reports, ledger) anchors to. Two-date model (dev_features/2026-07-05- document-date-two-field-model). Defaults to issueDate when omitted. Validated against issueDate (documentDate <= issueDate, >= issueDate - 60 days, same calendar/tax year) — see validateDocumentDate (documents/utils/sequenced-doc-types.util.ts). Re-validated (and, if backdated, gated behind an accountant-acknowledgment flag) at finalize — see FinalizeDocumentDto.documentDate/backdateAck.

Formatdate

backdateAck?boolean

Accountant-acknowledgment flag (two-date model, dev_features/2026-07-05-document-date- two-field-model). Required (must be true) whenever the resolved documentDate is TIER 2 — strictly earlier than the last ISSUED document of the same type (see validateDocumentDate in documents/utils/sequenced-doc-types.util.ts). Threaded through create()/update() so saving/editing a DRAFT with a Tier-2 documentDate does not throw before the user has had a chance to tick the accountant-consultation checkbox in the UI — the SAME flag is re-supplied (and re-validated) at finalize (FinalizeDocumentDto.backdateAck), where it is actually persisted to the audit columns (backdateAckAt/backdateAckByUserId). A draft save/update never stamps those columns itself — only finalize does, since only an ISSUED document's backdating is a fact worth auditing.

Defaultfalse

dueDate?|

Due date for payment (YYYY-MM-DD). If provided, this explicit caller value always wins. If omitted, the server computes it from the resolved payment terms (paymentTermsId, or the client's effective terms, or the business default — every business gets a default term after Workstream D's seeding) via PaymentTerms.calculateDueDate(documentDate) — the fiscal anchor, not issueDate (two-date model Decision #5). Falls back to +30 days only when no payment terms could be resolved at all.

Formatdate

paymentTermsId?|

Payment terms ID (UUID, references payment_terms). Optional.

Resolution Flow:

If provided → used directly (must belong to this business).
If omitted → resolved automatically: the client's effective payment terms (client override via client_settings.paymentTermsId, else the business default isDefault=true term) via ClientSettingsService.getEffectivePaymentTerms.
The resolved term's name is snapshotted onto the document (paymentTermsText) and used to compute dueDate (unless dueDate was explicitly provided above).

Formatuuid

currency?string

Currency code (ISO 4217). Defaults to business default currency.

Default"ILS"

Value in

"ILS"
"USD"
"EUR"

fxRate?|

Foreign exchange rate (if currency is not base currency). Used for reporting.

Range0.0001 <= value

vatMode?string

VAT mode: exclusive (VAT added), inclusive (VAT included), or none (no VAT)

Default"exclusive"

Value in

"exclusive"
"inclusive"
"none"
"zero_rated"

vatRate?|

Custom VAT rate for this document as percentage (e.g., 18 for 18%, 17 for 17%). If not provided, the rate is calculated based on client type:

OSEK_PATUR / FOREIGN clients: 0%
All other clients: Current legal rate (18%)

Range0 <= value <= 100

items?array<>

Line items for this document. Required for all documents except invoice-linked receipts (items will be auto-copied from invoice).

Items1 <= items

notes?|

Additional notes (Hebrew or English, rich HTML). Visible on printed document.

Lengthlength <= 10000

originalDocumentId?|

Reference to original document ID (required for credit notes)

Formatuuid

parentDocumentId?|

Reference to parent document ID (for invoice-linked receipts)

Formatuuid

origin?string

Origin of document creation (web, api, whatsapp, mobile, import, system). Defaults to "web".

Default"web"

Value in

"web"
"api"
"whatsapp"
"telegram"
"mobile"
"import"
"system"
"woocommerce"
"mcp"

payments?array<>

Payment entries for receipts. Each payment can have different payment methods and amounts.

documentDiscountType?string

Document-level discount type: PERCENT or FIXED.

PERCENT: documentDiscountPercent field is used (0-100)
FIXED: documentDiscountAmount field is used as exact discount value

Default: No document discount

Value in

"PERCENT"
"FIXED"

documentDiscountPercent?number

Document-level discount percentage (0-100). Used when documentDiscountType = PERCENT.

Formula: documentDiscountAmount = itemsTotal × (documentDiscountPercent / 100)

Range0 <= value <= 100

Default0

documentDiscountAmount?number

Document-level discount amount (fixed value). Used when documentDiscountType = FIXED. This is the calculated discount amount that will be subtracted from the items total.

Range0 <= value

subTotal*number

REQUIRED when items provided: Document subtotal before VAT (calculated by frontend). Server validates this equals sum of all lineSubTotal values (±0.01).

Formula: subTotal = Σ(items.lineSubTotal)

vatTotal*number

REQUIRED when items provided: Document VAT total (calculated by frontend). Server validates this equals sum of all lineVatTotal values (±0.01).

Formula: vatTotal = Σ(items.lineVatTotal)

grandTotal*number

REQUIRED when items provided: Document grand total including VAT and after document discount (calculated by frontend). Server validates this equals: Σ(items.lineGrandTotal) - documentDiscountAmount (±0.01).

Formula: grandTotal = Σ(items.lineGrandTotal) - documentDiscountAmount

partnerExternalRef?|

Partner's internal order/document ID — set when this document was issued via the Partner API (apps/client-api/src/partner-api/). Unique within the merchant business. Not used by the client-dashboard create form.

metadata?|

Internal passthrough metadata, stored verbatim on the document. Used e.g. by PaymentCheckoutService.issueDocumentForPayment to carry the merged page+sale merchant metadata (webhooks-automation plan §1.9-C) — not surfaced on the client-dashboard create form.

reference?|

Caller's idempotency reference. Stored on the issued document (same externalReference storage/lookup the /integrations flow uses). A retry with the same reference for this business returns the already-issued document with created=false and HTTP 200 instead of issuing a second one.

Lengthlength <= 200

waitForPdf?boolean

When true (default), the response is held for a bounded ~8s window until the PDF has finished rendering, so pdfStatus comes back "completed". When the wait times out (or when false), the document is still issued and pdfUrl is still the stable address — pdfStatus is then "processing" and the PDF becomes available at that URL a moment later.

Defaulttrue

Response Body

`application/json`

curl -X POST "https://example.com/documents/issue" \  -H "Content-Type: application/json" \  -d '{    "businessId": "660e8400-e29b-41d4-a716-446655440000",    "docType": "tax_invoice_receipt",    "issueDate": "2025-01-15",    "subTotal": 2700,    "vatTotal": 486,    "grandTotal": 3086  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "documentNumber": "50001",  "documentType": "order",  "status": "draft",  "subtotal": 200,  "vatTotal": 36,  "total": 236,  "currency": "ILS",  "issuedAt": "2026-07-22T00:00:00.000Z",  "pdfUrl": "/api/v1/documents/880e8400-e29b-41d4-a716-446655440000/pdf",  "pdfStatus": "completed",  "allocationStatus": "not_required",  "allocationNumber": {},  "created": true,  "reference": "order-2026-000123"}

Create and issue a document in one call

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`