כל מה שקראתם כאן, המערכת עושה בשבילכם בקליק
45 יום לנסות את ביג בוס בחינם. בלי כרטיס אשראי, בלי התקנה: מייל וסיסמה וזהו.
מה נשלח לביג בוס, ומה חוזר
המדריך הזה מיועד בעיקר למפתח/ת שבונה את החיבור, אבל כדאי שגם בעלי העסק יכירו אותו. הוא מראה מה בדיוק נשלח לביג בוס ומה חוזר בתשובה, וכך הודעת שגיאה מהמערכת המתחברת הופכת למשהו שאפשר להבין ולטפל בו.
לפני שמתחילים צריך מפתח גישה פעיל. איך יוצרים אותו: הפעלת ממשק ה-API ויצירת מפתח גישה ראשון.
הבקשה
כל הבקשות נשלחות באותה צורה:
- שיטה:
POST, לכתובת השרת ובסופה שם הפעולה, למשלhttps://www.bigboss.co.il/bigbossweb/Api.asmx/customer_get. - כותרת:
Content-Type: application/json; charset=utf-8. - גוף: JSON שכולל תמיד את השדה
api_tokenעם המפתח, ולצדו השדות של הפעולה. המפתח נשלח בגוף הבקשה, לא בכתובת.
כך נראית בקשה לשליפת כרטיס לקוח לפי מספר. במקום xxxxxxxx מדביקים את המפתח:
POST https://www.bigboss.co.il/bigbossweb/Api.asmx/customer_get
Content-Type: application/json; charset=utf-8
{
"api_token": "xxxxxxxx",
"customer_id": 5608
}
את המפתח מעתיקים פעם אחת, כשהוא נוצר: בחלון "המפתח נשמר", או בחלון "המפתח הוחלף" אחרי החלפה. ברשימה ובטופס המזהה הוא מוסתר.

"רש' מזהים": בעמודה "מפתח Api" המפתח מוסתר, ולצדו "הרשאה" ו"שימוש אחרון". את המפתח המלא, שנשלח בשדה api_token, מעתיקים רק פעם אחת, בחלון שנפתח אחרי השמירה. מעל הרשימה: הכרטיס של סביבת הבדיקה.
התשובה
התשובה היא תמיד JSON עם שלושה שדות: result_code, קוד שאומר אם הבקשה הצליחה, result_message, הודעה בעברית או "OK", ו-data, התוכן עצמו. בהצלחה, data מכיל את מה שביקשתם. בשגיאה הוא ריק (null).
{
"result_code": 200,
"result_message": "OK",
"data": {
"customer_id": 5608,
"company_name": "לקוח דוגמה - API",
"city": "עיר דוגמה",
...
}
}
התשובה המלאה לשליפת לקוח כוללת 14 שדות, והם מפורטים בלקוחות דרך ה-API: הוספה, עדכון, שליפה ויתרה. כרטיס שלא קיים מחזיר:
{
"result_code": 204,
"result_message": "כרטיס לא נמצא",
"data": null
}
תשובות רגילות, גם כשיש בהן שגיאה, מגיעות ב-HTTP 200. ההצלחה או השגיאה נקבעות בשדה result_code, ולכן הקוד שלכם בודק אותו ולא רק את קוד ה-HTTP. אם הבקשה מציינת שהיא מקבלת תשובה דחוסה (GZIP), התשובה נשלחת דחוסה.
תקלה לא צפויה בשרת עלולה לחזור כ-HTTP 500, בלי
result_codeובמבנה אחר. הקוד שלכם צריך לטפל גם במקרה הזה: לרשום את התקלה, ולא להניח שהפעולה הצליחה.

דוגמת בקשה ותשובה אמיתיות: הבקשה, הכותרת והתשובה המלאה, עם result_code, result_message ו-data.
קודי התשובה
| result_code | מה זה אומר |
|---|---|
| 200 | הצלחה, גם ביצירה של לקוח, פריט, קטגוריה או מסמך |
| 204 | לא נמצאו נתונים: שליפה או רשימה בלי תוצאות |
| 400 | הבקשה לא תקינה: שדה חסר או שגוי, JSON שבור, או בקשה בלי מפתח |
| 401 | בעיית זיהוי: המפתח שגוי, מושבת או נמחק, או שהמשתמש שלו אינו פעיל |
| 403 | הפעולה לא מותרת: מפתח "קריאה בלבד" ששולח פעולה שמשנה נתונים ("מפתח זה מוגדר לקריאה בלבד"), או פעולה שדורשת תוסף נוסף שאינו פעיל, למשל ספקים בלי תוסף מעקב הוצאות |
| 404 | עדכון של רשומה שלא נמצאה או שמוגדרת כלא פעילה |
| 409 | כפילות בהוספה: לקוח עם אותו ח.פ., פריט עם אותו מק״ט או קטגוריה עם אותו שם. וגם ביטול של מסמך שכבר בוטל: "המסמך כבר מבוטל", ובתשובה מסמכי הביטול מהפעם הראשונה. כך גם ספק עם ח.פ. שכבר קיים, הוצאה עם אסמכתא שכבר נרשמה השנה לאותו ספק, תשלום לספק עם request_reference שכבר נרשם, משימה שכבר בוצעה והרשמה ל-Webhook שכבר קיימת |
| 429 | יותר מדי בקשות בדקה: מחכים את מספר השניות שב-retry_after_seconds ושולחים שוב (הפירוט מתחת לטבלה) |
| 500 | שגיאה פנימית בעיבוד הבקשה, עם הודעה כמו "שגיאת פרמטרים פנימית" |
מגבלת קצב. מפתח אחד יכול לשלוח עד 120 בקשות בדקה, ועד 30 בקשות בדקה שנדחו. מעבר לזה חוזר result_code 429, גם הוא ב-HTTP 200, עם ההודעה "חרגת ממספר הבקשות המותר לדקה", או "חרגת ממספר הבקשות השגויות המותר לדקה – יש לבדוק את הבקשות ולנסות שוב" כשהרבה בקשות נדחו. בתוך data חוזר retry_after_seconds: כמה שניות לחכות לפני הבקשה הבאה. תשובת 204, "לא נמצא", לא נספרת כבקשה שנדחתה.
הודעות זיהוי נפוצות
| ההודעה | קוד | מה לבדוק |
|---|---|---|
| "חסר אסימון הרשאה" | 400 | הבקשה נשלחה בלי השדה api_token |
| "קוד הזדהות לא תקין" | 401 | הערך שנשלח אינו במבנה של מפתח, למשל טקסט אחר שהודבק במקום המפתח |
| "נתוני הזדהות שגויים" | 401 | אין מפתח כזה: מפתח עם טעות העתקה, או מפתח של מזהה שנמחק |
| "קוד הזדהות אינו פעיל" | 401 | המזהה הועבר ל"לא פעיל" |
| "המשתמש אינו פעיל" | 401 | המשתמש שיצר את המפתח הושבת |
| "מפתח זה מוגדר לקריאה בלבד" | 403 | המפתח מוגדר "קריאה בלבד", והפעולה משנה נתונים. שולחים אותה במפתח "קריאה וכתיבה", או משנים את ההרשאה בטופס המזהה |
| "מפתח זה אינו מורשה לשלוח מסמכים ללקוחות" | 403 | מפתח שאינו בהרשאה לשליחה קרא ל-document_send. בוחרים בהרשאה "קריאה, כתיבה ושליחה ללקוחות" במסך "ניהול ממשק Api" |
| "לא הועברו נתונים" | 400 | גוף הבקשה ריק |
| "מבנה JSON לא תקין" | 400 | ה-JSON שבור, למשל פסיק מיותר אחרי השדה האחרון, או שבגוף הבקשה יש רק null |
קריאה ראשונה מומלצת
כדי לבדוק שהחיבור עובד, מתחילים בפעולה שרק קוראת נתונים, ואפשר לעשות את זה גם במפתח "קריאה בלבד". company_info מחזירה את שם החברה, סוג העוסק, הרשאת המפתח (key_scope), האם הוא יכול לשלוח מסמכים ללקוחות (can_send_to_customers) ואילו מודולים פעילים (modules), וכך רואים מה מותר למפתח הזה. itemgroup_list מקבלת רק את api_token ומחזירה את כל קטגוריות הפריטים הפעילות, כל אחת עם group_id ו-group_name. פעולות שליפה אינן משנות דבר. פעולות יצירה כן: מסמך שנוצר דרך ה-API הוא מסמך סופי וממוספר, חוץ מטיוטה (document_draft_new), שנשמרת עם מספר זמני שלילי ואינה מסמך סופי.
השדות של כל פעולה מפורטים במדריכים לפי תחום: לקוחות, פריטים וקטגוריות, מלאי, מסמכים, ספקים והוצאות, ולידים ומשימות. מבנה התשובה וקודי התשובה מתוארים כאן כפי שהממשק מחזיר אותם היום.
שני כלים עוזרים כשבונים את החיבור: סביבת בדיקה, שבה בודקים בלי לגעת בנתונים האמיתיים, ו"יומן קריאות Api", שבו רואים מה כל מפתח שלח ומה ביג בוס ענתה.
כל שכבת המדריכים מרוכזת בעמוד ממשק API בביג בוס.