מבוא

מטמיעים את ההזמנות מהחנות שלכם לתוך VUZ — מסמכים תואמי מס ישראלי, API אחד, שתי אפשרויות אימות.

Prefer English? Switch to the English docs. התוכן הטכני — קוד, שמות שדות, קטגלוג ה-API — נשאר תמיד באנגלית בלבד, גם כאן.

מה אפשר לבנות

ה-API הציבורי של VUZ מאפשר לעסק ה-VUZ שלכם — חנות, תוסף, אינטגרציה מותאמת אישית — להנפיק מסמכים תואמי מס ישראלי, לנהל לקוחות, ולקבל עדכונים בזמן אמת, הכול דרך REST:

מסמכים (Documents) — יצירת חשבוניות מס / קבלות / הצעות מחיר / זיכויים, הנפקה סופית (מספר רץ, PDF חתום, מספר הקצאה מרשות המסים כשנדרש), ביטול, שיתוף במייל/SMS/ WhatsApp ותצוגה מקדימה של PDF — עם חישוב מע"מ לפי כללי המס הישראלי
לקוחות ו-CRM — הלקוחות שאתם מחייבים, ובנוסף משפכי מכירה, עסקאות, משימות, פגישות ויומני שיחות
קטלוג ומלאי — ניהול מוצרים מלא, מחסנים, תנועות מלאי וספירות
הוצאות — יצירת הוצאות, OCR על קבלות, אישור וייצוא
כספים — קישורי תשלום, הוראות קבע, תנאי תשלום וכרטסת לקוח
דוחות — מאזן בוחן, רווח והפסד, מאזן, דוחות מע"מ וייצוא במבנה אחיד
Webhooks — הרשמה לאירועים כמו document.finalized ו-payment.received, עם חתימת HMAC-SHA256 על כל שליחה

bolt

התחלה מהירה — 5 דקות

ממפתח API ועד למסמך חתום ראשון, שלב אחר שלב.

code

הפניית API מלאה

כל endpoint, כל שדה, כל שגיאה — עם בדיקה חיה (באנגלית בלבד).

API אחד, שתי אפשרויות אימות (credentials)

אין namespace נפרד ל"API ציבורי" — ה-endpoints שלמעלה הם בדיוק אותם routes תחת /api/v1/* שגם לוח הבקרה של VUZ עצמו משתמש בהם. כל route שמקבל אמצעי אימות סומן לכך במפורש — נכון להיום מדובר ב-439 פעולות ב-62 קבוצות משאבים, כל אחת מוגנת בהרשאות (scopes). שני אמצעי האימות עובדים על כולן באופן זהה:

מפתח API (כותרת X-Api-Key) — הדרך הפשוטה ביותר למפתחים; ניתן ליצור מתוך הגדרות ← אינטגרציות ← מפתחות API בלוח הבקרה. פרטים באימות ← מפתחות API.
טוקן OAuth 2.0 (Authorization: Bearer vuz_at_...) — לתוסף חנות (כמו WooCommerce) שמתחבר לעסק ה-VUZ שלכם בלי לשתף איתו סוד גולמי. פרטים באימות ← OAuth.

שני סוגי האמצעים נושאים הרשאות (scopes), מוגבלים בקצב (rate-limited), וקשורים לעסק אחד בלבד — האמצעי עצמו קובע איזה עסק אתם נוגעים בו; אתם לעולם לא שולחים מזהה עסק בעצמכם.

אתם ריסלר/מצרף שמנפיק מסמכים בשם מספר עסקים לקוחות? זה משטח נפרד — ראו Partner / Reseller API (באנגלית בלבד).

מה זה לא

לא namespace חדש. אין /api/v1/public/*. ה-routes הנגישים ל-API ציבורי הם endpoints רגילים של לוח הבקרה שסומנו במפורש כמקבלים גם אמצעי אימות.
לא גישה בלתי מוגבלת. המשטח רחב (439 פעולות), אבל כל אמצעי אימות קשור לעסק אחד בלבד ומוגבל להרשאות שהוענקו לו — מפתח עם documents:read בלבד לא יכול לגעת בהוצאות, בכרטסת או בכל משאב אחר.

הסביבות

ל-VUZ יש sandbox מבודד לחלוטין (https://sandbox-api.vuz.co.il/api/v1) לצד סביבת הייצור (https://api.vuz.co.il/api/v1) — מסד נתונים נפרד לחלוטין, ללא כל מצב משותף. קבלו מפתח sandbox דרך הגדרות ← אינטגרציות ← מפתחות API ← "מפתח sandbox" ופתחו כרצונכם: התנהגות אמיתית מקצה לקצה, אך שום מייל/SMS/WhatsApp לא יוצא ממנה בפועל, אין בקשת מספר הקצאה אמיתי ברשות המסים, שום כרטיס לא מחויב, וכל PDF מסומן בסימן מים "SANDBOX — לא מסמך חוקי". סייר ה-API בעמודי הרפרנס פונה כברירת מחדל לייצור — החליפו את בורר השרת ל-Sandbox אם אתם לא מוכנים ליצור מסמך אמיתי.

הצעדים הבאים

קבלת מפתח API

מלוח הבקרה: הגדרות ← אינטגרציות ← מפתחות API ← יצירה. הענקת ההרשאות שאתם צריכים (למשל documents:write, clients:write).

הנפקת המסמך הראשון

עברו על ההתחלה המהירה — ממפתח API ועד למסמך עם תצוגה מקדימה של PDF.

חיבור webhook

הרשמה לאירוע document.finalized כדי לדעת ברגע שמסמך מונפק. ראו Webhooks ← Events (באנגלית).