שליפה, רשימה וביטול מסמכים דרך ה-API

המסמך כבר נוצר, ועכשיו צריך אותו שוב

אחרי שהמערכת שלכם יצרה מסמך בביג בוס, מגיעות שאלות ההמשך: מה מצבו של המסמך עכשיו, אילו מסמכים נוצרו השבוע ללקוח מסוים, ואיך מבטלים מסמך כשההזמנה באתר בוטלה. שלוש פעולות בממשק ה-API עונות עליהן: document_get, document_list ו-document_cancel.

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

שימו לב: שלוש הפעולות עובדות עם אותו מפתח גישה ובאותו מבנה של בקשה ותשובה כמו שאר הממשק. מי ששולח בקשה בפעם הראשונה יתחיל בהקריאה הראשונה ל-API: מבנה הבקשה, התשובה וקודי התשובה.

 

שלוש הפעולות במבט אחד

 

שליפת מסמך אחד: document_get

שולחים את מזהה המסמך ב-document_id, או את סוג המסמך ב-document_type ואת המספר שלו ב-document_number. את הסוג כותבים באותם קודים כמו ביצירת מסמך, למשל 305 לחשבונית מס ו-400 לקבלה.

{
  "api_token": "<המפתח שלכם>",
  "document_type": 305,
  "document_number": 1052
}

התשובה מחזירה את המסמך כולו:

• פרטי המסמך: document_id, document_type_name (שם הסוג בעברית), document_date, due_date, מספר הלקוח ושמו, וסוג המע״מ.
• סכומים: לפני מע״מ, המע״מ, הסה״כ, ו-amount_open, הסכום שעוד פתוח.
• is_cancelled: 1 אם המסמך בוטל, ו-0 אם לא.
• request_reference: המזהה שהמערכת שלכם שלחה כשיצרה את המסמך.
• allocation_number ו-allocation_status: השדות של מספר ההקצאה.
• items: שורות המסמך, עם מק״ט, תיאור, כמות, מחיר ליחידה, אחוז הנחה וסה״כ לשורה. גם שורה חופשית מופיעה כאן, עם catalog_number ריק.
• payments: התקבולים, במסמך שיש בו תקבולים. מכרטיס אשראי חוזרות רק 4 הספרות האחרונות.
• document_link: קישור לעמוד הצפייה במסמך.

כך נראית התשובה, בקיצור:

"data": {
  "document_id": 31842,
  "document_type": 305,
  "document_type_name": "חשבונית מס",
  "document_number": 1052,
  "customer_id": 4821,
  "company_name": "לקוח לדוגמה",
  "total_amount": 118,
  "amount_open": 118,
  "is_cancelled": 0,
  "allocation_number": "",
  "allocation_status": 0,
  "request_reference": "ORDER-1052",
  "document_link": "https://www.bigboss.co.il/bigbossweb?vpid=...",
  "items": [
    { "line_number": 1, "catalog_number": "", "description": "שירות לדוגמה", "quantity": 1, "price_unit_nis": 100, "discount_percentage": 0, "line_total_nis": 100 }
  ],
  "payments": []
}

כשמשהו לא תקין:

• מסמך שלא קיים: 204 "מסמך לא נמצא".
• סוג בלי מספר: 400 "יש להעביר document_id, או document_type ו-document_number".
• סוג שאינו נתמך: 400 "סוג מסמך לא נתמך – document_type: 600", עם הסוג ששלחתם.

 

מסמך שנוצר דרך ה-API, כפי שהוא נפתח בביג בוס. "סכום פתוח" במסך הוא השדה amount_open בתשובה של document_get.

 

רשימת מסמכים: document_list

שולחים טווח תאריכים ב-date_from וב-date_to, עד 366 ימים. אפשר לסנן ללקוח אחד ב-customer_id ולסוג מסמך אחד ב-document_type.

{
  "api_token": "<המפתח שלכם>",
  "date_from": "2026-10-01",
  "date_to": "2026-10-05",
  "customer_id": 4821,
  "page": 1,
  "page_size": 100
}

התשובה מחזירה ארבעה שדות: page (מספר העמוד), page_size (כמה מסמכים בעמוד), total_count (כמה מסמכים נמצאו בסך הכול) ו-documents, המסמכים עצמם, מהחדש לישן. בקיצור:

"data": {
  "page": 1,
  "page_size": 100,
  "total_count": 2,
  "documents": [
    { "document_id": 31842, "document_type": 305, "document_number": 1052, "is_cancelled": 0, "request_reference": "ORDER-1052", "document_link": null, "items": null, "payments": null },
    { "document_id": 31790, "document_type": 3, "document_number": 640, "is_cancelled": 0, "request_reference": "", "document_link": null, "items": null, "payments": null }
  ]
}

בכל מסמך ברשימה יש את אותם פרטים כמו ב-document_get, חוץ משלושה: document_link, items ו-payments חוזרים ריקים (null). כשצריך את השורות, את התקבולים או את הקישור, שולפים את המסמך ב-document_get.

עימוד
page מתחיל ב-1, ו-page_size הוא בין 1 ל-500. בלי שני השדות מקבלים את העמוד הראשון, עם עד 100 מסמכים. כש-total_count גדול מגודל העמוד, מבקשים את העמוד הבא עם אותו סינון.

כשמשהו לא תקין:

• אין מסמכים שמתאימים לסינון: 204 "לא נמצאו מסמכים". גם אז חוזר data, עם total_count 0 ורשימה ריקה.
• 400 "שדה date_from מאוחר משדה date_to".
• 400 "טווח התאריכים המקסימלי הוא 366 ימים".
• 400 "שדה page_size חייב להיות בין 1 ל-500", ו-400 "שדה page חייב להיות 1 ומעלה".
• 400 "שדה customer_id לא תקין", למשל כשנשלח 0.

 

נסו את מערכת ביג בוס לניהול העסק ל-45 יום בחינם >>

ביטול מסמך: document_cancel

שולחים את סוג המסמך ואת המספר שלו, ואפשר להוסיף את סיבת הביטול ב-cancel_reason.

{
  "api_token": "<המפתח שלכם>",
  "document_type": 305,
  "document_number": 1052,
  "cancel_reason": "ההזמנה בוטלה באתר"
}

הביטול מפיק מסמך ביטול:

• חשבונית מס (305) – נוצרת חשבונית זיכוי (330) על אותו סכום. בהערות שלה נרשמת הסיבה, למשל: "לביטול חשבונית מס מס' 1052 – סיבת ביטול: ההזמנה בוטלה באתר".
• קבלה (400) – נוצר החזר תקבול (40).

בתשובה חוזרים is_cancelled 1 והרשימה cancel_documents. בכל מסמך ביטול יש סוג, מספר, מספר לקוח, sent_status, קישור צפייה ושדות מספר ההקצאה:

"data": {
  "document_type": 305,
  "document_number": 1052,
  "is_cancelled": 1,
  "cancel_documents": [
    { "document_type": 330, "document_number": 214, "customer_id": 4821, "sent_status": 0, "document_link": "https://www.bigboss.co.il/bigbossweb?vpid=...", "allocation_number": "", "allocation_status": 0 }
  ]
}

אחרי הביטול, document_get על המסמך המקורי מחזיר is_cancelled 1 ו-amount_open 0.

המדריך מתאר ביטול של חשבונית מס ושל קבלה. סוג שאינו נתמך בביטול נדחה ב-400, למשל החזר תקבול: "סוג מסמך לא נתמך – document_type: 40". לפני שמחברים ביטול אוטומטי של סוג מסמך אחר, כדאי לנסות אותו קודם על מסמך אחד.

 

ביטול שנשלח פעמיים: קוד 409

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

לכן אפשר לשלוח את אותו ביטול שוב בלי חשש: גם 200 וגם 409 אומרים שהמסמך מבוטל, ובשניהם מספר מסמך הביטול נמצא בתשובה.

 

הכול יחד: הזמנה שבוטלה באתר

1. שומרים את פרטי המסמך כבר ביצירה
כשהמסמך נוצר, שומרים לצד ההזמנה את document_type ואת document_number מהתשובה.

2. מבטלים
כשההזמנה מתבטלת, שולחים document_cancel עם אותו סוג ומספר, ועם הסיבה.

3. בודקים את התשובה
ב-200 או ב-409 שומרים לצד ההזמנה את מסמך הביטול מתוך cancel_documents. בכל קוד אחר רושמים את ההודעה ובודקים את המסמך בתוך ביג בוס.

וכדי לבדוק מה נוצר ללקוח מסוים, document_list עם התאריכים ועם customer_id מחזיר את המסמכים שלו, כל אחד עם ה-request_reference שלו, וכך משווים אותם להזמנות אצלכם.

 

מה הפעולות האלה לא עושות

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

 

איך ביג בוס עוזרת לסנכרן מסמכים עם המערכת שלכם, ומה היא לא עושה

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

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

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

נסו את מערכת ביג בוס לניהול העסק ל-45 יום בחינם >>

יש שאלה לפני שמתחילים? דברו איתנו

 

מדריכים נוספים

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

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