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

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

אתר שמציג "במלאי" או "אזל" צריך לדעת כמה יחידות יש באמת. דרך ה-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.

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

הפעולה עובדת רק על פריט שמנוהל במלאי. פריט שאינו מנוהל במלאי, או שלא קיים, מחזיר 204 עם ההודעה "פריט לא נמצא או לא מנוהל במלאי". האם פריט מנוהל במלאי נקבע בשדה managed_in_inventory: פריטים וקטגוריות דרך ה-API.

כמויות לכל הפריטים

הפעולה inventory_list מחזירה בקריאה אחת שורה לכל פריט פעיל שמנוהל במלאי, עם item_id, catalog_number, item_name, group_id והכמות. אפשר לצמצם לקטגוריה אחת בעזרת group_id. בלי תוצאות חוזרת ההודעה "לא נמצאו נתוני מלאי התואמים לסינון".

ברשימה מופיע הסה״כ בלבד, בלי פירוט לפי מחסן. כשצריך את הכמות בכל מחסן, שולפים את הפריט ב-inventory_get.

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

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

לפני שמחברים

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

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

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

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

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

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

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