משיכת כמויות מלאי למערכת חיצונית

כמה יש במלאי, ובאיזה מחסן

אתר שמציג "במלאי" או "אזל" צריך לדעת כמה יחידות יש באמת. דרך ה-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. מלאי זז רק דרך מסמך: מסמך שיש בו שורה עם מק״ט של פריט מנוהל מלאי מוריד או מוסיף מהמחסן של הפריט, לפי סוג המסמך. הפירוט ביצירת מסמך מכירה דרך ה-API: סוגים, שורות, מע״מ והנחה.
• אין הודעה על שינוי. ה-API עונה כשפונים אליו. כדי לקבל הודעה כשכמות של פריט משתנה, משתמשים בתוסף שליחת אירועים למערכות חיצוניות (Webhook), שהוא תוסף נפרד. ההודעה מכילה את השינוי בכמות ולא את היתרה, והעברה בין מחסנים או ספירת מלאי שנסגרת במסך לא שולחות אותה. את היתרה עצמה שולפים כאן, ב-inventory_get.

לפני שמחברים

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

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

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

3. המק״טים זהים
כשהמק״ט של מוצר באתר זהה למק״ט שלו בביג בוס, האתר יכול לשאול לפי catalog_number בלי לשמור אצלו את מספר הפריט.

איך משתמשים בזה באתר

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

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

כל שכבת המדריכים מרוכזת בעמוד ממשק API בביג בוס.