כל מה שקראתם כאן, המערכת עושה בשבילכם בקליק
45 יום לנסות את ביג בוס בחינם. בלי כרטיס אשראי, בלי התקנה: מייל וסיסמה וזהו.
כמה יש במלאי, ובאיזה מחסן
אתר שמציג "במלאי" או "אזל" צריך לדעת כמה יחידות יש באמת. דרך ה-API האתר או מערכת אחרת שואלים את ביג בוס מה הכמות של פריט, ומקבלים את הסה״כ ואת הפירוט לפי מחסן. כך הלקוח באתר רואה את מה שרשום אצלכם במערכת.
המדריך מסביר את פעולות המלאי: שליפת כמויות, העברה בין מחסנים וספירת מלאי, מה חוזר בכל אחת ומה הן אינן עושות. מבנה הבקשה והתשובה הכללי מוסבר במדריך הקריאה הראשונה ל-API: מבנה הבקשה, התשובה וקודי התשובה.
מאיפה מגיעות הכמויות. הכמויות הן מה שרשום בניהול המלאי של ביג בוס, ולכן הן משקפות את המציאות רק כשמנהלים בו את המלאי בפועל, עם התוסף ניהול רכש ומלאי. ה-API קורא את הכמויות, ומזיז אותן רק דרך מסמכים, כמו העברה בין מחסנים וספירת מלאי.
כמות של פריט אחד
הפעולה inventory_get מקבלת item_id או catalog_number, ומחזירה את הכמות בכל המחסנים יחד ואת הפירוט לפי מחסן. כך נראית תשובה אמיתית לפריט דוגמה:
"data": {
"quantity": 35,
"warehouse_id": 0,
"warehouses": [
{ "warehouse_id": 5601, "warehouse_name": "מחסן סניף - דוגמה", "quantity": 9 },
{ "warehouse_id": 5600, "warehouse_name": "מחסן ראשי - דוגמה", "quantity": 26 }
],
"quatity": 35
}
- quantity: הסה״כ בכל המחסנים.
- warehouses: רשימת המחסנים, ולכל אחד המספר, השם והכמות בו.
- warehouse_id: 0 בתשובה הזו, כי הסה״כ הוא של כל המחסנים.
- quatity: אותו סה״כ, בשם הישן של השדה. הוא נשאר כדי שחיבורים ותיקים ימשיכו לעבוד. בחיבור חדש עובדים עם
quantity.
כמות במחסן אחד
כששולחים גם warehouse_id עם מספר המחסן, התשובה היא הכמות במחסן הזה בלבד: quantity היא הכמות בו, warehouse_id הוא המספר שלו, והרשימה warehouses חוזרת ריקה (null). בלי השדה, או עם 0, התשובה היא של כל המחסנים, כמו בדוגמה שלמעלה.
"data": {
"quantity": 9,
"warehouse_id": 5601,
"warehouses": null,
"quatity": 9
}
מחסן שלא קיים נדחה ב-400, וההודעה כוללת את המספר ששלחתם, למשל "מחסן 999999 לא נמצא". מספר שלילי נדחה ב-400 עם "שדה warehouse_id לא תקין".

דוגמת בקשה ותשובה אמיתיות: כמות המלאי של פריט, עם הסה״כ ועם הפירוט לפי מחסן.
הפעולה עובדת רק על פריט שמנוהל במלאי. פריט שאינו מנוהל במלאי, או שלא קיים, מחזיר 204 עם ההודעה "פריט לא נמצא או לא מנוהל במלאי". האם פריט מנוהל במלאי נקבע בשדה managed_in_inventory: פריטים וקטגוריות דרך ה-API.
כמויות לכל הפריטים
הפעולה inventory_list מחזירה בקריאה אחת שורה לכל פריט פעיל שמנוהל במלאי, עם item_id, catalog_number, item_name, group_id והכמות. אפשר לצמצם לקטגוריה אחת בעזרת group_id. בלי תוצאות חוזרת ההודעה "לא נמצאו נתוני מלאי התואמים לסינון".
ברשימה מופיע הסה״כ, בלי פירוט לפי מחסן. כששולחים warehouse_id, הרשימה מחזירה את הכמויות במחסן הזה. כשצריך את הכמות בכל המחסנים של פריט אחד, שולפים אותו ב-inventory_get.
העברה בין מחסנים וספירת מלאי
שתי פעולות מזיזות מלאי דרך ה-API, ושתיהן יוצרות מסמך בביג בוס, כמו העברה וספירה שעושים במסך. הן דורשות מפתח "קריאה וכתיבה".
העברה בין מחסנים: inventory_transfer
שולחים את מחסן המקור ב-source_warehouse_id, את מחסן היעד ב-destination_warehouse_id, ואת הפריטים ב-items, עם מק״ט וכמות בכל שורה. נוצר מסמך העברה (סוג 830), והמספר שלו חוזר בתשובה.
{
"api_token": "<המפתח שלכם>",
"source_warehouse_id": 7001,
"destination_warehouse_id": 7002,
"request_reference": "TRANSFER-1042",
"items": [
{ "catalog_number": "SKU-100", "quantity": 1 }
]
}
בבדיקה שלנו בקשה להעביר יותר ממה שיש במחסן המקור נדחתה ב-400, עם המק״ט, הכמות שיש והכמות שביקשנו: "אין מספיק מלאי במחסן המקור לפריט DEMO-003 (קיים: 9.00, מבוקש: 100.00)". העברה שנייה עם אותו request_reference נדחתה ב-400 "נמצא מסמך בעל אותו מזהה – request_reference", ולא נוצרה העברה כפולה.
ספירת מלאי: inventory_count
שולחים את המחסן ב-warehouse_id ואת הפריטים ב-items. השדה apply_as_delta קובע מה המספר אומר: עם 0 זו הכמות שנספרה, והמלאי במחסן נקבע לה. עם 1 זו תוספת לכמות שכבר יש. נוצר מסמך ספירה (סוג 840), ולכל פריט חוזרות הכמות לפני, הכמות אחרי וההפרש.
ערך אחר ב-apply_as_delta נדחה ב-400 "שדה apply_as_delta יכול להיות 0 או 1", וכמות שלילית בספירה רגילה נדחית ב-400 "כמות שנספרה לא יכולה להיות שלילית".
מה פעולות המלאי לא עושות
- אין כתיבה ישירה של כמויות דרך ה-API. מלאי זז רק דרך מסמך. העברה בין מחסנים וספירת מלאי הן מסמכים כאלה, כמו שמוסבר בסעיף הקודם, וגם מסמך שיש בו שורה עם מק״ט של פריט מנוהל מלאי מוריד או מוסיף מהמחסן של הפריט, לפי סוג המסמך. הפירוט ביצירת מסמך מכירה דרך ה-API: סוגים, שורות, מע״מ והנחה.
- אין הודעה על שינוי. ה-API עונה כשפונים אליו. כדי לקבל הודעה כשכמות של פריט משתנה, משתמשים בתוסף שליחת אירועים למערכות חיצוניות (Webhook), שהוא תוסף נפרד. ההודעה מכילה את השינוי בכמות וגם את היתרה, במחסן ובכל המחסנים יחד, והיא נשלחת גם בהעברה בין מחסנים ובסיום ספירת מלאי במסך. כדי לבדוק יתרה ברגע שצריכים אותה, שולפים אותה כאן, ב-
inventory_getאו ב-inventory_list.
לפני שמחברים
שלושה דברים כדאי לבדוק בביג בוס לפני שהאתר מתחיל לשאול על מלאי:
1. הפריטים מנוהלים במלאי
כל פריט שהאתר שואל עליו צריך להיות מסומן כמנוהל במלאי, אחרת חוזרת התשובה 204 במקום כמות.
2. הכמויות נרשמות בביג בוס
כמויות המלאי זזות רק דרך מסמכים בביג בוס, אלה שמפיקים מתוך המערכת ואלה שנוצרים דרך ה-API. סחורה שלא נרשמה במסמך לא תופיע בתשובה.
3. המק״טים זהים
כשהמק״ט של מוצר באתר זהה למק״ט שלו בביג בוס, האתר יכול לשאול לפי catalog_number בלי לשמור אצלו את מספר הפריט.
איך משתמשים בזה באתר
הדרך הישירה היא שהאתר שואל על פריט ברגע שהוא צריך אותו, למשל כשגולש פותח עמוד מוצר או מוסיף לסל. כשצריך תמונה של כל המלאי, למשל כדי לעדכן את רשימת המוצרים באתר, שולחים inventory_list ומעדכנים את כל הפריטים בבת אחת. את התדירות קובעים בצד שלכם, לפי מה שהאתר צריך.
מה בדיוק יש בהודעת המלאי שביג בוס שולחת, ואיך משלבים אותה עם השליפה: הודעת מלאי: מה המספר אומר.
כל שכבת המדריכים מרוכזת בעמוד ממשק API בביג בוס.