הקריאה הראשונה ל-API: מבנה הבקשה, התשובה וקודי התשובה

כל מה שקראתם כאן, המערכת עושה בשבילכם בקליק

45 יום לנסות את ביג בוס בחינם. בלי כרטיס אשראי, בלי התקנה: מייל וסיסמה וזהו.

פתחו חשבון: 45 יום חינם
מדריך למשתמש לתוסף ממשק API בביג בוס

מה נשלח לביג בוס, ומה חוזר

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

לפני שמתחילים צריך מפתח גישה פעיל. איך יוצרים אותו: הפעלת ממשק ה-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 ובמבנה אחר. הקוד שלכם צריך לטפל גם במקרה הזה: לרשום את התקלה, ולא להניח שהפעולה הצליחה.

 

פלט של שתי קריאות אמיתיות לממשק ה-API של ביג בוס עם הבקשה, הכותרת והתשובה המלאה של כל קריאה

דוגמת בקשה ותשובה אמיתיות: הבקשה, הכותרת והתשובה המלאה, עם 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 בביג בוס.

 

לא הצטרפת עדיין?
לא מצאת את מה שחיפשת?
ביג בוס תמיכה

כשצריך עזרה – אנחנו איתך!

צוות התמיכה שלנו ישמח

לעמוד לרשותך כאן

עוד מדריכים עבור ממשק API
עוד מאמרים עבור ממשק API

45 ימי הניסיון בחינם שלך מתחילים ביצירת חשבון :)

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

🔒 הפרטים מוצפנים ומאובטחים

- נרשמים עכשיו ומתחילים -

45 יום מלאים בלי כרטיס אשראי בלי התחייבות