Webhook – מפרט טכני

Webhook מפרט טכני

כעת נתעמק בצד הטכני של התוסף שליחת אירועים למערכות חיצוניות (Webhook) של ביג בוס.

בדף זה נתאר את מבנה הנתונים (Payload) שביג בוס שולחת עבור כל אחד מסוגי האירועים, ואת צורת הבקשה עצמה.

הבקשה

• שיטה: POST לכתובת שהוגדרה באירוע, בשדה "כתובת נקודת הקצה", שחייבת להתחיל ב-https.
• כותרות: Content-Type: application/json (UTF-8), ו-Authorization: Bearer עם הערך שהוקלד בשדה "מפתח Api" של האירוע.
• גוף: אובייקט JSON מוזח עם נתוני הרשומה בלבד. אין בו שם אירוע, מזהה אירוע או זמן שליחה, ולכן כדי להבחין בין סוגים משתמשים בכתובת נפרדת לכל סוג, או בפרמטר שמוסיפים לכתובת (למשל ?type=lead-added), שמגיע שלם.
• מזהים נשלחים כמספרים, סכומים עם נקודה עשרונית (למשל 59.0), ותאריכים בפורמט 2026-10-06T15:19:20, בשעון ישראל ובלי אזור זמן.
• תשובה: קוד 2xx תוך 15 שניות. תוכן התשובה לא נקרא, והפניה (301 או 302) נחשבת כישלון.
• ניסיונות חוזרים: כשאין תשובת הצלחה, ביג בוס מנסה שוב אחרי כדקה ואחרי עוד כ-5 דקות, שלושה ניסיונות בסך הכול. ייתכן שאותה הודעה תגיע פעמיים, ולכן מזהים כפילויות לפי המזהה (lead_id, customer_id, document_id). אין הבטחה שההודעות יגיעו לפי הסדר.

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

– הקמה \ עדכון \ מחיקה של ליד

– הקמה \ עדכון \ מחיקה של לקוח

– הקמה \ עדכון \ מחיקה של ספק

– הקמה \ עדכון \ מחיקה של פריט

– עדכון של מלאי

– הפקת מסמך

ליד – פרטי הנתונים

להלן ה-Payload שנשלח בהוספה, בעדכון ובמחיקה של ליד. במחיקה נשלחים הערכים שהיו בכרטיס לפני המחיקה.

דוגמא של נתונים:

{
  "lead_id": 1234,
  "company_name": "שם החברה",
  "contact_name": "שם איש הקשר",
  "address": "כתובת",
  "city": "עיר",
  "zip": "מיקוד",
  "tel": "+972501234567",
  "cel": "+972521234567",
  "email": "[email protected]",
  "comments": "הערות חופשיות"
}

לקוח \ ספק – פרטי הנתונים

להלן ה-Payload שנשלח בהוספה, בעדכון ובמחיקה של לקוח ושל ספק. סימון לקוח כ"לא פעיל" שולח הודעת עדכון רגילה, ואין בה שדה שמציין זאת.

דוגמא של נתונים:

{
  "customer_id": 5678,
  "company_hp": "123456789",
  "company_name": "שם החברה",
  "contact_name": "שם איש הקשר",
  "address": "כתובת",
  "city": "עיר",
  "zip": "מיקוד",
  "tel": "+97236123456",
  "cel": "+972521234567",
  "email": "[email protected]",
  "comments": "הערות חופשיות",
  "account_code": "AC12345",
  "vat_exemption": 1
}

פריט – פרטי הנתונים

להלן ה-Payload אשר יישלח עבור כל הפעילויות מול פריט:

דוגמא של נתונים:

{
  "item_id": 3456,
  "item_name": "שם הפריט",
  "catalog_number": "123-ABC",
  "barcode": "7290001234567",
  "group_id": 10,
  "group_name": "קטגוריית פריטים",
  "price_buy_nis": 12.34,
  "price_sell": 23.45,
  "price_sell_matvea_id": 2,
  "price_sell_matvea_code": "NIS",
  "price_sell_vat_included": 1,
  "image_url": "",
  "extended_description": "תיאור מורחב של הפריט",
  "managed_in_inventory": 1,
  "inventory_min_qtty": 2.5,
  "inventory_max_qtty": 100.0
}

מלאי- פרטי הנתונים

להלן ה-Payload שנשלח כשכמות של פריט משתנה במחסן (סוג האירוע "עדכון מלאי"), הודעה נפרדת לכל פריט ומחסן. השדה item_name נשלח היום ריק, ובעדכון כמות ידני ובייבוא group_name מגיע כ"לא מוגדר". את היתרה עצמה שולפים בתוסף ממשק ה-API. ההסבר המלא: הודעת מלאי: מה המספר אומר.

דוגמא של נתונים:

{
  "item_id": 3456,
  "catalog_number": "123-ABC",
  "item_name": "שם הפריט",
  "group_id": 10,
  "group_name": "קטגוריית פריטים",
  "warehouse_id": 2,
  "warehouse_name": "מחסן מרכזי",
  "quantity": -2.0, "quatity": -2.0
}

מסמך – פרטים בעת הפקת מסמך

להלן ה-Payload שנשלח כשמופק מסמך מכירה סופי (סוג האירוע "הפקת מסמך"). טיוטה, מסמכי רכש והוצאה וביטול מסמך לא שולחים הודעה, ועריכה והפקה חוזרת של מסמך שעדיין פתוח לעריכה שולחת את ההודעה שוב עם אותו document_id. פרטי הלקוח בהודעה הם אלה שבמסמך. ההסבר המלא: הודעת מסמך: מה נשלח בהפקה, בעריכה ובביטול.

עבור שורות המסמך:

עבור שורות התקבול במסמך:

{
"document_id": 9876,
"document_type": 3,
"document_number": 4512,
"document_date": "2025-07-31T14:26:00",
"due_date": "2025-08-30T14:26:00",
"company_id": 5678,
"company_hp": "523456789",
"company_name": "שם החברה",
"contact_name": "שם איש הקשר",
"address": "רחוב X 1, חולון",
"city": "חולון",
"tel": "+97236111111",
"cel": "+972521234567",
"email": "[email protected]",
"document_vat_type": 2,
"discount_percentage": 5.0,
"discount_amount": 120.50,
"maam_percentage": 17.0,
"amount_maam": 273.85,
"amount_total": 1889.35,
"items": [
{
"line_number": 1,
"catalog_number": "123-ABC",
"description": "תיאור פריט",
"quantity": 2.0,
"price_unit": 250.00,
"discount_percentage": 5.0,
"amount_discount": 25.00,
"matvea_code": "NIS",
"exchange_rate": 1.0000,
"price_nis": 475.00
}
],
"payments": [
{
"line_number": 1,
"payment_type": 1,
"amount_nis": 1889.35,
"due_date": "2025-08-05T14:26:00",
"bank_code": 12,
"branch_number": "01",
"bank_account_number": "1234567",
"cheque_number": "3456789",
"credit_card_id": null,
"credit_card_number": null
}
]
}

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