אימות ותגובות API

השתמשו בפרטי התחברות ל־API

שלחו בקשות v3 דרך HTTPS אל https://api.multitel.net. כל נקודת קצה במדריך זה דורשת אימות. שמרו את פרטי ההתחברות בשרת שלכם, ולעולם אל תשימו אותם בקוד JavaScript שרץ בדפדפן, בדפים ציבוריים, בצילומי מסך או במערכות בקרת גרסאות.

השתמשו באחת מצורות האישורים הבאות:

• HTTP Basic עם שם המשתמש והסיסמה של API שהוגדרו עבור חשבון MultiTEL שלכם.
• אסימון Bearer בכותרת Authorization: Bearer YOUR_API_TOKEN, עבור חשבון API מופעל שהוגדר לאימות אסימונים. בקשות אסימון מתקבלות רק מכתובות המורשות עבור אותו חשבון.

אם רשימת היתרים של IP הוגדרה עבור חשבון API שלכם, שלחו את כל הבקשות מכתובות מורשות.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getcountries'

curl --header "Authorization: Bearer $API_TOKEN" 'https://api.multitel.net/v3/getcountries'

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

טיפול בכשלי אימות

כשלי אימות נשלחים עם סטטוס HTTP 401. הגוף משתמש במעטפת הסטנדרטית, עם status.code מוגדר ל 401 ומחרוזת ריקה בתור response.

• אין פרטי התחברות: status.msg הוא Username and password are required, והתגובה כוללת אתגר אימות מסוג Basic.
• אסימון Bearer נדחה: אם הכותרת Authorization משתמשת בסכימה Bearer והאסימון אינו מוכר, מושבת או אינו מורשה מהכתובת שלכם, status.msg הוא Invalid bearer token. לא מנסים פרטי התחברות אחרים כאשר כותרת Bearer קיימת.
• פרטי התחברות מסוג Basic לא תקינים: status.msg מתחיל ב A valid username and password pair are required., והתגובה כוללת אתגר אימות מסוג Basic. ההודעה יכולה להכיל טקסט אבחון נוסף, לכן אל תנתחו אותה באמצעות קוד.

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

קריאת גוף התגובה

רוב נקודות הקצה של v3, כולל getcountries, getstates, getareas ו other, מחזירות JSON במעטפת זו:

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "countrycode": "1",
      "name": "United States",
      "description": "United States",
      "isocode": "US",
      "is_mobile": 0,
      "sms_coverage": 1,
      "latitude": "38.0000",
      "longitude": "-97.0000",
      "next_function": "v3/getareas/US"
    }
  ]
}

זוהי תגובת רשימת מדינות להמחשה בלבד, ולא הצהרה על המלאי או היכולות העדכניים.

תגובת שגיאה נראית כך:

{
  "status": {
    "code": 404,
    "msg": "No areas found"
  },
  "response": ""
}

אם לא ניתן לקודד תגובה, הגוף מכיל status.code 500, status.msg Response encoding error, ואובייקט ריק בתור response.

נקודת הקצה הישנה GET /v3/countries מחזירה {"code": 200, "data": [...]} במקום זאת. בדקו את התגובה המתועדת של כל נקודת קצה. אם גוף אינו JSON תקין, למשל לאחר כשל שרת בלתי צפוי, התייחסו לבקשה כאל כושלת ונסו שוב מאוחר יותר.

קודי תוצאה של API וסטטוס HTTP

status.code הוא קוד התוצאה של API. הוא אינו הסטטוס של HTTP. כשלי אימות נשלחים עם HTTP 401. אחרת, נקודות הקצה לגילוי מדווחות על תוצאות כגון 404 ו 500 רק ב status.code ואינן מגדירות סטטוס HTTP תואם. תוצאת לא-נמצא או פרמטר-חסר יכולה לכן להגיע עם סטטוס HTTP מוצלח. תמיד בדקו status.code לפני השימוש ב response.

קוד תוצאה 500 עם ההודעה ISO Code parameter is required אומר שפרמטר נדרש חסר. תקנו את הבקשה במקום להתייחס אליה כאל השבתת שרת.

מעקב אחר next_function

תוצאות הגילוי כוללות next_function. זהו נתיב יחסי ללא לוכסן מוביל, לפעמים עם מחרוזת שאילתה, כגון v3/getareas/US או v3/getareas/US?state=NY. הוסיפו לפניו את https://api.multitel.net/ כדי לבנות את הבקשה הבאה, ואמתו בקשה זו באותו אופן. מסננים אופציונליים ששלחתם, כגון pid, אינם מועברים אל next_function. הוסיפו אותם שוב אם אתם צריכים אותם.

בורר מלאי אופציונלי (pid)

getcountries, getstates ו getareas מקבלות פרמטר שאילתה אופציונלי pid שמצמצם תוצאות למקור מלאי אחד. השתמשו בו רק עם ערך שסופק על ידי MultiTEL, בצורתו המספרית או בצורתו ההקסדצימלית בת 32 התווים. השמיטו אותו לשימוש רגיל. שלחו pid במחרוזת השאילתה. אם נקודת הקצה אינה מזהה או מקבלת את הערך, היא מתעלמת ממנו ללא שגיאה, והבקשה מתנהגת כאילו pid הושמט.

הפרדה בין גילוי להזמנות

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

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