By the end of this guide you’ll have:
  1. ✅ Created a merchant on VUZ
  2. ✅ Created an end customer under that merchant
  3. ✅ Issued a tax_invoice_receipt for ₪84.37 (including 18% VAT)
  4. ✅ Received the PDF URL synchronously in the response
  5. ✅ Downloaded the signed, compliant PDF
Total reading time: 5 minutes. Total run time: ~10 seconds.

​
Prerequisites

1

API key

Email partners@vuz.co.il to request a key. You’ll receive a vuz_test_* (sandbox-marker) or vuz_live_* (production-marker) token. Store it securely — it’s only shown once. Today both kinds hit production — sandbox isolation is on the roadmap.
2

Base URL

Use https://api.vuz.co.il/api/v1 for production, or https://localhost:3020/api/v1 while integrating against your local dev VUZ instance. All examples below use production.
3

A merchant's tax info

For real-world use, provide the merchant’s legal name, ע.מ./ח.פ., and address. For this quickstart, we provide test data.

​
Step 1 — Create a merchant

A merchant is a child VUZ business that you (the partner) parent. Pass their legal info — VUZ creates the dormant user, generates a digital signing certificate, and initializes a chart of accounts. 
curl -X POST https://api.vuz.co.il/api/v1/partner/merchants \
  -H "Authorization: Bearer vuz_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerExternalRef": "TG-MERCH-001",
    "legalName": "מאפייה בוטיק לוי בעמ",
    "businessType": "limited_company",
    "taxId": "514329876",
    "email": "owner@bakery-001.co.il",
    "phone": "+972501234567",
    "address": "דיזנגוף 50, תל אביב"
  }'
Response: 
{
  "merchant": {
    "id": "927c10ab-e59e-4c33-91a8-7bb663e2035c",
    "partnerExternalRef": "TG-MERCH-001",
    "legalName": "מאפייה בוטיק לוי בעמ",
    "businessType": "limited_company",
    "taxId": "514329876",
    "currency": "ILS",
    "createdAt": "2026-05-13T13:48:20.757Z"
  },
  "created": true
}
Idempotency built-in. Send the same partnerExternalRef twice — you get the same merchant ID back with "created": false. Safe to retry on network failure forever.

​
Step 2 — Issue a tax invoice receipt

This single call creates the document, finalizes it, generates the PDF, and returns the URL.
cURL
curl -X POST "https://api.vuz.co.il/api/v1/partner/merchants/927c10ab.../documents" \
  -H "Authorization: Bearer vuz_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerExternalRef": "TG-ORDER-887234",
    "documentType": "tax_invoice_receipt",
    "client": {
      "partnerExternalRef": "TG-CUST-99821",
      "name": "דנה כהן",
      "type": "private",
      "email": "dana@example.com",
      "phone": "+972503334444"
    },
    "items": [
      { "description": "לחמנייה טרייה", "quantity": 3, "unitPrice": 8.50 },
      { "description": "קפה הפוך", "quantity": 1, "unitPrice": 14.00 },
      { "description": "עוגת גבינה", "quantity": 1, "unitPrice": 32.00 }
    ],
    "payment": {
      "method": "credit_card",
      "amount": 84.37,
      "reference": "TZN-887234",
      "creditCompanyCode": 2,
      "cardName": "Visa",
      "cardLastDigits": "1234"
    },
    "waitForPdf": true
  }'
Response (~2 seconds): 
{
  "document": {
    "id": "205bd0d9-0c71-419f-989e-d5b2b790fe85",
    "partnerExternalRef": "TG-ORDER-887234",
    "documentType": "tax_invoice_receipt",
    "documentNumber": "60014",
    "status": "issued",
    "issueDate": "2026-05-13",
    "subTotal": "71.50",
    "vatTotal": "12.87",
    "grandTotal": "84.37",
    "currency": "ILS",
    "pdfStatus": "completed",
    "pdfUrl": "/api/v1/partner/merchants/927c10ab.../documents/205bd0d9.../pdf"
  },
  "created": true,
  "pdfWaitedMs": 1843
}
waitForPdf: true makes the request block (~2 sec) until the PDF is rendered and uploaded to S3. If you don’t need the URL in the response, omit it — the request returns in ~500ms and the PDF generates asynchronously. VUZ delivers the invoice to your end customer regardless.

​
Step 3 — Download the PDF

The pdfUrl works with the same API key. Just GET it.
cURL
curl https://api.vuz.co.il/api/v1/partner/merchants/927c10ab.../documents/205bd0d9.../pdf \
  -H "Authorization: Bearer vuz_test_xxx" \
  -o invoice-60014.pdf
Response: Content-Type: application/pdf, Content-Disposition: attachment; filename="TAX_INVOICE_RECEIPT-60014-...pdf". The PDF is:
  • ✅ Digitally signed (Israeli VAT Circular 24/2004 compliant)
  • ✅ Sequential document number (assigned per merchant)
  • ✅ Full Hebrew right-to-left rendering
  • ✅ VAT breakdown shown (subtotal + 18% VAT + grand total)
  • ✅ Includes your platform’s branding (when partner template is configured)

​
What VUZ does automatically (no extra calls needed)

After document creation:
1

Journal entries posted

Debit Cash (1100) ₪84.37 / Credit Revenue (4000) ₪71.50 / Credit VAT Payable (2200) ₪12.87 — balanced double-entry, written automatically.
2

Customer ledger updated

Invoice + payment entries written. Outstanding balance = ₪0.00 for this receipt.
3

Email sent to end customer

Sent via AWS SES with the PDF attached. Subject line and body localized to the merchant’s language preference (Hebrew default).
4

Webhook fired to your endpoint

If you’ve registered a webhook, you’ll receive document.finalized and document.delivered events with HMAC-SHA256 signatures.

​
You did it 🎉

That’s the entire happy path. Next:

Handle errors

Every error code, what it means, and how to recover.

Set up webhooks

Get notified of every event in real time.

Issue a refund

Credit notes that legally reverse a prior invoice.

Full API Reference

Every endpoint, every parameter, with live testing.