רשימת אזורי הכיסוי במדינה

לאחר בחירת ארץ (ובארצות הברית או בקנדה, אפשר גם לבחור מדינה או פרובינציה מתוך getstates), קראו ל־getareas כדי לראות היכן מוצעים מספרים. שמרו את מזהה האזור uuid לשלב הבא.

כל אזור מוביל לאחד משני שלבים הבאים:

• available > 0: next_function הוא v3/getprefixes/{uuid}, עם ?state= שמתווסף כאשר מסננים לפי מדינה או פרובינציה. השתמשו בו לעיון בקידומות.
• available = 0: לאזור יש קידומות אך אין מלאי, ו־next_function הוא v3/order/{uuid}. עיינו בתיעוד ההזמנות כדי לברר מה נדרש בשלב זה.

available הוא הסכום הכולל לכל האזור, גם כשמסננים לפי מדינה או פרובינציה. המסנן מקבל קוד או שם מלא, אך פועל רק עבור US ו־CA. אם סינון לפי מדינה או פרובינציה מחזיר No areas found, נסו שוב ללא המסנן. הבדיקות מתבצעות בסדר הבא: קוד ארץ חסר, ארץ לא מוכרת, מסנן מדינה או פרובינציה עבור ארץ אחרת, מדינה או פרובינציה לא תקפה, אין אזורים תואמים. כל אחד מהמקרים האלה מחזיר קוד 500 או 404 ב־status.code, ללא קוד מצב HTTP תואם.

בקשה

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

בקשת GET עם isocode בנתיב והפרמטרים האופציונליים state ו־pid במחרוזת השאילתה. אם מקטע הנתיב מושמט, נקרא במקומו שדה isocode בקידוד טופס.

curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US'
curl --user "$API_USER:$API_PASSWORD" 'https://api.multitel.net/v3/getareas/US?state=NY'

תגובה

מעטפת תגובה תקנית. בהצלחה, status.code הוא 200, status.msg הוא 'Results: N', status.results הוא N, ו־response הוא רשימה הממוינת לפי שם האזור. שדות: uuid (מזהה אטום של האזור המשמש בשלב הבא); country_uuid (מזהה ארץ אטום בן 32 תווים, שאינו נחוץ בהמשך); name; area_type ו־number_type (תיאורים קטלוגיים; הרשומות אינן בהכרח מסוגי מספרים מקומיים); country_iso; is_mobile (0 או 1, מתוך דגלי המספרים הניידים של האזור; תמיד 0 עבור US, אלא אם החשבון שלכם מורשה למספרים ניידים של US); available (סך המלאי בכל הקידומות התואמות של האזור, ללא הגבלה למדינה או לפרובינציה שהתבקשה); sms_coverage (0 או 1); returns_numbers (0 או 1, ערך הדגל הגבוה ביותר מבין קידומות האזור); latitude ו־longitude; state_iso; next_function. state_iso: כאשר מסננים לפי מדינה או פרובינציה, זהו הקוד שזוהה עבור ערך המסנן. עבור US ו־CA ללא מסנן, זהו קוד המדינה או הפרובינציה ששמה זהה לשם האזור; אחרת, הערך השמור עבור האזור; ואם גם הוא אינו קיים, קוד הנגזר מנתוני הקידומות של האזור. בארצות אחרות, זהו הערך השמור והוא עשוי להיות ריק. next_function הוא 'v3/getprefixes/{uuid}' (בתוספת '?state={code}' כאשר מופעל סינון) כאשר available גדול מ־0, ואחרת 'v3/order/{uuid}'. אזורים שאין להם אף קידומת תואמת מושמטים. אזורים שיש להם קידומות אך אין בהם מלאי מוחזרים עם available שערכו 0.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 2",
    "results": 2
  },
  "response": [
    {
      "uuid": "0000000000000000000000000000a001",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Example City",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 58,
      "sms_coverage": 1,
      "returns_numbers": 1,
      "latitude": "40.0000",
      "longitude": "-75.0000",
      "state_iso": "NY",
      "next_function": "v3/getprefixes/0000000000000000000000000000a001"
    },
    {
      "uuid": "0000000000000000000000000000a002",
      "country_uuid": "0000000000000000000000000000c001",
      "name": "Sample Town",
      "area_type": "City",
      "number_type": "Local",
      "country_iso": "US",
      "is_mobile": 0,
      "available": 0,
      "sms_coverage": 0,
      "returns_numbers": 0,
      "latitude": "41.0000",
      "longitude": "-76.0000",
      "state_iso": "PA",
      "next_function": "v3/order/0000000000000000000000000000a002"
    }
  ]
}

שגיאות

• 500: msg 'ISO Code parameter is required': isocode חסר או ריק. זוהי שגיאה בבקשה שניתן לתקן. לא מוגדר קוד מצב HTTP תואם.
• 404: msg 'Error: no such country': קוד הארץ אינו מוכר. לא מוגדר קוד מצב HTTP תואם.
• 404: msg 'State filter is only available for US and CA': נשלח ערך לא ריק של state עבור ארץ אחרת. לא מוגדר קוד מצב HTTP תואם.
• 404: msg 'Invalid state': state אינו קוד מוכר וגם אינו שם מוכר של מדינה או פרובינציה בארץ זו. לא מוגדר קוד מצב HTTP תואם.
• 404: msg 'No areas found': אין אזור התואם למסנני הארץ, מקור המלאי והמדינה או הפרובינציה. לא מוגדר קוד מצב HTTP תואם.
• 401: האימות חסר או נכשל. נשלח עם קוד מצב HTTP 401.

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

• פעולת חיפוש בלבד, המיועדת לחשבונות לקוחות. היא אינה שומרת מלאי, מבצעת הזמנה או משנה דבר.
• available נועד למידע בלבד ועשוי להשתנות לפני השלב הבא.