Idempotency
The honest current state — and how to keep a retry from double-billing a customer.
Read this before you wire up retries. POST /api/v1/documents and POST /api/v1/clients on the main public API do not currently accept an idempotency key.
Retrying a failed request (timeout, 5xx, a flaky connection) creates a second
document or client. This page tells you exactly how to work around it today.
Why this page exists
VUZ's original integration surface — /integrations/*, built for the WooCommerce plugin
and still live as a compatibility alias — does have a real idempotency key:
externalReference, formatted source:site:entity:id (e.g.
wc:mystore.co.il:order:12345). Send the same externalReference twice on
POST /integrations/documents and you get the same document back, safe to retry forever.
The newer, curated /api/v1/documents and /api/v1/clients endpoints — the ones this
portal otherwise recommends — were built directly over the dashboard's CreateDocumentDto
/ CreateClientDto, which have no such field. This is a real, current gap, not a
documentation oversight.
What to do about it today
Keep your own mapping
Store yourOrderId → vuz.document.id (and yourCustomerId → vuz.client.id) in your own
system the moment you get a 201 back. Before creating, check whether you already have
a mapping for this order/customer — if so, skip the create call entirely.
If you're already on WooCommerce
Keep using /integrations/documents (POST, RequireScopes: documents:write, clients:write) — it has real externalReference idempotency and a
GET /integrations/documents/by-external/{ref} lookup. It's OAuth-bearer only (no
API-key support), and stays available as a compatibility alias.
On ambiguous failure, look before you retry
If a POST /documents call times out and you don't know whether it landed, call
GET /documents?clientId=...&fromDate=... (or your own mapping) before blindly
retrying — don't retry a write on a network error without checking first.
This gap is tracked; if your integration is retry-heavy, tell us at
developers@vuz.co.il — it helps prioritize adding externalReference support to the
main /api/v1/documents endpoint.