הצגת קידומות לאזור

לפני שמתחילים

בחרו אזור באמצעות getareas. העתיקו את מזהה האזור מהתגובה או מהערך המוחזר של next_function. עבור אזור בארצות הברית או בקנדה, השתמשו ב־getstates אם ברצונכם לצמצם את התוצאות למדינה או לפרובינציה אחת.

קריאת התוצאה

בדקו את status.code בגוף ה־JSON וגם את סטטוס ה־HTTP. תוצאות מוצלחות נמצאות במערך response. כברירת מחדל, התגובה ממוינת לפי שם. available הוא אומדן, ודגלי הקטלוג אינם מחליפים בדיקה של היכולות בפועל ושל דרישות הרישום של המספר שנבחר.

בחירת השלב הבא

השתמשו בתוצאה ללא קיבוץ. כאשר returns_numbers הוא 1, הערך המוחזר של next_function מפנה לחיפוש מספרים. כאשר הערך הוא 0, המספרים מוקצים בעת ההזמנה והנתיב מפנה לפעולת הזמנה. בדקו את הפעולה ואת דרישותיה לפני שליחת הבקשה: בקשת הזמנה עלולה לחייב את חשבונכם. אל תשלחו באופן אוטומטי בקשות לכל נתיב שמוחזר.

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

אפשרויות תצוגה מתקדמות

compact=1 מחזיר מדגם בסדר אקראי של עד 100 שורות, ולא עמוד מתוך קבוצת תוצאות גדולה יותר. קיבוץ יוצר שורות סיכום ומזהים סינתטיים; השתמשו בתגובה רגילה ללא קיבוץ כדי לבחור קידומת בודדת. אל תסתמכו על תוצאות מדגמיות או מקובצות כדי לטעון שהמלאי מוצג במלואו או שהיכולות מדויקות.

בקשה

השתמשו בפרטי ההזדהות של חשבון ה־API הפעיל שלכם דרך HTTPS. יש תמיכה באימות Basic ובאסימוני bearer פעילים של חשבון ה־API; מגבלות החשבון חלות.

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

curl --fail-with-body --silent --show-error \
  --user "$API_USER:$API_PASSWORD" \
  "https://api.multitel.net/v3/getprefixes/$AREA_ID?state=NY"

תגובה

מעטפת ה־JSON הסטנדרטית של status/response. השדה status.results מציין את מספר השורות שהוחזרו, גם כאשר הופעלו דגימה או קיבוץ. השדה response מכיל אובייקטים של קידומות. לא מוחזרים שדות מחיר. בתגובה הרגילה ללא קיבוץ, uuid הוא מזהה הקידומת; area_uuid ו־country_uuid הם מזהים המוחזרים בתגובה; prefix ו־name הם מידע לתצוגה; available הוא אומדן זמינות ולא שמירת מספר; needs_registration ו־restrictions מתארים מידע על הרישום; sms_coverage, is_mobile ו־number_type הם רמזים מהקטלוג, ולא הבטחה ליכולת מסוימת של מספר. השדה number_type עשוי להיות ריק או להכיל מחרוזת אחרת מהקטלוג, ולכן אין לדרוש שיהיה מתוך קבוצת ערכים קבועה. השדה state הוא מחרוזת ועשוי להיות ריק או להכיל עיצוב מהקטלוג. השדות latitude ו־longitude עשויים להיות ריקים. השדות metered ו־overflow הם דגלי קטלוג ולא סכומי כסף. השדה returns_numbers בוחר נתיב להצגת רשימת מספרים (1) או נתיב להקצאה בעת ההזמנה (0). השדה next_function מזהה את הנתיב הבא הזה. תגובות מקובצות מכילות בנוסף מאפיינים ממוזגים, לרבות ערכי מאפיינים המשמשים כחלופה כשאין ערך זמין; אין לפרש אותם כיכולות מאומתות של כל מספר.

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

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "uuid": "PREFIX_ID_FROM_RESPONSE",
      "area_uuid": "AREA_ID_FROM_RESPONSE",
      "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
      "prefix": "+1212",
      "name": "Example area",
      "metered": 0,
      "overflow": 0,
      "needs_registration": 0,
      "restrictions": "",
      "state": "NY",
      "country_iso": "US",
      "is_mobile": 0,
      "number_type": "local",
      "latitude": "",
      "longitude": "",
      "available": 12,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "next_function": "v3/getnumbers/PREFIX_ID_FROM_RESPONSE"
    }
  ]
}

שגיאות

• 404: Invalid area ID: קבלו מזהה אזור עדכני בתהליך בירור האפשרויות.
• 404: State filter is only available for US and CA: השמיטו את state עבור ארצות אחרות.
• 404: Invalid state: השתמשו במדינה או בפרובינציה שהוחזרה על ידי getstates עבור ארץ זו.
• 404: No prefixes found: לא הוחזרו שורות תואמות מהקטלוג. אין בכך הוכחה שלעולם לא ניתן יהיה להזמין מספר מסוים.
• 500: שגיאה: 'Failed loading prefixes': החיפוש בקטלוג נכשל. נסו שוב מאוחר יותר ופנו לתמיכה אם התקלה נמשכת.

זמינות והשפעות נלוות

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