הצגת סוגי מספרים מיוחדים ומחיריהם במדינה

ניתן לאתר מספרים מקומיים באמצעות getcountries ו־getareas. עבור מספרים ארציים, מספרי חינם, מספרים בעלות משותפת, מספרים גלובליים ומספרים ניידים, קראו ל־other עם קוד ה־ISO של המדינה.

• הקבוצות מופיעות בסדר קבוע, וקבוצות שאין בהן רשומות אינן נכללות.
• בכל רשומה מפורטות תוכניות התמחור של חשבונכם בשדה prices. בחרו תוכנית לפי הערכים שלה בשדות channels, monthly_price, setup_price, per_minute ו־free_minutes, ושמרו את הערך שלה בשדה price_id לצורך הזמנה כאשר נקודת הקצה להזמנה דורשת אותו.
• אם הערך של needs_registration נחשב לאמת בהקשר בוליאני, קראו את restrictions לפני ההזמנה. התייחסו לטקסט זה כתוכן לתצוגה שאינו מהימן.
• פעלו לפי next_function: v3/getnumbers/{uuid} מאפשר לבחור מספר מסוים, ואילו v3/order/{uuid} מבצע הזמנה ישירות מהרשומה.
• רשימת response ריקה עם הקוד 200 מציינת שלא נמצאו סוגי מספרים מיוחדים בעת הבקשה. אם הקטלוג לא היה נגיש באופן זמני, התשובה עלולה להיות חלקית או לא להיות בפורמט JSON תקין, ולכן יש לנסות שוב מאוחר יותר.
• עבור מדינות שאינן בקטלוג מוחזר הקוד 404 ללא קוד מצב HTTP תואם. בדקו תמיד את status.code.

בקשה

נדרש: אימות HTTP Basic או אסימון Bearer (ראו אימות ותשובות API). אם האימות נכשל, מוחזרת תשובת HTTP 401 לפני ביצוע החיפוש.

GET עם isocode בנתיב. אם מקטע הנתיב אינו נכלל, נקרא במקומו שדה isocode בקידוד טופס.

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

תשובה

מעטפת תשובה תקנית. בהצלחה, status.code הוא 200, status.msg ריק, ו־status.results הוא מספר הקבוצות. response הוא רשימת קבוצות. שדות הקבוצה: group_key (מפתח סוג מנורמל: national, tollfree, sharedcost, global, mobile, או מפתח אחר המורכב מאותיות קטנות וספרות); group_name (שם לתצוגה); group_type_uuid (מזהה אטום של הסוג); items. סדר הקבוצות הוא national, tollfree, sharedcost, global, mobile, ולאחר מכן מפתחות אחרים לפי group_name. קבוצות ללא items אינן נכללות, וגם הסוג המקומי אינו נכלל. עבור US, קבוצת המספרים הניידים אינה נכללת אלא אם חשבונכם מורשה להשתמש במספרים ניידים של US. הפריטים ממוינים לפי name (ללא הבחנה בין אותיות גדולות לקטנות), ולאחר מכן לפי prefix. שדות הפריט: uuid (מזהה אטום של הרשומה המשמש ב־next_function); area_uuid (מזהה אטום של קבוצת הקטלוג); country_uuid (מזהה אטום של המדינה); prefix (קידומת מלאה המתחילה ב־'+' ובקוד החיוג של המדינה); name (השם בקטלוג; תווי מירכאות עשויים להופיע עם לוכסן הפוך לפניהם כתו מילוט); metered, overflow ו־needs_registration (דגלים שעשויים להיות מסוג boolean או number; התייחסו לכל ערך הנחשב לאמת בהקשר בוליאני כאל כן); restrictions (ריק כאשר אין צורך ברישום, ואחרת מכיל טקסט דרישות שעשוי לכלול מעברי שורה ב־HTML וקישור, מירכאות סביב הטקסט ותווים עם סימני מילוט; התייחסו אליו כטקסט לתצוגה שאינו מהימן); state (עבור US, CA ו־PR, קוד של מדינה או פרובינציה בתוך הארץ, או רשימה ריקה כאשר קוד כזה אינו ידוע; עבור ארצות אחרות, קוד ה־ISO של הארץ); country_iso; is_mobile (1 בקבוצת המספרים הניידים, ואחרת 0); number_type (זהה ל־group_key); available (כמות מסוג integer המדווחת בקטלוג עבור הרשומה, 0 כאשר אינה מדווחת); sms_coverage (1 אם תכונה כלשהי מזכירה SMS או MMS); returns_numbers (1 כאשר ניתן להציג רשימה של מספרים מסוימים); next_function ('v3/getnumbers/{uuid}' כאשר returns_numbers הוא 1, ואחרת 'v3/order/{uuid}'); prices; features (רשימת מחרוזות המתארות יכולות); group_key; group_type_uuid. כל רשומה ב־prices כוללת price_id (מזהה אטום של התוכנית), is_customer_custom (true כאשר חל תמחור מותאם אישית לחשבונכם; רק עבור תוכניות ללא ערוצים כלולים), per_minute ו־free_minutes (מחרוזות של מספרים עשרוניים), setup_price ו־monthly_price (מחרוזות עם שתי ספרות אחרי הנקודה העשרונית), ו־channels (מספר הערוצים הכלולים, מסוג integer). רשומות שאין להן אף תוכנית תמחור אינן נכללות. בכל בקשה נבחנות לכל היותר 1000 רשומות קטלוג לכל סוג מספר. אם אין רשומות באף סוג, response הוא רשימה ריקה עם status.results שערכו 0. אם החיפוש בזמן אמת בקטלוג נכשל, ייתכן שהתשובה לא תשתמש במעטפת זו, או שיחסרו קבוצות.

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

{
  "status": {
    "code": 200,
    "msg": "",
    "results": 1
  },
  "response": [
    {
      "group_key": "tollfree",
      "group_name": "Toll-free",
      "group_type_uuid": "00000000-0000-4000-8000-0000000000a1",
      "items": [
        {
          "uuid": "0000000000000000000000000000b001",
          "area_uuid": "0000000000000000000000000000a001",
          "country_uuid": "0000000000000000000000000000c001",
          "prefix": "+33800",
          "name": "Example Toll-free",
          "metered": true,
          "overflow": 0,
          "needs_registration": 0,
          "restrictions": "",
          "state": "FR",
          "country_iso": "FR",
          "is_mobile": 0,
          "number_type": "tollfree",
          "available": 10,
          "sms_coverage": 0,
          "returns_numbers": 1,
          "next_function": "v3/getnumbers/0000000000000000000000000000b001",
          "prices": [
            {
              "price_id": "0000000000000000000000000000d001",
              "is_customer_custom": false,
              "per_minute": "0.05",
              "free_minutes": "0",
              "setup_price": "0.00",
              "monthly_price": "5.00",
              "channels": 2
            }
          ],
          "features": ["voice"],
          "group_key": "tollfree",
          "group_type_uuid": "00000000-0000-4000-8000-0000000000a1"
        }
      ]
    }
  ]
}

שגיאות

• 500: msg 'ISO Code parameter is required': isocode חסר או ריק. זוהי שגיאה בבקשה שניתן לתקן. לא מוגדר קוד מצב HTTP תואם.
• 404: msg 'Error: no such country': המדינה אינה מוכרת או אינה מקושרת לקטלוג המספרים המיוחדים. לא מוגדר קוד מצב HTTP תואם.
• 401: האימות חסר או נכשל. נשלח עם קוד מצב HTTP 401.

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

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