POST
/
partner
/
merchants
/
{merchantId}
/
documents
Create and finalize a tax document in one call
curl --request POST \
  --url https://api.vuz.co.il/api/v1/partner/merchants/{merchantId}/documents \
  --header 'Content-Type: application/json' \
  --data '
{
  "partnerExternalRef": "TG-ORDER-887234",
  "documentType": "tax_invoice_receipt",
  "items": [
    {
      "description": "לחמנייה",
      "quantity": 2,
      "unitPrice": 8.5,
      "vatRate": 18,
      "discountPercent": 0
    }
  ],
  "clientId": "550e8400-e29b-41d4-a716-446655440000",
  "issueDate": "2026-05-13",
  "notes": "תודה שהזמנת דרך TOGO",
  "originalDocumentId": "<string>",
  "waitForPdf": false
}
'

​
How it works

This is the heart of the Partner API. One call:
  1. Looks up the merchant (must belong to your partner)
  2. Resolves or creates the client (inline or by clientId)
  3. Computes line totals + VAT per Israeli tax law
  4. Persists the AccountingDocument as a draft
  5. Finalizes it — assigns the next sequential documentNumber, computes the document hash, posts double-entry journal entries (Cash / Revenue / VAT Payable), writes customer-ledger entries
  6. Queues PDF generation (Puppeteer → Wasabi S3)
  7. Fires the document.finalized webhook event to your subscribers
  8. Returns the issued document — number, totals, status, and (optionally) the PDF URL
Total elapsed: ~500 ms when waitForPdf is false, ~2.3 s when true.
Idempotent on partnerExternalRef. Send the same value twice — you get the same document back with created: false. Safe to retry forever (no Redis TTL, deduplicated at the DB level).

​
What happens after this call

For a ₪84.37 cash sale (OSEK_MURSHE merchant):
AccountDebitCredit
1100 Cash / A.R.84.37—
4000 Revenue—71.50
2200 VAT Payable—12.87
Balanced. Posted to journal_entries. Available in your merchant’s chart of accounts.
For receipts: one DEBIT (invoice) + one CREDIT (payment) — running balance closes to ₪0.00.
Puppeteer renders the document via the merchant’s bound template (or partner default). Uploaded to Wasabi S3.
AWS SES delivery with PDF attached, subject + body in the merchant’s preferred language (Hebrew default).
document.finalized event, signed with HMAC-SHA256 (X-Vuz-Signature). See Webhooks.

Path Parameters

​
merchantId
string
required

Body

application/json
​
partnerExternalRef
string
required

Partner's internal order/document ID. Unique within the merchant. Used for idempotency.

Example:

"TG-ORDER-887234"

​
documentType
enum<string>
required

Document type to issue

Available options:
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
Example:

"tax_invoice_receipt"

​
items
object[]
required

Line items

​
clientId
string

Existing client UUID. Provide either clientId OR inline client.

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
client
object

Inline client — used when client doesn't exist yet. Auto-creates one. Provide either clientId OR client.

​
issueDate
string

Issue date (ISO 8601). Defaults to today in IL timezone.

Example:

"2026-05-13"

​
payment
object

Payment info — required for receipt and tax_invoice_receipt

​
notes
string

Free-text note shown on the document

Example:

"תודה שהזמנת דרך TOGO"

​
originalDocumentId
string

Reference to the document being credited (REQUIRED for credit_note)

​
waitForPdf
boolean
default:false

When true, the API will wait synchronously until the PDF is generated (typically +2-4 sec) and return the PDF URL in the response. When false (default), the response returns immediately and the PDF is generated async — VUZ delivers it to the end customer regardless.

Response

201 - undefined