The VUZ Partner API is REST over HTTPS. Predictable URLs, JSON bodies, snake_case fields, HTTP status codes you’d expect.
Environments
VUZ currently runs in two environments. Pick the right base URL for the stage you’re in.
| Stage | Base URL | When to use |
|---|
| Local integration | https://localhost:3020/api/v1/partner | While we co-develop with you on our dev machine. HTTPS-only (self-signed cert). |
| Production | https://api.vuz.co.il/api/v1/partner | Real merchants, real tax documents. Every request hits the regulator-compliant pipeline. |
A dedicated sandbox environment is not yet available. Today, vuz_test_* and vuz_live_* API keys both target the production database — the prefix is informational only. Treat every call against production as a real, audited action. Sandbox-isolated infrastructure (api.sandbox.vuz.co.il with its own DB) is on the near-term roadmap; we’ll announce it in the changelog when it ships.
Authentication
All requests require a Bearer token in the Authorization header:
Authorization: Bearer vuz_live_xxxxxxxxxxxx
| Prefix | Marker | Today’s behavior |
|---|
vuz_live_* | Production key | Hits production DB, creates real documents |
vuz_test_* | Sandbox-flagged key | Hits the same production DB (sandbox isolation is roadmap) |
Resources
- Merchants — child businesses you parent on VUZ
- Clients — end customers of each merchant
- Documents — the tax invoices, receipts, and credit notes you issue
- Webhooks — async event notifications back to your server
Core principles
| Principle | What it means |
|---|
| Idempotent writes | Every POST takes a partnerExternalRef. Retrying with the same ref returns the same record — never duplicates. |
| Predictable shapes | All money is decimal strings ("84.37"). All dates are ISO 8601. All IDs are UUIDv4. |
| Synchronous default | POST /documents returns the issued document with number assigned, in ~500ms. |
| Real signatures | Every document is digitally signed per VAT Circular 24/2004 — no “fake mode” today. |