חיפוש מספרי טלפון זמינים

בחרו קידומת בודדת

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

עיינו בקבוצת תוצאות בגודל מוגבל

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

מצאו תבנית ספרות שקל לזכור

ספקו number_filter_mode=contains או ends_with יחד עם number_filter_value. הערך חייב להכיל 1–15 ספרות. חיפוש עשוי לאחזר קבוצות מוגבלות של מספרים מועמדים לפני החלת המסנן, ולכן הוא עלול להחמיץ מספרים מתאימים אחרים במלאי. אם נחוץ לכם מקור נתמך לביצוע החיפוש הנדרש, קבלו בורר מסוג pid מ-MultiTEL והשתמשו ב-filter_required=1; אם הבחירה חסרה או אינה נתמכת, תוחזר שגיאת API.

בדקו את המספר שנבחר

קראו את number, info.uuid, את הערך הנבחר של price[].uuid, את שמות התכונות הזמינות ואת דרישות הרישום מתוך אותה תוצאה. המערך price עשוי להציע כמה תוכניות עם כמויות ערוצים ותעריפים שונים. שדות כספיים וכמויות עשויים להיות מקודדים כמחרוזות. מטא-נתונים אופציונליים, לרבות info.state, משתנים בין המקורות; אין לדרוש מבנה אחיד של נתוני מדינה או להסיק מחירים ממזהה.

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

הזמינו בנפרד ואמתו את התוצאה

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

בקשה

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

פרמטרים בנתיב ופרמטרי שאילתה בכתובת URL. השתמשו ב-GET לתהליך החיפוש הציבורי. רכיב הטיפול מקבל גם ערכים מסוימים מטופס או מבקשה, אך זה אינו API לחיפוש באמצעות גוף בקשה ב-JSON.

curl --fail-with-body --get \
  --user "${MULTITEL_API_USERNAME}:${MULTITEL_API_PASSWORD}" \
  --data-urlencode "compact=1" \
  --data-urlencode "quantity=10" \
  "https://api.multitel.net/v3/getnumbers/${PREFIX_ID}/10"

תגובה

אובייקט JSON אחד המכיל את status ואת response. בהצלחה, status.code הוא 200 ו-response הוא מערך של רשומות מספרים. status.results הוא מספר הרשומות במערך המוחזר; status.msg עשוי להיות Results: N או OK בתגובה מוזרמת. ללא compact=1, חיפושים מסוימים כותבים את המערך response בהדרגה ומסיימים ב-status, לכן המתינו לגוף ה-JSON המלא. אין מדובר ב-JSON המופרד באמצעות ירידות שורה. בדקו את status.code גם כאשר התעבורה ב-HTTP מצליחה. שדות אופייניים מוצגים להלן; מטא-נתונים ייחודיים למקור ושדות אופציונליים משתנים. התייחסו לכל מזהה כאל ערך אטום שאין להסיק משמעות ממבנהו, ושמרו יחד את המספר ואת הערך הנבחר שלו ב-price[].uuid.

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

{
  "status": {
    "code": 200,
    "msg": "Results: 1",
    "results": 1
  },
  "response": [
    {
      "number": "12125550123",
      "info": {
        "uuid": "NUMBER_ID_FROM_RESPONSE",
        "prefix_uuid": "PREFIX_ID_FROM_RESPONSE",
        "area_uuid": "AREA_ID_FROM_RESPONSE",
        "country_uuid": "COUNTRY_ID_FROM_RESPONSE",
        "country_iso": "US",
        "prefix": "+1212",
        "name": "Example area",
        "state": "US"
      },
      "price": [
        {
          "uuid": "PRICE_PLAN_ID_FROM_RESPONSE",
          "per_minute": "0.01",
          "per_sms": "0",
          "per_mms": "0",
          "free_minutes": "0",
          "setup_price": "1.00",
          "monthly_price": "2.00",
          "yearly_price": "0",
          "channels": "2"
        }
      ],
      "contract": {
        "term": "1 month",
        "renewal": "monthly",
        "notice": "none"
      },
      "restrictions": {
        "needs_registration": "0",
        "restrictions": ""
      },
      "features": [
        "voice"
      ],
      "overflow": "0"
    }
  ]
}

שגיאות

• 401: האימות נכשל. פרטי הזדהות שגויים או חסרים, וכן דחיית הגישה לחשבון ה-API, אינם מניבים תוצאות חיפוש.
• 404: Invalid prefix ID, Invalid country, Invalid area או No numbers found. קראו את status.msg; תגובת שגיאה אינה מערך של מספרים.
• 400: NUMBER_FILTER_INVALID בשדה response.code: מצב לא תקין, ערך שאינו מורכב מ-1–15 ספרות, או filter_required ללא ציון גם של המצב וגם של הערך.
• 422: NUMBER_FILTER_UNSUPPORTED בשדה response.code: הקידומת מקצה מספר בעת ההזמנה (reason=order_only_prefix ו-next_function מציין את מסלול ההזמנה), או שהמקור שנבחר במפורש אינו יכול לתמוך במסנן הנדרש.

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

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