התחלה מהירה

בסוף המדריך הזה יהיו לכם:

1. ✅ מפתח API של sandbox עם ההרשאות הנכונות
2. ✅ לקוח שנוצר
3. ✅ מסמך מסוג tax_invoice_receipt שנוצר והונפק סופית
4. ✅ תצוגה מקדימה של ה-PDF

זמן קריאה: כ-5 דקות. כל המדריך רץ מול ה-sandbox (https://sandbox-api.vuz.co.il) — סביבת בדיקות אמיתית ומבודדת לחלוטין עם מסד נתונים משלה, כך ששום דבר שתעשו כאן לא יוצר מסמך אמיתי, לא שולח הודעה אמיתית ולא מחייב אף אחד. המעבר לייצור בסוף הוא שינוי של שתי שורות.

שלב 1 — יצירת מפתח sandbox

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

POST https://api.vuz.co.il/api/v1/api-keys/sandbox
Authorization: Bearer <your dashboard JWT>
X-Business-Id: <your business id>

התשובה כוללת את המפתח הגולמי פעם אחת בלבד:

{
  "businessId": "b6b0b8b0-...",
  "rawKey": "vuz_ab12cdef3456789012345678901234567890abcdef12",
  "keyPrefix": "vuz_ab12",
  "environment": "sandbox",
  "created": true
}

מפתח ה-sandbox מונפק עם כל סט ההרשאות הקנוני, כך שכל הקריאות במדריך פשוט יעבדו. שמרו את rawKey במקום בטוח — הוא לא יוצג שוב. מכאן והלאה כל בקשה שולחת אותו ככותרת X-Api-Key. שימו לב: המחרוזת של המפתח נראית אותו דבר בשתי הסביבות (vuz_...) — הבידוד מגיע ממסד נתונים נפרד לחלוטין, לא מהקידומת (ראו אימות ← מפתחות API).

שלב 2 — יצירת לקוח

curl -X POST https://sandbox-api.vuz.co.il/api/v1/clients \
  -H "X-Api-Key: vuz_ab12cdef3456789012345678901234567890abcdef12" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Cohen",
    "email": "dana@example.com"
  }'

שימו לב — בלי כותרת X-Business-Id: מפתח ה-API עצמו קשור לעסק שלכם (ראו מושגי יסוד ← עסק).

שלב 3 — יצירת מסמך

curl -X POST https://sandbox-api.vuz.co.il/api/v1/documents \
  -H "X-Api-Key: vuz_ab12cdef3456789012345678901234567890abcdef12" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "9b2f6b2e-2e1e-4b7e-9f1e-1e2e3e4e5e6e",
    "docType": "tax_invoice_receipt",
    "issueDate": "2026-07-01",
    "vatMode": "exclusive",
    "items": [
      {
        "description": "Consulting - 2 hours",
        "quantity": 2,
        "unitPrice": 150,
        "vatApplicable": true,
        "vatRate": 17,
        "lineSubTotal": 300,
        "lineVatTotal": 51,
        "lineGrandTotal": 351
      }
    ],
    "subTotal": 300,
    "vatTotal": 51,
    "grandTotal": 351
  }'

שלב 4 — הנפקה סופית

POST /documents יוצר מסמך במצב DRAFT (טיוטה). ההנפקה הסופית היא קריאה נפרדת (עם הרשאה נפרדת — documents:finalize) שמקצה מספר רץ, יוצרת PDF חתום, ומבקשת מספר הקצאה מרשות המסים כשנדרש:

curl -X POST https://sandbox-api.vuz.co.il/api/v1/documents/205bd0d9-0c71-419f-989e-d5b2b790fe85/finalize \
  -H "X-Api-Key: vuz_ab12cdef3456789012345678901234567890abcdef12"

המסמך חוזר במצב ISSUED — ממוספר ובלתי ניתן לשינוי. ראו מושגי יסוד ← מסמכים.

שלב 5 — תצוגה מקדימה של ה-PDF

curl "https://sandbox-api.vuz.co.il/api/v1/documents/205bd0d9-0c71-419f-989e-d5b2b790fe85/pdf/preview" \
  -H "X-Api-Key: vuz_ab12cdef3456789012345678901234567890abcdef12" \
  -o preview.pdf

מסמכי טיוטה מוצגים עם סימן מים DRAFT; ?draft=false לאחר הנפקה סופית. ?language=he|en קובע את שפת ה-PDF (ברירת מחדל: he).

מעבר לייצור

שני שינויים בלבד:

1. יצירת מפתח ייצור: הגדרות ← אינטגרציות ← מפתחות API ← יצירה, עם ההרשאות שאתם באמת צריכים בלבד.
2. החלפת כתובת הבסיס ל-https://api.vuz.co.il/api/v1.

מפתח sandbox לעולם לא יעבוד מול הייצור (ולהפך) — לסביבות מסדי נתונים נפרדים לחלוטין, וכל תשובה מציינת מי ענה בכותרת X-Vuz-Environment: live|sandbox.

סיימתם 🎉