Partner Quickstart

Issue a tax invoice on behalf of a merchant in 5 minutes — from a real sandbox key to a PDF, end-to-end.

This is the reseller/aggregator quickstart (/api/v1/partner/*). If you're integrating your own single VUZ business, use the main Quickstart instead.

By the end of this guide you'll have:

✅ Created a merchant on VUZ
✅ Created an end customer under that merchant
✅ Issued a tax_invoice_receipt for ₪84.37 (including 18% VAT)
✅ Received the PDF URL synchronously in the response
✅ Downloaded the signed, compliant PDF

Total reading time: 5 minutes. Total run time: ~10 seconds.

Prerequisites

API key

Ask your VUZ contact for a sandbox key (vuz_test_*) — a real, isolated test environment with its own database, its own merchants, its own everything. Nothing you do with it ever touches production or a real customer. Store it securely — it's only shown once.

Base URL

Use https://sandbox-api.vuz.co.il/api/v1 for everything below — a vuz_test_* key only ever works there (a vuz_live_* key only works against https://api.vuz.co.il/api/v1, and vice versa — mixing them returns 403 auth.key_environment_mismatch). Once you're ready to go live, request a vuz_live_* key and swap the host and the Authorization header — nothing else changes.

A merchant's tax info

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

What's actually different in the sandbox: no email/SMS/WhatsApp ever reaches a real inbox (suppressed or redirected to a developer address), Tax Authority calls are routed to the Authority's own test environment (tsandbox) so no legally valid allocation number is ever issued, no card is ever charged, and every PDF is watermarked "SANDBOX — NOT A LEGAL DOCUMENT." Data in the sandbox is disposable — inactive tenants are purged automatically. See Sandbox guardrails for the full list.

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://sandbox-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 -X POST "https://sandbox-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 https://sandbox-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".

What VUZ does automatically (no extra calls needed)

Journal entries posted

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

Customer ledger updated

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

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).

Webhook fired to your endpoint

If you've registered a webhook, you'll receive a document.finalized event with an HMAC-SHA256 signature — see Webhooks → Signature verification.