מדריך ליישום ניידות LINK REST API SMS מדריך למשתמש

מדריך יישום ניידות LINK REST API SMS

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

LINK Mobility מספק RESTful API שניתן להשתמש בו כדי לגשת לשירותי LINK Mobility כגון שליחת SMS. ממשק API זה נועד להיות קל לשימוש ותואם לכל השפות והמסגרות המודרניות. באמצעות השפה שתבחר האפליקציה שלך יכולה להשתמש ב-Link Mobility REST API כדי ליישם יכולות העברת הודעות ותשלום עוצמתיות

© LINK Mobility, 10 במרץ 2021

מידע משפטי

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

Netsize™ ו-linkmobility™ מוגנות על ידי חוקי הקניין הרוחני הצרפתי, האיחוד האירופי והבינלאומי.

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

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

NETSIZE
Société anonyme au capital de 5 478 070 יורו
Siège social :62, avenue Emile Zola92100 Boulogne – צרפת
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com

היקף המסמך

מסמך זה מתאר כיצד ספק השירות משתמש ב-LINK Mobility REST API עבור SMS. הוא מיועד לאדריכלים ומעצבים טכניים המיישמים את שירותיו של ספק השירות.

1. שימוש בסיסי

קל מאוד לשלוח SMS. אתה שולח בקשת HTTP ל-LINK Mobility שניתן לבצע באמצעות א web דפדפן.

2. Over Functionalview

מערכת LINK Mobility מספקת את הפונקציונליות הבסיסית הבאה עבור הודעות SMS:
שליחת הודעות SMS עם סיום נייד (MT), כגון הודעות טקסט או בינאריות (למשל WAP Push) הודעות פרימיום ותעריף רגיל.

קבלת דוחות מסירה עבור הודעות MT שנשלחו.

קבלת הודעות SMS ממקור נייד (MO), פרימיום ותעריף סטנדרטי.
ה-SMS REST API מוקדש לשליחת הודעות SMS בתעריף סטנדרטי.

ה-API שולח את כל הודעות ה-SMS באופן אסינכרוני, ומאפשר תכונות כגון:

"אש ושכח" - ספק השירות רוצה לקבל זמני תגובה צפויים יותר ואינו רוצה לחכות לתוצאה מהמפעיל.

נסה שוב פונקציונליות - LINK Mobility ישלח שוב את ההודעה אם למפעיל יש בעיות זמניות.

2.1 שליחת הודעת SMS

                                       
ספק שירות Netsize Consumer

1. שלח הודעת MT
2. החזר מזהה הודעה
3. שלח הודעת SMS
4. מסירת דו"ח מסירה
5. שלח דו"ח מסירה

הזרימה הבסיסית לשליחת הודעות SMS מתוארת באופן הבא:

ספק השירות מבקש לשלוח הודעת SMS לנמען באמצעות מערכת LINK Mobility.

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

LINK Mobility מטפל בניתוב ומעביר את הודעת ה-SMS לצרכן הפונה.
דוח מסירה מופעל, למשל כאשר הודעת ה-SMS נשלחת למכשיר של הצרכן.

דוח המסירה נשלח לספק השירות. הדוח מכיל את אותו מזהה הודעה כפי שהוחזר בשלב 2.

זרימה חלופית: בקשה לא חוקית

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

3. נקודת קצה

ניתן לגשת למשאב ה-SMS באמצעות הנתיב:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
עבור אבטחת חיבור, ה- LINK Mobility REST API נגיש רק באמצעות HTTPS.
אישור השרת Link Mobility חתום על ידי Thawte Server CA.

4. תפעול

שירות ה-SMS מספק את הפעולות הבאות:

שֵׁם	נָתִיב
לִשְׁלוֹחַ	/restapi/v1/sms/send

4.1 שלח

פעולת השליחה משמשת לשליחת SMS לנמען בודד.

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

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

ספק השירות יכול לשלוח הודעות משורשרות, אך הכנת כותרת נתוני המשתמש ונתוני המשתמש חייבת להיעשות על ידי ספק השירות וההודעה חייבת להישלח באמצעות מספר בקשות שליחה אל LINK Mobility.

5. אימות

שם משתמש וסיסמה נשלחים בכל בקשה באמצעות HTTP Basic Authentication Scheme.

https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA

אישורים נשלחים בכותרת הרשאה בבקשת ה-HTTP. הלקוח בונה את שדה הכותרת כמתואר כאן:

https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side

למשלample, אם שם המשתמש הוא john ו-changeme הוא הסיסמה אז כותרת ההרשאה המתקבלת היא:

הרשאה: בסיסי am9objpjaGFuZ2VtZSA=

כחלופה ניתן להגיש את שם המשתמש והסיסמה כפרמטרי בקשה. זה מומלץ רק ללקוחות שאינם תומכים ב-Basic Auth.

6. הגשת בקשה

6.1 מחרוזת שאילתה

פרמטרי הבקשה נשלחים כמחרוזת שאילתה המכילה זוגות של שם/ערך. מחרוזת השאילתה מקודדת באמצעות קידוד אחוז (URL הַצפָּנָה).

http://www.w3schools.com/tags/ref_urlencode.asp

למשלampלה, שלום עולם! מקודד בתור Hello+World%21.

6.2 פרמטרי בקשה חובה

שֵׁם	אורך מקסימלי	תֵאוּר
כתובת יעד	40	ה-MSISDN שאליו יש לשלוח את הודעת ה-SMS, החל מקוד המדינה. לְשֶׁעָבַרample: 46123456789. עבור כמה שווקים (ששם חייב להיות ערפול של ה-Consumer MSISDN) ערך זה יכול להיות גם כינוי אלפאנומרי, עם קידומת "#".
הודעהטקסט	1600	תוכן הודעת ה-SMS.

6.3 פרמטרי בקשה אופציונליים (לשימוש מתקדם)

שֵׁם	אורך מקסימלי	תֵאוּר
מקור כתובת	16	כתובת המקור של הודעת ה-SMS היוצאת. סוג כתובת המקור מוגדר על ידי הפרמטר originatorTON. האורך המקסימלי של מספר קצר הוא 16. השולח אלפא מספרי מוגבל לאלפבית ברירת המחדל של GSM עם אורך מקסימלי של 11 תווים. האורך המקסימלי של שולח MSISDN הוא 15 (באמצעות אותו פורמט כמו רכיב destinationAddress). ניתן להשמיט כאשר originatingAddress ו- originatingTON נבחרים על ידי המערכת. פונקציה זו תלויה בשוק ובתצורה. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
originatorTON	1	סוג המספר של כתובת המקור (TON): 0 - מספר קצר 1 - אלפא מספרי (אורך מקסימלי 11) 2 – MSISDN ניתן להשמיט כאשר originatingAddress ו- originatingTON ייבחרו על ידי המערכת. פונקציה זו תלויה בשוק ובתצורה. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
userDataHeader	280	כותרת נתוני משתמש יחד עם נתוני המשתמש יכולים להכיל עד 140, כלומר 280 אוקטטים בקידוד hex. פרמטר זה תמיד מקודד hex.
DCS	3	ערכת קידוד נתונים. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
PID	3	מזהה פרוטוקול. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
relativeValidityTime	6	זמן תוקף יחסי בשניות (ביחס לזמן ההגשה ל-LINK Mobility). הערך המרבי הוא 604800 (7 ימים) וברירת המחדל היא 48 שעות. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
זמן אספקה	20	הזמן הטוב ביותרamp מתי יש לשלוח הודעת SMS (זמן מסירה מושהה). ראה סעיף על פורמט תאריך שעה.
statusReportFlags	1	שלח בקשה לדוח: 0 - אין דוח מסירה (ברירת מחדל) 1 - דוח מסירה מבוקש 9 – דוח מסירת שרת מבוקש (LINK Mobility לא מעביר את הדוח לספק השירות אלא הופך אותו לזמין בדוחות וכו')
campaignName	50	עסקאות LINK Mobility הן tagעם השם הזה. הוא משמש לקיבוץ עסקאות בדוחות קישור ניידות.
maxConcatenatedMessages	1	ערך בין 1 ל-10 המגדיר כמה הודעות משורשרות מותרות. ברירת המחדל היא 3.
correlationId	100	תעודה מזהה מסופקת על ידי ספק השירות שתהיה הדהוד בדוח מסירה.
שם משתמש	100	מסופק כחלופה לאימות HTTP בסיסית.
סִיסמָה	100	מסופק כחלופה לאימות HTTP בסיסית.

6.4 שיטות בקשת HTTP

עבור יכולת פעולה הדדית מקסימלית, ה-API תומך בשיטות בקשת HTTP GET ו-POST. אין להשתמש בשיטות HTTP אחרות.

6.4.1 קבל

מחרוזת השאילתה המקודדת מצורפת ל- URL.

לְקַבֵּל
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
הרשאה: בסיסי am9objpjaGFuZ2VtZSA=

6.4.2 פוסט

מחרוזת השאילתה המקודדת נשלחת בגוף הודעת בקשת ה-HTTP. סוג התוכן הוא application/x-www-form-urlמוּצפָּן.

שֶׁלְאַחַר https://europe.ipx.com/restapi/v1/sms/send
מארח: europe.ipx.com
סוג תוכן: יישום / x-www-form-urlמוּצפָּן
הרשאה: בסיסי am9objpjaGFuZ2VtZSA=
אורך תוכן: 57

destinationAddress=46123456789&messageText=Hello+World%21

6.5 תאריך ושעה

פרמטרים ב-REST API המייצגים תאריך ושעה נמצאים תמיד באזור זמן UTC (זמן אוניברסלי מתואם). הכי זמניםamps מיוצגים כמחרוזת בפורמט המדויק הזה:
2017-04-25T23:20:50Z
זה מייצג 20 דקות ו-50 שניות לאחר השעה ה-23 של ה-25 באפריל 2017 ב-UTC.

7. הודעת תגובה

לאחר קבלת ופירוש הודעת בקשה ה-API מגיב בהודעת תגובת HTTP.

7.1 קוד מצב HTTP

REST API תמיד מחזיר את קוד מצב HTTP 200 בסדר עבור בקשות מעובדות. גוף ההודעה מכיל פרמטר responseCode המשמש לקביעת התוצאה המדויקת.

7.2 גוף ההודעה

גוף ההודעה מורכב מ-JSON המתאר את התוצאה של הבקשה.
http://json.org/
Link Mobility JSON תואם למדריך הסגנון של Google JSON.
https://google.github.io/styleguide/jsoncstyleguide.xml

7.3 פרמטרי תגובה

שֵׁם	אורך מקסימלי	תֵאוּר
קוד תגובה	3	0 מציין עסקה מוצלחת.
תגובה הודעה	255	תיאור טקסטואלי של תגובה, למשל טקסט שגיאה.
הזמנים ביותרamp	20	תאריך ושעה שבהם LINK Mobility עיבד את הבקשה. (עיין בסעיף פורמט תאריך/שעה).
traceId	36	מזהה פנימי של קישור ניידות. משמש לתמיכה ופתרון בעיות.
messageIds	10 x 36	מערך מזהי הודעות ייחודיות של LINK Mobility עבור כל הודעה מוצלחת (מספר מזהי הודעות מוחזרים אם ההודעה משורשרת). הושמט במקרה של כישלון.

7.4 דוגמאותampלה תגובות

הַצלָחָה

HTTP/1.1 200 בסדר
סוג תוכן: application/json
אורך תוכן: 144
תאריך: ה', 15 בספטמבר 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

הנה אותו JSON מעוצב לקריאות:

{
"קוד תגובה":0,
"תגובה הודעה":"הַצלָחָה",
"הזמנים ביותרamp“:”2016-0915T13:20:31Z”,
"traceId“:”f678d30879fd4adc25f2”,
"messageIds“:[“1-4850879008”]
}

כֶּשֶׁל

HTTP/1.1 200 בסדר
סוג תוכן: application/json
אורך תוכן: 148
תאריך: ה', 15 בספטמבר 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" התחברות לא חוקית או שימוש ב-API לא מורשה","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

הַצלָחָה

HTTP/1.1 200 בסדר
סוג תוכן: application/json
אורך תוכן: 144
תאריך: ה', 15 בספטמבר 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}

הנה אותו JSON מעוצב לקריאות:

{
"קוד תגובה":0,
"תגובה הודעה":"הַצלָחָה",
"הזמנים ביותרamp“:”2016-0915T13:20:31Z”,
"traceId“:”f678d30879fd4adc25f2”,
"messageIds“:[“1-4850879008”]
}

כֶּשֶׁל

HTTP/1.1 200 בסדר
סוג תוכן: application/json
אורך תוכן: 148
תאריך: ה', 15 בספטמבר 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" התחברות לא חוקית או שימוש ב-API לא מורשה","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}

7.5 קודי תגובה

ניתן להחזיר את קודי התגובה הבאים בתגובת השליחה:

קוד	טֶקסט	תֵאוּר
0	הַצלָחָה	הוצא להורג בהצלחה.
1	התחברות לא חוקית או שימוש לא מורשה ב-API	שם משתמש או סיסמה שגויים או ספק השירות חסום על ידי LINK Mobility.
2	הצרכן נחסם על ידי Link Mobility	הצרכן נחסם על ידי LINK Mobility.
3	התפעול אינו מסופק על ידי LINK Mobility	הפעולה חסומה עבור ספק השירות.
4	הצרכן אינו ידוע ל-LINK Mobility	הצרכן אינו ידוע ל-LINK Mobility. או אם נעשה שימוש בכינוי בבקשה; הכינוי לא נמצא.
5	הצרכן חסם שירות זה ב-LINK Mobility	הצרכן חסם שירות זה ב-LINK Mobility.
6	כתובת המקור אינה נתמכת	כתובת המקור אינה נתמכת.
7	כתובת מקור האלפא אינה נתמכת על ידי החשבון	כתובת מקור האלפא אינה נתמכת על ידי החשבון.
8	כתובת מקור MSISDN אינה נתמכת	כתובת המקור של MSISDN אינה נתמכת.
9	GSM מורחב לא נתמך	GSM מורחב לא נתמך.
10	Unicode לא נתמך	Unicode לא נתמך.
11	דוח מצב אינו נתמך	דוח מצב אינו נתמך.
12	היכולת הנדרשת אינה נתמכת	היכולת הנדרשת (מלבד האמור לעיל) לשליחת ההודעה אינה נתמכת.
13	חריגה מקצב הצער המקסימלי של ספק התוכן	ספק השירות שולח את הודעות ה-SMS אל LINK Mobility מהר מדי.
14	מזהה פרוטוקול אינו נתמך על ידי החשבון	מזהה פרוטוקול אינו נתמך.
15	חרגת ממגבלת שרשור ההודעות	מספר ההודעות המשורשרות חורג מהמספר המרבי המבוקש.
16	לא ניתן לנתב את ההודעה.	LINK Mobility לא הצליחה לנתב את ההודעה.
17	פרק זמן אסור	אסור לשלוח הודעה במהלך פרק זמן
18	יתרה נמוכה מדי בחשבון ספק השירות	ספק השירות חסום עקב יתרה נמוכה מדי
50	הצלחה חלקית	הצלחה חלקית בעת שליחת הודעת SMS למספר נמענים.
99	שגיאת שרת פנימית	שגיאת קישור ניידות אחרת, צור קשר עם תמיכת LINK Mobility לקבלת מידע נוסף.
100	כתובת יעד לא חוקית	כתובת היעד (MSISDN, או כינוי) אינה חוקית.
102	מזהה לא חוקי עם הפניה (מקושרת).	מזהה ההפניה לא חוקי, אולי מזהה ההפניה כבר בשימוש, ישן מדי או לא ידוע.
103	שם חשבון לא חוקי	שם החשבון אינו חוקי.
105	מטא נתוני שירות לא חוקיים	המטא נתונים של השירות אינם חוקיים.
106	כתובת מקור לא חוקית	כתובת המקור אינה חוקית.
107	כתובת מקור אלפאנומרית לא חוקית	כתובת המקור האלפאנומרית אינה חוקית.
108	זמן תוקף לא חוקי	זמן התוקף אינו חוקי.
109	זמן אספקה ​​לא חוקי	זמן האספקה ​​אינו חוקי.
110	תוכן הודעה/נתוני משתמש לא חוקיים	נתוני המשתמש, כלומר הודעת ה-SMS, אינם חוקיים.
111	אורך הודעה לא חוקי	אורך הודעת ה-SMS אינו חוקי.
112	כותרת לא חוקית של נתוני משתמש	כותרת נתוני המשתמש אינה חוקית.
113	ערכת קידוד נתונים לא חוקית	ה-DCS לא חוקי.
114	מזהה פרוטוקול לא חוקי	ה-PID לא חוקי.
115	דגלים לא חוקיים של דוח מצב	דגלי דוח המצב אינם חוקיים.
116	TON לא חוקי	ה-TON המקור אינו חוקי.
117	פסול גampשם יישור	ה-Campשם המערך אינו חוקי.
120	מגבלה לא חוקית למספר המרבי של הודעות משורשרות	המספר המרבי של הודעות משורשרות אינו חוקי.
121	כתובת מקור לא חוקית של msisdn	כתובת המקור של MSISDN אינה חוקית.
122	מזהה מתאם לא חוקי	מזהה המתאם אינו חוקי.

8. תכונות אופציונליות

8.1 תיקון MSISDN

תיקון MSISDN הוא תכונה אופציונלית שניתן להפעיל על ידי תמיכת LINK Mobility אם תתבקש.

תכונה זו תתקן את כתובות היעד ותיישר אותן לפורמט E.164 הנדרש. בנוסף לתיקון הפורמט, המערכת עשויה גם לבצע פונקציונליות ספציפית לשוק כגון תרגום מספרים צרפתיים בינלאומיים לתיקון מספרי DOM-TOM (départements et territoires d'outre-mer) כאשר זה רלוונטי.

להלן מספר אקסampקטעי תיקונים:

כתובת היעד שהוגשה	כתובת יעד מתוקנת
+46(0)702233445	46702233445
(0046)72233445	46702233445
+460702233445	46702233445
46(0)702233445	46702233445
46070-2233445	46702233445
0046702233445	46702233445
+46(0)702233445aaa	46702233445
336005199999	2626005199999 (מספר צרפתי מתורגם למספר DOM-TOM)

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

להלן מספר דוגמאותampמספר תיקונים שנעשו בעת שימוש בשוודיה (קוד מדינה 46) כשוק ברירת המחדל למספרים לאומיים.

כתובת היעד שהוגשה	כתובת יעד מתוקנת
0702233445	46702233445
070-2233 445	46702233445
070.2233.4455	46702233445
460702233445	46702233445
+460702233445	46702233445
+458022334455	458022334455
45802233445	לא חוקי מכיוון שחסר הסימן '+'

שימו לב שה-MSISDN המתוקן ישמש את LINK Mobility והוא יוחזר בדוחות המסירה.

אנא צור קשר עם תמיכת LINK Mobility לקבלת מידע נוסף.

8.2 החלפת דמות

החלפת תווים היא תכונה אופציונלית שניתן להפעיל על ידי תמיכת LINK Mobility אם תתבקש.

תכונה זו תתרגם תווי אלפבית שאינם GSM בנתוני המשתמש (טקסט SMS) לתווי אלפבית GSM מקבילים כאשר ה-DCS מוגדר ל-"GSM" (17). למשלample "Sequüência de teste em Português" יתורגם ל"Sequüencia de teste em Português".

9. דוחות מסירה

ספק השירות יכול, אם הוקצה, לבקש דוחות מסירה של הודעות SMS או הודעות מסירה עבור הודעות MT שנשלחו. דוחות אלו מופעלים ב-SMSC של המפעיל כאשר הודעת ה-MT נמסרת לצרכן היעד או נמחקת, למשל, פג תוקף או, מסיבה כלשהי, אינה ניתנת לניתוב.

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

הדוחות מנותבים דרך LINK Mobility ונשלחים לספק השירות באמצעות פרוטוקול HTTP.

כדי לקבל דוחות, ספק השירות צריך ליישם למשלampיש Java Servlet או דף ASP.NET. שניהם מקבלים בקשות HTTP GET או POST.

פרמטרים

הבקשה כוללת את הפרמטרים הבאים:

פָּרָמֶטֶר	סוּג	M/O/I*	ערך ברירת מחדל	אורך מקסימלי	תֵאוּר
MessageId	חוּט	M	–	22	מזהה ההודעה של הודעת MT שאליה דוח זה מתאים.
כתובת יעד	חוּט	M	–	40	ה-MSISDN של הצרכן, כלומר כתובת היעד של הודעת ה-MT המקורית.
קוד סטטוס	מִספָּר שָׁלֵם	M		1	קוד סטטוס מציין את מצב הודעת ה-MT. קודי סטטוס ישימים הם: 0 - נמסר 2 - נמחק (קוד סיבה חל)
TimeStamp	חוּט	M	–	20	זמן המציין מתי דוח המסירה התקבל על ידי LINK Mobility. אזור הזמן של הזמןamp הוא CET או CEST (עם שעון קיץ כפי שהוגדר עבור האיחוד האירופי). פורמט: yyyyMMdd HH:mm:ss.
מַפעִיל	חוּט	M	–	100	שם המפעיל בשימוש בעת שליחת הודעת ה-SMS או שם החשבון המשמש בעת שליחת הודעת ה-SMS. רשימה של מפעילים זמינים מסופקת על ידי תמיכת LINK Mobility.
ReasonCode	מִספָּר שָׁלֵם	O	–	3	קוד סיבה מציין מדוע ההודעה הגיעה למצב שנמחק. קודי סיבה ישימים הם: 100 - פג תוקף 101 – נדחה 102 - שגיאת עיצוב 103 - שגיאה אחרת 110 - מנוי לא ידוע 111 - מנוי חסום 112 - מנוי לא מסופק 113 - מנוי לא זמין 120 - כשל ב-SMSC 121 - עומס SMSC 122 - נדידת SMSC 130 - שגיאה במכשיר 131 - חריגה מזיכרון השפופרת ההתנהגות עשויה להשתנות עם שילובי המפעיל.
OperatorTimeStamp	חוּט	O	–	20	זמן המציין מתי הדוח הופעל ב-SMSC של המפעיל (אם סופק על ידי המפעיל). אזור הזמן של הזמןamp הוא CET או CEST (עם שעון קיץ כפי שהוגדר עבור האיחוד האירופי). פורמט: yyyyMMdd HH:mm:ss.
StatusText	חוּט	O	–	255	מציין מיקום למידע נוסף מהמפעיל, למשל תיאור טקסט ברור של המצב/סיבה. ההתנהגות עשויה להשתנות עם שילובי המפעיל.
CorrelationId	חוּט	O	–	100	מזהה המתאם שסופק ב-SendRequest או SendTextRequest.
OperatorNetworkCode	מִספָּר שָׁלֵם	O	–	6	קוד הרשת הניידת (MCC + MNC) של המפעיל.

* M = חובה, O = אופציונלי, I = מתעלם.
ספק השירות חייב לספק את LINK Mobility עם היעד URL עבור דוחות מסירה (אופציונלי כולל אישורים עבור אימות HTTP בסיסי). ספק השירות יכול לבחור באיזו שיטת HTTP מועדפת להשתמש:
HTTP POST (מומלץ)
HTTP GET.

Example באמצעות HTTP GET (נמסר בהצלחה):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0

Example באמצעות HTTP GET (לא נמסר, המפעיל סיפק את הזמןamp לאירוע):

https://user:password@www.serviceprovider.com/receivereport?MessageId=123&DestinationAddress=46762050312&Operator=Vodafone&OperatorTimeStamp=20100401%2007%3A47%3A59&TimeStamp=20100401%2007%3A47%3A51&StatusCode=2&StatusText=Delivery%20failed&ReasonCode=10

הפרמטרים הם URL מקודד.

קידוד תווים:
ספק השירות יכול לבחור באיזה קידוד תווים מועדף להשתמש:
UTF-8 (מומלץ)
ISO-8859-1.

9.1 אישור ספק שירות

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

שימו לב: ל-LINK Mobility יש פסק זמן קריאה עבור אישורים של 30 שניות עבור דוחות מסירה. פסק זמן יפעיל ניסיון חוזר של מסירה (אם ניסיון חוזר מופעל) או ביטול של המסירה (אם ניסיון חוזר מושבת). משמעות הדבר היא שאפליקציית ספק השירות חייבת להבטיח זמני תגובה מהירים, במיוחד בעת עומס גבוה.

מומלץ מאוד לאשר את דוח המסירה כלפי LINK Mobility לפני עיבודו.

הכלל להכרה חיובית ושלילית מתואר כדלקמן:

אישור חיובי, ACK, דוח מסירה נמסר:
קוד תגובה של טווח HTTP 200 בשילוב עם התוכן הבא בפורמט XML:

אישור שלילי, NAK, דו"ח מסירה לא נמסר:
כל תשובה מלבד אישור חיובי, למשלample, אישור שלילי מופעלת על ידי כל קוד שגיאה HTTP או תוכן ה-XML הבא:

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

להלן בקשת HTTP POST ותגובה למשלampחלק של דוח מסירה שנמסר לספק שירות:

בקשת HTTP:

POST /context/app HTTP/1.1
סוג תוכן: יישום / x-www-form-urlencoded;charset=utf-8
מארח: שרת:יציאה
אורך תוכן: xx

MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0

תגובת HTTP:

HTTP/1.1 200 בסדר
סוג תוכן: טקסט/רגיל

9.2 נסה שוב

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

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

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

כאשר ניסיון חוזר עבור NAK מופעל, חשוב להבין אילו תרחישים יפיקו ניסיון ניסיון חוזר מ-LINK Mobility וכיצד הניסוי החוזר פועל. לכל ספק שירות יש תור נסיונות חוזר משלו, שבו ההודעות מסודרות לפי זמן ההודעותamp. Link Mobility תמיד מנסה להעביר הודעות ישנות יותר תחילה, למרות שהסדר הפרטני של ההודעות שנמסרו לספק השירות אינו מובטח. הסיבה העיקרית לביטול הודעות מתור הניסיון החוזר היא אחת משתי סיבות: או שתוקף ההודעה TTL פג או (תיאורטית) תור הניסיון החוזר הופך למלא. ה-TTL תלוי במפעיל ובחשבון, כלומר, יכול להשתנות בהתאם למפעיל או לסוג ההודעה, למשל, הודעת SMS פרימיום או הודעת SMS בתעריף רגיל.

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

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

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

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

10. טיפים ליישום

1. אפשר להשתמש שלך web דפדפן להגשת בקשות ל-API. זה מקל מאוד לחקור ולהעריך את השירותים ללא כל כלי פיתוח.

2. Chrome או Firefox מומלצים יחד עם תוסף כגון JSONView כדי להציג JSON בפורמט יפה.

3. השתמשנו ב-SoapUI לבדיקת POST, אימות בסיסי ולבדיקת בקשת ה-HTTP הגולמית והודעות התגובה.

https://www.soapui.org/

4. ה-CURL הכלי שימושי להגשת בקשות POST עם אימות בסיסי. ראה אקסampלה למטה.

https://curl.haxx.se/

curl פרסם \
-H "Content-Type: application/x-www-form-urlמקודד" \
-H "הרשאה: בסיסית am9objpjaGFuZ2VtZSA=" \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”

_______________

שינוי תקשורת מותאמת אישית