תיעוד REST API
ממשקי REST API ל-SMS ול-MMS
שלחו הודעות יישום מאושרות וטפלו בקבלת הבקשות, באירועי מסירה, בפיצול למקטעים ובחיובים.
בחירת ה-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.
הכנת בקשת SMS
יש להשתמש במספר שליחה מאושר התומך ב-SMS ובבעלות החשבון ובנמען שהסכים לקבל את ההודעה, ולהשלים את רישום ה-Brand/Campaign או את אימות המספר ללא עלות למתקשר (toll-free), לפי הנדרש. הדוגמה שלהלן שולחת הודעה אמיתית כאשר ממלאים אותה בפרטי הזדהות ובמספרים תקפים; אין זו סביבת ארגז חול (sandbox).
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"יש להחליף את מצייני המקום של השולח והנמען במספרי טלפון בפורמט בינלאומי, בספרות בלבד וכולל קידומת המדינה. עבור MMS, יש לספק ב-media כתובת URL נתמכת של מדיה הניתנת לאחזור ציבורי, ולוודא תחילה את הזכאות ל-MMS ואת התמחור.
קבלת הבקשה אינה מסירה
יש לבדוק הן את סטטוס האפליקציה החיצוני והן את תוצאת ההודעות שהוחזרה. יש לתעד את מזהה ההודעה שסיפק השירות, ולעקוב אחר סטטוס המסירה ואירועי webhook. הגשה מוצלחת אינה יכולה להוכיח שהמכשיר של הנמען קיבל את ההודעה.
החיוב על SMS הוא לפי מקטע (segment). קידוד ואורך ההודעה עשויים ליצור כמה מקטעים; חיובי מדיה וחיובים הקשורים למפעילים עשויים להיות שונים מ-SMS. יש לקרוא את מחיר המכירה הנוכחי של החשבון לפני השליחה. אין לנסות שוב באופן עיוור שליחה שנתקלה בפסק זמן: יש לבדוק תחילה את התוצאה שתועדה.
טיפול בשגיאות ובניסיונות חוזרים
- כשל באימות או בהרשאה
- יש לבדוק שפרטי ההזדהות של ה-API פעילים, שהשירות מותר ושמגבלות כתובת ה-IP של המקור מתקיימות. עוגיית סשן בפורטל אינה פרטי הזדהות לאינטגרציה.
- קרדיט לא מספיק או אישור שלא התקיים
- יש לטפל ביתרת החשבון, באישור השליחה או בדרישת המסמכים לפני שחוזרים על הפעולה.
- אין תוצאה
- יש לטפל במלאי ריק או בשם מתקשר חסר כתוצאה רגילה. אין להניח שלמספר תקין מבחינה תחבירית יש את כל השירותים.
- פסק זמן ברשת או כשל בשירות
- בפעולות קריאה יש להשתמש בניסיונות חוזרים מוגבלים עם השהיה גדלה (backoff). ברכישה, בשליחה או ברישום, יש לבדוק תחילה את מצב הפעולה; ניסיון חוזר של בקשה שהתקבלה עלול לשכפל פעולה בחיוב.
התמיכה באידמפוטנטיות (idempotency) תלויה בכל משפחת API. ה-API לשירותי חירום תומך במפתחות לניסיון חוזר; אין זה הופך בקשות v3 שרירותיות לאידמפוטנטיות. יש לשמור חותמות זמן, מזהים שהוחזרו ותגובות לאחר הסרת פרטים רגישים לצורך פנייה לתמיכה.
המשיכו עם מדריך העזר של החשבון שלכם
מדריך העזר למשתמשים מחוברים מסנן את הפעולות לפי ההרשאות והשירותים המופעלים בחשבונכם. השתמשו במארח המדויק, בסוג פרטי ההזדהות, בשדות הבקשה ובסכמת התגובה המופיעים בו. הקונסולות יכולות לבצע פעולות בפועל, כולל רכישות ושליחת הודעות.