הקריאה הראשונה ל-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" מעתיק את המפתח שנשלח בשדה 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.

קודי התשובה

הודעות זיהוי נפוצות

קריאה ראשונה מומלצת

כדי לבדוק שהחיבור עובד, מתחילים בפעולה שרק קוראת נתונים. itemgroup_list מקבלת רק את api_token ומחזירה את כל קטגוריות הפריטים הפעילות, כל אחת עם group_id ו-group_name. פעולות שליפה אינן משנות דבר. פעולות יצירה כן: מסמך שנוצר דרך ה-API הוא מסמך סופי וממוספר.

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

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