Create a new document

Creates a new accounting document (invoice, receipt, tax invoice, etc.) with line items and automatic calculations.

Document Types:

INVOICE (חשבונית): Standard invoice without VAT
RECEIPT (קבלה): Payment receipt
TAX_INVOICE (חשבונית מס): Tax invoice with VAT
TAX_INVOICE_RECEIPT (חשבונית מס קבלה): Combined tax invoice and receipt (most common in Israel)
QUOTE (הצעת מחיר): Price quotation
CREDIT_NOTE (זיכוי): Credit note for refunds/corrections
DEAL_BILL (חשבון עסקה): Deal bill for osek pator (not charging VAT)

Document Workflow:

DRAFT: Editable, no document number assigned, can be modified freely
ISSUED: Immutable, document number assigned, PDF generated, sent to client
CANCELED: Marked as void, document number preserved for audit trail

VAT Calculation Modes:

EXCLUSIVE: VAT added on top of line item prices (most common for B2B)
INCLUSIVE: VAT included in line item prices (common for B2C)
NONE: No VAT applied (for exempt transactions or private clients)

Required Fields:

businessId: Multi-tenant scoping
clientId: Client this document is issued to
docType: Document type (invoice, receipt, etc.)
issueDate: Document issue date
items: At least one line item with description, quantity, unitPrice

Automatic Calculations:

Line item subtotals: quantity × unitPrice × (1 - discountPercent/100)
Line item VAT: subtotal × (vatRate / 100) if VAT applicable
Document subtotal: Sum of all line item subtotals
Document VAT total: Sum of all line item VAT amounts
Grand total: subtotal + vatTotal

Example Use Case: Creating a tax invoice receipt for consulting services: "ייעוץ עסקי - 10 שעות" @ ₪150/hour = ₪1,500 subtotal

17% VAT (₪255) = ₪1,755 total

Creating Credit Notes (חשבונית זיכוי)

Credit notes are used to reverse or partially refund issued invoices. They follow special rules per Israeli Tax Authority requirements.

Credit Note Requirements:

docType: "CREDIT_NOTE"
originalDocumentId: REQUIRED - UUID of the original invoice being credited
Line items should have NEGATIVE amounts (or positive amounts will be converted to negative on finalization)
The original invoice must be finalized (ISSUED status)

Credit Note Types:

Full Credit (ביטול מלא):
- Credit the entire invoice amount
- Use same line items as original with negative quantities/amounts
Partial Credit (זיכוי חלקי):
- Credit specific amount or specific items
- Create line items for only the items being credited

Credit Note with Refund vs Non-Refund:

metadata.isRefund: true - Money returned to customer (affects Bank account in journal)
metadata.isRefund: false - Reduces Accounts Receivable (customer debt reduced)

Example - Full Credit Note:

{  "businessId": "xxx",  "clientId": "yyy",  "docType": "CREDIT_NOTE",  "originalDocumentId": "original-invoice-uuid",  "issueDate": "2025-01-20",  "items": [    {      "description": "ייעוץ עסקי - 10 שעות (זיכוי)",      "quantity": -10,      "unitPrice": 150,      "vatApplicable": true    }  ],  "notes": "Credit note for invoice #123. Reason: Service cancellation"}

Example - Partial Credit Note:

{  "businessId": "xxx",  "clientId": "yyy",  "docType": "CREDIT_NOTE",  "originalDocumentId": "original-invoice-uuid",  "issueDate": "2025-01-20",  "items": [    {      "description": "Partial refund - 3 hours",      "quantity": -3,      "unitPrice": 150,      "vatApplicable": true    }  ],  "notes": "Partial credit for 3 hours. Reason: Service adjustment"}

Journal Entry Created:

DR 4000 (Revenue) - reduces revenue
DR 2200 (VAT Payable) - reduces VAT liability
CR 1300 (AR) - if non-refund
CR 1100 (Bank) - if refund

Validations:

Original document must be ISSUED (finalized)
Cannot credit a credit note
Cannot credit canceled documents
Credit amount cannot exceed original invoice balance

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.

Response Body

`application/json`

curl -X POST "https://example.com/documents" \  -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": "880e8400-e29b-41d4-a716-446655440000",  "createdAt": "2025-11-09T09:31:07.507Z",  "updatedAt": "2025-11-09T09:31:07.523Z",  "deletedAt": null,  "docType": "quote",  "docNumber": null,  "status": "draft",  "issueDate": "2025-11-09",  "issueTime": "14:32:07",  "documentDate": "2025-11-05",  "dueDate": "2025-12-09",  "documentDatePeriodClosed": true,  "backdateAckAt": "2019-08-24T14:15:22Z",  "backdateAckByUserId": "7009be0c-f167-48ba-92d0-be39eb8a403b",  "paymentTermsId": "990e8400-e29b-41d4-a716-446655440000",  "paymentTermsText": "שוטף + 30",  "currency": "ILS",  "fxRate": null,  "vatMode": "exclusive",  "vatRateDefault": 17,  "subTotal": "150.00",  "vatTotal": "25.50",  "grandTotal": "175.50",  "clientName": null,  "clientTaxId": null,  "clientAddress": null,  "notes": null,  "metadata": null,  "originalDocumentId": null,  "parentDocumentId": null,  "cancelledByDocumentId": null,  "pdfPath": null,  "publicSlug": "j3AxtCjwHS",  "isPublicEnabled": true,  "clientPhoneSnapshot": "+972522456789",  "branchId": "string",  "branchName": "string",  "parentClientName": "string",  "signedAt": null,  "signatureImagePath": null,  "signatureName": null,  "signatureNote": null,  "outstandingAmount": null,  "paidAt": null,  "paymentStatus": "UNPAID",  "documentBalance": 1000,  "totalPaymentsReceived": 0,  "totalCreditsApplied": 0,  "roundingAdjustment": -0.01,  "paymentStatusUpdatedAt": null,  "paymentLinkUrl": "https://pay.vuz.co.il/abc123def456",  "paymentLinkId": "990e8400-e29b-41d4-a716-446655440000",  "paymentLinkStatus": "active",  "paymentLinkExpiresAt": "2025-12-25T00:00:00.000Z",  "isClosed": false,  "closedAt": null,  "closedBy": null,  "isInteractive": false,  "interactiveStatus": "negotiation",  "publicToken": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",  "publicTokenExpiresAt": "2025-12-25T00:00:00.000Z",  "negotiationVersion": 1,  "business": {    "id": "50596d36-8006-4aeb-a29e-ca78edddb2df",    "businessName": "אקו דב",    "ownerPhone": "972527253023",    "vatRate": 18,    "currency": "ILS",    "vatNumber": "300160629",    "logoPath": null,    "address": null,    "email": "naor@echo-dev.co.il",    "businessMeta": {      "logoUrl": "/uploads/logos/fd32d6f3-f790-4999-b30a-df360993123b.jpg"    },    "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34",    "isActive": true,    "isOnTrial": true,    "trialEndDate": "2025-11-11"  },  "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df",  "client": {    "id": "3c3e3b30-924b-4a9f-9fbc-516010d36427",    "name": "אקסיומה",    "type": "company_ltd",    "email": "yosi@exioma.co.il",    "phone": "0522456789",    "address": "צנחנים 1 רעננה",    "vatNumber": "111111111",    "contactPerson": "יוסי בוכניק",    "notes": "",    "isActive": true,    "userId": "45b9de13-426f-45f8-98f8-a8a8961acf34",    "businessId": "50596d36-8006-4aeb-a29e-ca78edddb2df"  },  "clientId": "3c3e3b30-924b-4a9f-9fbc-516010d36427",  "createdBy": null,  "updatedBy": null,  "origin": "web",  "originName": "vuz",  "items": [    {      "id": "990e8400-e29b-41d4-a716-446655440000",      "lineNo": 1,      "description": "ייעוץ עסקי - 10 שעות",      "quantity": "10.000",      "unit": "שעות",      "unitPrice": "150.00",      "discountPercent": "0.00",      "vatApplicable": true,      "vatRate": 17,      "lineSubTotal": "150.00",      "lineVatTotal": "25.50",      "lineGrandTotal": "175.50",      "createdAt": "2025-11-09T09:31:07.518Z",      "updatedAt": "2025-11-09T09:31:07.518Z",      "deletedAt": null,      "documentId": "25cd5cfb-8e24-4dd6-b564-0b3c06cb9056"    }  ],  "payments": [    {      "id": "990e8400-e29b-41d4-a716-446655440000",      "paymentMethod": "cash",      "paymentProvider": "string",      "amount": 500,      "paymentDate": "2025-11-09",      "notes": "Payment for invoice #123",      "referenceNumber": "REF-12345",      "bankNumber": "12",      "branchNumber": "456",      "accountNumber": "123456789",      "checkNumber": "123456",      "dueDate": "2025-02-15",      "creditCompanyCode": 2,      "cardName": "Visa",      "cardLastDigits": "1234",      "creditTransactionType": 1,      "numberOfInstallments": 3,      "tranzilaTransactionId": "6982",      "tranzilaAuthCode": "0672865"    }  ],  "aiSummaryData": {}}

Creating Credit Notes (חשבונית זיכוי)

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`