תיעוד REST API
ממשקי REST API לשיחות חירום
רשמו מספר וכתובת שירות, עקבו אחר סטטוס ההפעלה שלהם ותחזקו את הרשומה כשהמיקום משתנה.
בחירת ה-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.
קריאת הכיסוי ללא רישום מספר
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multi.tel/emergency/coverage?environment=production"https://api.multitel.net/emergency נתמך גם הוא. אף אחת מכתובות הבסיס של שירותי החירום אינה כוללת /v3. הכיסוי מפרט את המדינות הנתמכות בשירות הבינלאומי, סוגי מספרים נתמכים ומחירים; הזכאות ל-E911 בצפון אמריקה נבדקת במהלך הרישום.
{
"code": 200,
"message": "",
"environment": "production",
"requestId": "EXAMPLE_REQUEST_ID",
"data": {}
}זה ממחיש את המעטפת בלבד. את סכמת data של כל פעולה יש לקרוא ב-מדריך ה-API לשירותי חירום שפורסם.
רישום, מעקב אחר הסטטוס ולאחר מכן הגדרת חיוג
- עבור ארה״ב/קנדה ואזורי E911 נתמכים אחרים בצפון אמריקה, יש לספק את המספר, את כתובת ה-E911 ואת אישורי ההסכמה הנדרשים. E911 בצפון אמריקה זמין בסביבת שימוש בפועל בלבד.
- עבור מספר בינלאומי נתמך שבבעלותך, יש לספק הפניה שמורה למסמך (Document) או את זהות משתמש הקצה וכתובתו. יש לעיין תחילה בדרישות המדינה וסוג המספר.
- יש לשלוח בקשת
POST /registrationsאחת.Idempotency-Keyאופציונלי מזהה שינוי לוגי; יש לשמור אותו ואת המטען (payload) המדויק לאורך ניסיונות חוזרים. - יש לקרוא את
GET /registrations/:number. יש לבדוק את מחזור החיים, אתpendingואתactionRequired; ולטפל בתיקונים הנדרשים. קבלה או המתנה אינן שירות פעיל. - לאחר ההפעלה, יש להגדיר את מזהה המתקשר הנכון לשירותי חירום ואת מסלול החיוג הייחודי למדינה. יש להשתמש בהליך האימות של השירות שאינו שיחת חירום.
רישומי sandbox בינלאומיים מבודדים ואינם מפעילים חיוג חירום אמיתי. נדרשים פרטי ההזדהות של החשבון הראשי עבור E911 בצפון אמריקה; המדריך מסביר את התמיכה המוגבלת בחשבונות משנה בינלאומיים.
טיפול בשגיאות ובניסיונות חוזרים
- כשל באימות או בהרשאה
- יש לבדוק שפרטי ההזדהות של ה-API פעילים, שהשירות מותר ושמגבלות כתובת ה-IP של המקור מתקיימות. עוגיית סשן בפורטל אינה פרטי הזדהות לאינטגרציה.
- קרדיט לא מספיק או אישור שלא התקיים
- יש לטפל ביתרת החשבון, באישור השליחה או בדרישת המסמכים לפני שחוזרים על הפעולה.
- אין תוצאה
- יש לטפל במלאי ריק או בשם מתקשר חסר כתוצאה רגילה. אין להניח שלמספר תקין מבחינה תחבירית יש את כל השירותים.
- פסק זמן ברשת או כשל בשירות
- בפעולות קריאה יש להשתמש בניסיונות חוזרים מוגבלים עם השהיה גדלה (backoff). ברכישה, בשליחה או ברישום, יש לבדוק תחילה את מצב הפעולה; ניסיון חוזר של בקשה שהתקבלה עלול לשכפל פעולה בחיוב.
התמיכה באידמפוטנטיות (idempotency) תלויה בכל משפחת API. ה-API לשירותי חירום תומך במפתחות לניסיון חוזר; אין זה הופך בקשות v3 שרירותיות לאידמפוטנטיות. יש לשמור חותמות זמן, מזהים שהוחזרו ותגובות לאחר הסרת פרטים רגישים לצורך פנייה לתמיכה.
המשיכו עם מדריך העזר של החשבון שלכם
מדריך העזר למשתמשים מחוברים מסנן את הפעולות לפי ההרשאות והשירותים המופעלים בחשבונכם. השתמשו במארח המדויק, בסוג פרטי ההזדהות, בשדות הבקשה ובסכמת התגובה המופיעים בו. הקונסולות יכולות לבצע פעולות בפועל, כולל רכישות ושליחת הודעות.