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 Нантэр
http://www.LinkMobility.com
http://www.linkmobility.com
Аб'ём дакумента
У гэтым дакуменце апісваецца, як Пастаўшчык паслуг выкарыстоўвае API LINK Mobility REST для SMS. Прызначана для тэхнічных архітэктараў і дызайнераў, якія рэалізуюць паслугі Пастаўшчыка паслуг.
1. Асноўнае выкарыстанне
Адправіць SMS вельмі проста. Вы адпраўляеце HTTP-запыт у LINK Mobility, які можа быць выкананы з дапамогай проста a web браўзер.
2. Функцыянальнае надview
Сістэма LINK Mobility забяспечвае наступныя асноўныя функцыі для SMS-паведамленняў:
Адпраўка мабільных тэрмінаваных (MT) SMS-паведамленняў, такіх як тэкставыя або двайковыя (напрыклад, WAP Push) платныя і стандартныя паведамленні.
Атрыманне справаздач аб дастаўцы адпраўленых паведамленняў МТ.
Атрыманне SMS-паведамленняў з мабільнага тэлефона (MO), прэміум і стандартны тарыф.
API SMS REST прызначаны для адпраўкі SMS-паведамленняў MT са стандартнай хуткасцю.
API адпраўляе ўсе SMS-паведамленні асінхронна, дазваляючы такія функцыі, як:
«Спаліў і забыўся» - Пастаўшчык паслуг хоча мець больш прадказальны час водгуку і не жадае чакаць выніку ад Аператара.
Функцыя паўторнай спробы – LINK Mobility паўторна адправіць паведамленне, калі ў аператара ўзнікнуць часовыя праблемы.
2.1 Адпраўка SMS-паведамлення
Пастаўшчык паслуг Netsize Consumer
- Адправіць паведамленне MT
- Ідэнтыфікатар зваротнага паведамлення
- Адправіць SMS-паведамленне
- Даставіць справаздачу аб дастаўцы
- Адправіць справаздачу аб дастаўцы
Асноўны працэс адпраўкі 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/адправіць |
4.1 Адправіць
Аперацыя адпраўкі выкарыстоўваецца для адпраўкі SMS аднаму атрымальніку.
Гэтая аперацыя прызначана як для звычайных, так і для прасунутых карыстальнікаў. У самым простым выпадку для дастаўкі SMS патрабуецца толькі адрас прызначэння і тэкст паведамлення. LINK Mobility выявіць схему кадавання даных і пры неабходнасці выканае аўтаматычнае аб'яднанне паведамлення ў некалькі частак.
Для пашыранага выкарыстання Пастаўшчык паслуг можа выкарыстоўваць дадатковыя параметры для поўнага кантролю фарматавання паведамлення, уключаючы загаловак карыстальніцкіх даных.
Пастаўшчык паслуг можа адпраўляць злучаныя паведамленні, але падрыхтоўка даных карыстальніка і загалоўка даных карыстальніка павінна быць зроблена Пастаўшчыком паслуг, і паведамленне павінна быць адпраўлена з дапамогай некалькіх запытаў адпраўкі ў LINK Mobility.
5. Аўтэнтыфікацыя
Імя карыстальніка і пароль адпраўляюцца ў кожным запыце з выкарыстаннем базавай схемы аўтэнтыфікацыі HTTP.
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 — пароль, то выніковы загаловак аўтарызацыі:
Аўтарызацыя: Basic am9objpjaGFuZ2VtZSA=
У якасці запаснага варыянту імя карыстальніка і пароль можна падаць у якасці параметраў запыту. Гэта рэкамендуецца толькі для кліентаў, якія не падтрымліваюць Basic Auth.
6. Падача запыту
6.1 Радок запыту
Параметры запыту падаюцца ў выглядзе радка запыту, які змяшчае пары імя/значэнне. Радок запыту закадаваны з дапамогай працэнтнага кадавання (URL кадзіроўка).
http://www.w3schools.com/tags/ref_urlencode.asp
Напрыкладample, прывітанне, свет! кадуецца як Hello+World%21.
6.2 Абавязковыя параметры запыту
| Імя | Максімальная даўжыня | Апісанне |
| адрас прызначэння | 40 | MSISDN, на які трэба адправіць SMS, пачынаючы з кода краіны. напрыкладampЛе: 46123456789. Для некаторых рынкаў (дзе спажывецкі MSISDN павінен быць абфускаваным) гэта значэнне таксама можа быць літарна-лічбавым псеўданімам з прэфіксам «#». |
| паведамленнеТэкст | 1600 | Змест смс паведамлення. |
6.3 Дадатковыя параметры запыту (для пашыранага выкарыстання)
| Імя | Максімальная даўжыня | Апісанне |
| паходны адрас | 16 | Пачатковы адрас для выходнага SMS-паведамлення. Тып першапачатковага адраса вызначаецца параметрам originatorTON. Максімальная даўжыня кароткага нумара - 16. Літарна-лічбавы адпраўшчык абмежаваны стандартным алфавітам GSM з максімальнай даўжынёй 11 сімвалаў. Максімальная даўжыня адпраўніка MSISDN складае 15 (з выкарыстаннем таго ж фармату, што і элемент destinationAddress). Можа быць апушчаны, калі originatingAddress і originatingTON выбраны сістэмай. Гэта функцыя залежыць ад рынку і канфігурацыі. Паводзіны могуць адрознівацца ў залежнасці ад інтэграцыі аператара. |
| стваральнікTON | 1 | Тып нумара першапачатковага адраса (TON): 0 – Кароткі нумар 1 – Літарна-лічбавы (максімальная даўжыня 11) 2 – MSISDN Можа быць апушчаны, калі originatingAddress і originatingTON будуць выбраны сістэмай. Гэтая функцыя залежыць ад рынку і канфігурацыі. Паводзіны могуць адрознівацца ў залежнасці ад інтэграцыі аператара. |
| userDataHeader | 280 | Загаловак даных карыстальніка разам з данымі карыстальніка можа ўтрымліваць да 140, г.зн. 280 у шаснаццатковым кадзіраванні, актэтаў. Гэты параметр заўсёды закадаваны ў шаснаццатковай форме. |
| 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з гэтай назвай. Ён выкарыстоўваецца для групоўкі транзакцый у справаздачах Link Mobility. |
| maxConcatenatedMessages | 1 | Значэнне ад 1 да 10, якое вызначае колькасць дазволеных аб'яднаных паведамленняў. Па змаўчанні 3. |
| карэляцыяId | 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=Прывітанне+Свет%21
Аўтарызацыя: Basic am9objpjaGFuZ2VtZSA=
6.4.2 ПОСТ
Закадзіраваны радок запыту падаецца ў целе паведамлення HTTP-запыту. Content-Type - прыкладанне/x-www-form-urlзакадзіраваны.
ПОСТ https://europe.ipx.com/restapi/v1/sms/send
Гаспадар: europe.ipx.com
Змест зместу: application / x-www-form-urlзакадзіраваны
Аўтарызацыя: Basic am9objpjaGFuZ2VtZSA=
Працягласць: 57
destinationAddress=46123456789&messageText=Прывітанне+Свет%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 OK для апрацаваных запытаў. Цела паведамлення змяшчае параметр responseCode, які выкарыстоўваецца для вызначэння дакладнага выніку.
7.2 Цела паведамлення
Цела паведамлення складаецца з JSON, які апісвае вынік запыту.
http://json.org/
Link Mobility JSON адпавядае Кіраўніцтву па стылі Google JSON.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Параметры адказу
| Імя | Максімальная даўжыня | Апісанне |
| responseCode | 3 | 0 азначае паспяховую транзакцыю. |
| responseMessage | 255 | Тэкставае апісанне адказу, напрыклад тэкст памылкі. |
| часamp | 20 | Дата і час апрацоўкі запыту LINK Mobility. (Гл. раздзел фармату даты/часу). |
| traceId | 36 | Унутраны ідэнтыфікатар Link Mobility. Выкарыстоўваецца для падтрымкі і ліквідацыі непаладак. |
| messageIds | 10 х 36 | Масіў унікальных ідэнтыфікатараў паведамлення LINK Mobility для кожнага паспяховага паведамлення (вяртаецца некалькі ідэнтыфікатараў паведамленняў, калі паведамленне аб'яднана). Апускаецца ў выпадку няўдачы. |
7.4 практample адказы
Поспех
HTTP/1.1 200 ОК
Тып кантэнту: application/json
Працягласць: 144
Дата: чацвер, 15 верасня 2016 г. 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Поспех”,”часamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Вось той жа JSON, адфарматаваны для зручнасці чытання:
{
“responseCode“:0,
“responseMessage“:”Поспех”,
“час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”,”часamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Поспех
HTTP/1.1 200 ОК
Тып кантэнту: application/json
Працягласць: 144
Дата: чацвер, 15 верасня 2016 г. 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Поспех”,”часamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Вось той жа JSON, адфарматаваны для зручнасці чытання:
{
“responseCode“:0,
“responseMessage“:”Поспех”,
“час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”,”часamp”:”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, звярніцеся ў службу падтрымкі 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 | Несапраўдны campaign імя | вampімя aign несапраўднае. |
| 120 | Няправільны ліміт для максімальнай колькасці аб'яднаных паведамленняў | Максімальная колькасць злучаных паведамленняў несапраўдная. |
| 121 | Няправільны зыходны адрас msisdn | Зыходны адрас MSISDN несапраўдны. |
| 122 | Няправільны ID карэляцыі | Ідэнтыфікатар карэляцыі няправільны. |
8. Дадатковыя функцыі
8.1 Выпраўленне MSISDN
Карэкцыя MSISDN з'яўляецца дадатковай функцыяй, якая можа быць уключана падтрымкай LINK Mobility па запыце.
Гэта функцыя выправіць адрасы прызначэння і прывядзе іх у патрэбны фармат E.164. У дадатак да карэкцыі фармату сістэма можа таксама выконваць спецыфічныя функцыі рынку, такія як пераклад міжнародных нумароў на французскай мове для карэкцыі нумароў DOM-TOM (дэпартаментаў і тэрыторый замежжа), калі гэта магчыма.
Ніжэй прыведзены шэраг эксampспіс выпраўленняў:
| Прадстаўлены адрас прызначэння | Выпраўлены адрас прызначэння |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445ааа | 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 “Seqüência de teste em Português” будзе перакладзена на “Seqüencia de teste em Portugues”.
9. Справаздачы аб дастаўцы
Пастаўшчык паслуг можа, калі гэта прадугледжана, запытваць справаздачы аб дастаўцы SMS-паведамленняў або апавяшчэнняў аб дастаўцы адпраўленых паведамленняў MT. Гэтыя справаздачы ствараюцца ў SMSC аператара, калі паведамленне MT альбо дастаўляецца мэтаваму спажыўцу, альбо выдаляецца, напрыклад, калі яно пратэрмінаванае або па нейкай прычыне не паддаецца маршрутызацыі.
Пастаўшчыку паслуг паведамляецца толькі пра канчатковы статус SMS-паведамлення, г.зн., дастаўлена або выдалена. Для кожнага паведамлення MT ствараецца толькі адна справаздача. Пры выдаленым статусе можа прымяняцца код прычыны. Гэты код прычыны ўказвае прычыну недастаўкі SMS-паведамлення.
Справаздачы накіроўваюцца праз LINK Mobility і адпраўляюцца пастаўшчыку паслуг па пратаколе HTTP.
Каб атрымліваць справаздачы, Пастаўшчык паслуг павінен укараніць, напрыкладampLe Java Servlet або старонка ASP.NET. Абодва атрымліваюць HTTP-запыты GET або POST.
Параметры
Запыт уключае наступныя параметры:
| Параметр | Тып | M/O/I* | Значэнне па змаўчанні | Максімальная даўжыня | Апісанне |
| MessageId | радок | M | – | 22 | Ідэнтыфікатар паведамлення MT, якому адпавядае гэтая справаздача. |
| Адрас прызначэння | радок | M | – | 40 | MSISDN спажыўца, г.зн. адрас прызначэння зыходнага паведамлення MT. |
| Код стану | цэлы лік | M | 1 | Код стану паказвае статус паведамлення MT. Дастасавальныя коды стану: 0 – Дастаўлена 2 – Выдалена (прымяняецца код прычыны) |
|
| ЧасСтamp | радок | M | – | 20 | Час, які паказвае, калі справаздача аб дастаўцы была атрымана LINK Mobility. Часавы пояс часуamp з'яўляецца CET або CEST (з летнім часам, як гэта вызначана для ЕС). Фармат: ГГГГММДД ГГ:хх:сс. |
| Аператар | радок | 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 – Перавышана памяць тэлефона Паводзіны могуць адрознівацца ў залежнасці ад інтэграцыі аператара. |
| Час аператараamp | радок | O | – | 20 | Час спрацоўвання справаздачы ў SMSC Аператара (калі гэта прадугледжана Аператарам). Часавы пояс часуamp з'яўляецца CET або CEST (з летнім часам, як гэта вызначана для ЕС). Фармат: ГГГГММДД ГГ:хх:сс. |
| Тэкст стану | радок | O | – | 255 | Запаўняльнік для дадатковай інфармацыі ад Аператара, напрыклад, тэкставае апісанне стану/прычыны. Паводзіны могуць адрознівацца ў залежнасці ад інтэграцыі аператара. |
| Ідэнтыфікатар карэляцыі | радок | O | – | 100 | Ідэнтыфікатар карэляцыі, прадстаўлены ў SendRequest або SendTextRequest. |
| Код сеткі аператара | цэлы лік | 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 (не дастаўлена, аператар падаў timestamp на мерапрыемства):
Параметры такія 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
Змест зместу: application / x-www-form-urlзакадаваны;набор знакаў=utf-8
Хост: сервер:порт
Працягласць зместу: хх
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-адказ:
HTTP/1.1 200 ОК
Content-Type: тэкст/звычайны
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-запытаў і паведамленняў-адказаў.
4. вURL інструмент карысны для адпраўкі запытаў POST з базавай аўтэнтыфікацыяй. Глядзіце прampніжэй.
curl Апублікаваць \
-H «Тып кантэнту: дадатак/x-www-form-urlзакадаваны” \
-H «Аўтарызацыя: Basic am9objpjaGFuZ2VtZSA=» \
https://europe.ipx.com/restapi/v1/sms/send \
–data «destinationAddress=46123456789&messageText=Hello+World%21»
_______________
Трансфармацыя персаналізаванай камунікацыі
Дакументы / Рэсурсы
 |
LINK Кіраўніцтва па ўкараненні мабільнасці REST API SMS [pdfКіраўніцтва карыстальніка Кіраўніцтва па ўкараненні мабільнасці REST API SMS, мабільнасць, кіраўніцтва па ўкараненні REST API SMS, REST API SMS, API SMS, SMS |
