מספר הקצאה ב-API: המספר מגיע בתוך קריאת ההפקה

מתי חשבונית צריכה מספר הקצאה

לפי רפורמת ״חשבוניות ישראל״, חשבונית מס (סוג 305) או חשבונית מס קבלה (סוג 320) צריכה מספר הקצאה כששלושה תנאים מתקיימים יחד:

• הסכום לפני מע״מ גבוה מ-5,000 ₪ (הסף מ-1 ביוני 2026).
• החשבונית נושאת מע״מ.
• הקונה הוא עסק מזוהה, שצריך את המספר כדי לנכות את מס התשומות.

רוב המכירות ללקוחות פרטיים לא מגיעות לסף, ולכן רוב החנויות לא יפגשו את הנושא בכלל. ההסבר המלא על הכלל עצמו נמצא במדריך למספר הקצאה, ואפשר לבדוק חשבונית מסוימת בכלי הבדיקה.

שלב 1: בעל העסק מחבר את העסק לרשות המסים

רשות המסים נותנת את הזכות לבקש מספרים לעסק, לא לתוכנה. לכן בעל העסק מאשר בעצמו, פעם אחת, בעמוד של הרשות ועם הפרטים שלו. האפליקציה שלכם פותחת את התהליך ומקבלת אותו בחזרה:

curl -X POST "$BASE/businesses/$BID/ita/connect" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl": "https://app.example.com/settings/tax", "state": "user-1842"}'

# 201
# { "ok": true, "url": "https://openapi.taxes.gov.il/…", "expiresAt": "…", "sandbox": false }

1. שולחים את בעל העסק לכתובת שחזרה

   פותחים אותה בדפדפן שלו. עם "link": true מקבלים כתובת שאפשר לשלוח במייל או בוואטסאפ, והיא תקפה 24 שעות.

2. הוא מאשר ברשות המסים

   נכנס עם הפרטים שלו ומאשר את BillOS.

3. הדפדפן חוזר אליכם

   לכתובת returnUrl, עם ita=connected (או denied, או error), מזהה העסק וה-state שלכם.

4. מאמתים לפני שמודיעים לו שהצליח

   פרמטר בכתובת הוא משהו שכל אחד יכול להקליד. קוראים את הסטטוס, או מחכים לאירוע ita.connected.

curl "$BASE/businesses/$BID/ita" -H "X-Api-Key: $KEY"

# { "ok": true, "ita": { "status": "active", "connected": true,
#     "connectedAt": "2026-10-27T09:12:00.000Z", "expiresAt": "2027-01-25T09:12:00.000Z", "daysLeft": 90 } }

מה ש-BillOS מחזיקה הוא ההרשאה עצמה, מוצפנת, והיא לא יוצאת מ-BillOS. אתם קוראים סטטוס, לא אסימון.

שלב 2: מפיקים, והמספר חוזר על המסמך

מכאן אין שום דבר מיוחד לעשות. מפיקים חשבונית כרגיל. אם היא צריכה מספר, BillOS מבקשת אותו מרשות המסים בתוך קריאת ההפקה:

DOC=$(curl -s -X POST "$BASE/businesses/$BID/documents" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-2207" -d '{
    "docType": 305,
    "party": {"name": "אלפא מערכות בע״מ", "taxId": "123456782"},
    "lines": [{"description": "ריטיינר פיתוח, נובמבר", "quantity": 1, "unitPriceExVat": 1200000}]
  }' | jq -r .document.id)

curl -s -X POST "$BASE/businesses/$BID/documents/$DOC/issue" -H "X-Api-Key: $KEY" \
  | jq '.document | {docNumber, allocationNumber}'

המספר מודפס על החשבונית תחת ״מספר הקצאה״. אם הוא הגיע רגע אחרי ההפקה, נשלח האירוע document.allocation_assigned עם מזהה המסמך והמספר.

כדי לדעת מראש מה יקרה, בודקים את הטיוטה בלי להפיק אותה. הקריאה POST …/documents/:id/validate מריצה את כל בדיקות ההפקה, כולל כלל ההקצאה, ולא תופסת מספר.

כשאין מספר: אזהרה או סירוב

ברירת המחדל היא שהחשבונית מופקת בכל מקרה, והתשובה אומרת מה קרה:

עסק שמעדיף לא להפיק חשבונית כזאת בלי מספר מפעיל מצב מחמיר. אז ההפקה מסורבת עם 422 allocation_required, ושום מספר מסמך לא נתפס:

curl -X PATCH "$BASE/businesses/$BID" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"requireAllocation": true}'

ההסכמה תקפה 90 יום

הסכמה של בעל העסק נמשכת 90 יום, ורק הסכמה חדשה מאריכה אותה. שלושה אירועים מלווים את זה, וכדאי להאזין להם מהיום הראשון:

כשבעל העסק לא חוזר מעמוד הרשות

שני דברים בצד של רשות המסים עוצרים הסכמה לעיתים קרובות, והדפדפן לא מגיע בחזרה לכתובת שלכם. הראשון הוא בדיקת זיהוי בחיבור ראשון דרך תוכנה: בעל העסק מקבל הודעת SMS על פעילות חריגה. השני הוא עסק שעדיין מחובר לתוכנת חשבוניות אחרת: הרשות מאפשרת תוכנה אחת, והעמוד שלה מודיע שלא ניתן להשלים את הפעולה.

שיחה אחת פותרת את שניהם: מוקד התמיכה לבתי תוכנה ברשות המסים, 02-5688444 שלוחה 2. מבקשים לשחרר את חסימת הזיהוי או לנתק את התוכנה הקודמת, ואחרי השיחה מתחילים את החיבור מחדש בלשונית חדשה. אם הסטטוס עדיין not_connected כמה דקות אחרי ששלחתם אותו, זה מה שכדאי להגיד לו.

בודקים ב-Sandbox

במפתח bk_test_ אותה קריאת ita/connect מחזירה עמוד של BillOS שעומד במקום העמוד של הרשות, עם כפתורי אישור וסירוב. שום דבר לא מגיע לרשות המסים. כדי לבדוק את התזכורות שלכם בלי לחכות 90 יום:

curl -X POST "$BASE/businesses/$BID/ita/simulate" -H "X-Api-Key: $KEY" \
  -H "Content-Type: application/json" -d '{"state": "expiring"}'    # or "expired"

חשבונית מעל הסף מופקת ב-Sandbox עם האזהרה allocation_missing, או מסורבת כש-requireAllocation פעיל, כך ששני המסלולים נבדקים לפני המעבר ל-live. התיעוד המלא: docs.billos.co.il.