תיעוד REST API

ממשק REST API לבדיקת ניתוב LRN

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

פתיחת התיעוד הייעודי לחשבון מפתחים ואוטומציה

בחירת ה-API ופרטי ההזדהות יחד

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

משפחת API	כתובת בסיס (Base URL)	אימות ותוצאה
תקשורת v3	`https://api.multitel.net/v3`	פרטי הזדהות מאושרים מסוג Basic; אסימונים (tokens) שהוקצו ומתאימים לשימוש, רק בפעולות שתומכות בהם. JSON עם `status` ו-`response`.
רישום לשירותי חירום	`https://api.multi.tel/emergency`	פרטי הזדהות מאושרים מסוג Basic או גישת bearer שהוקצתה במיוחד. JSON עם `code`, `message` ו-`data`.
אינטגרציות REST של הפורטל	המארח והפעולה כפי שמוצגים בתיעוד המפתחים של החשבון שלך	יש להשתמש בפרטי ההזדהות, בהיקפי ההרשאה (scopes) ובסכמה המתועדים של אותה פעולה. בקשות מסשן דפדפן משתמשות בממשק נפרד.

יש להגדיר את MULTITEL_API_USERNAME ואת MULTITEL_API_PASSWORD בהגדרות הסודות של השרת שלך לפני השימוש בדוגמאות. אין להטמיע אותם ב-JavaScript ציבורי בדפדפן, בכתובות URL או בבקרת גרסאות. פרטי הזדהות ייעודיים מנוהלים ב-הגדרות שילוב API.

חיפוש מספר

GET /v3/lrn/{number} מקבל את מספר היעד בנתיב. ניתן לספק מספר מקור אופציונלי כ-/v3/lrn/{number}/{ani} עבור מידע התלוי במקור. יש להזין מספרי טלפון בצפון אמריקה בספרות בלבד, כולל קידומת המדינה כאשר נדרש; הדוגמאות משתמשות במספרים בדיוניים שמורים.

curl --fail-with-body \
  --user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
  --header "Accept: application/json" \
  "https://api.multitel.net/v3/lrn/12025550123"

curl --fail-with-body \
  --user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
  --header "Accept: application/json" \
  "https://api.multitel.net/v3/lrn/12025550123/12025550124"

ביצוע חיפוש עם פרטי הזדהות תקפים כרוך בחיוב. התעריף הוא ‏0.00025 ‏$ לכל חיפוש: ‏0.25 ‏$ לכל 1,000 או ‏250 ‏$ למיליון. אין הנחות כמות. זהו חיפוש מידע ניתוב; הוא אינו מבצע שיחת טלפון.

קריאת התוצאה

{
  "status": {
    "code": 200,
    "msg": "Success"
  },
  "response": {
    "lrn": "12025550123",
    "ported": 0,
    "ocn": "",
    "lata": "",
    "rc": "",
    "cost": "$0.00025"
  }
}

דוגמה מומצאת זו מדגימה את מבנה התגובה בלבד; אין זו תוצאת ניתוב שנמדדה. יש לבדוק את status.code לפני השימוש ב-response. השדה cost הוא מחרוזת שמתחילה בסימן מטבע, ולא מספר JSON.

שדה	משמעות
`lrn`	Location Routing Number, המשמש לזיהוי יעד הניתוב.
`ported`	מחוון המציין אם המספר נויד, כפי שמספק חיפוש זה: בדרך כלל 0 או 1. אין להשתמש בו כהוכחת בעלות או זכאות לשירות.
`ocn`	Operating Company Number, כאשר הוא מסופק.
`lata`	אזור גישה ותמסורת מקומי (Local Access and Transport Area), כאשר הוא מסופק.
`rc`	מרכז תעריף (rate center), כאשר הוא מסופק.
`city`, `state`, `lec`, `lectype`, `jurisdiction`, `local`	פרטים נוספים הקשורים למיקום, למפעיל או למקור, כאשר הם זמינים. ייתכן שיהיו חסרים או ריקים.

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

שימוש בחיפושים בתהליך הניתוב שלך

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

צפייה במוצר LRN ובתמחור הקבוע. נתיב ה-OpenAPI הציבורי כולל מקטע ANI; המימוש הפרוס של LRN מקבל גם את הבקשה הקצרה יותר ללא ANI. lrninfo היא פעולה נפרדת ואין להחליף בה את נקודת הקצה הזו.

טיפול בשגיאות ובניסיונות חוזרים

כשל באימות או בהרשאה: יש לבדוק שפרטי ההזדהות של ה-API פעילים, שהשירות מותר ושמגבלות כתובת ה-IP של המקור מתקיימות. עוגיית סשן בפורטל אינה פרטי הזדהות לאינטגרציה.
קרדיט לא מספיק או אישור שלא התקיים: יש לטפל ביתרת החשבון, באישור השליחה או בדרישת המסמכים לפני שחוזרים על הפעולה.
אין תוצאה: יש לטפל במלאי ריק או בשם מתקשר חסר כתוצאה רגילה. אין להניח שלמספר תקין מבחינה תחבירית יש את כל השירותים.
פסק זמן ברשת או כשל בשירות: בפעולות קריאה יש להשתמש בניסיונות חוזרים מוגבלים עם השהיה גדלה (backoff). ברכישה, בשליחה או ברישום, יש לבדוק תחילה את מצב הפעולה; ניסיון חוזר של בקשה שהתקבלה עלול לשכפל פעולה בחיוב.

התמיכה באידמפוטנטיות (idempotency) תלויה בכל משפחת API. ה-API לשירותי חירום תומך במפתחות לניסיון חוזר; אין זה הופך בקשות v3 שרירותיות לאידמפוטנטיות. יש לשמור חותמות זמן, מזהים שהוחזרו ותגובות לאחר הסרת פרטים רגישים לצורך פנייה לתמיכה.

המשיכו עם מדריך העזר של החשבון שלכם

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

קטלוג נקודות הקצה הייעודי לחשבון קונסולת REST לתקשורת מסמך OpenAPI ציבורי לתקשורת מדריך שילוב OAuth