LINK Mobility Implementation Guide REST API SMS
LINK Mobility disponigas servon por mesaĝo livero, mikropagoj, kaj lok-bazitaj servoj. La platformo funkcias kiel travidebla, blank-etikedo enhavakiranto kaj transakcia enkursigilo inter Servaj Provizantoj kaj Operaciantoj.
LINK Mobility disponigas RESTfulan API kiu povas esti uzata por aliri LINK Mobility-servojn kiel sendi SMS. Ĉi tiu API estas desegnita por esti facile uzebla kaj kongrua kun ĉiuj modernaj lingvoj kaj kadroj. Uzante la lingvon de via elekto, via aplikaĵo povas uzi la Link Mobility REST API por efektivigi potencajn mesaĝajn kaj pagajn kapablojn
© LINK Mobility, la 10-an de marto 2021
Jura Informo
La informoj provizitaj en ĉi tiu dokumento estas la sola proprieto kaj kopirajto de Netsize. Ĝi estas konfidenca kaj destinita por strikte informa uzo. Ĝi ne estas deviga kaj povus esti submetata al ŝanĝoj sen avizo. Ĉiu neaŭtorizita malkaŝo aŭ uzo estos konsiderata kiel kontraŭleĝa.
Netsize™ kaj linkmobility™ estas protektataj de francaj, EEC kaj internaciaj leĝoj pri intelekta proprieto.
Ĉiuj aliaj varmarkoj cititaj estas la sola posedaĵo de siaj respektivaj posedantoj.
Nenio ĉi tie estas interpretita kiel permeso aŭ rajto sub Netsize patento, kopirajto aŭ varmarko.
NETSIZE
Société anonyme au capital de 5 478 070 eŭroj
Siège social :62, avenuo Emile Zola92100 Boulogne – Francio
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Amplekso de Dokumento
Ĉi tiu dokumento priskribas kiel la Servoprovizanto uzas la LINK Mobility REST API por SMS. Ĝi estas destinita por teknikaj arkitektoj kaj projektistoj, kiuj efektivigas la servojn de la Servoprovizanto.
1. Baza Uzado
Estas tre facile sendi SMS. Vi sendas HTTP-peton al LINK Mobility kiu povas esti plenumita uzante nur a web retumilo.
2. Funkcia Superview
La LINK Mobility-sistemo disponigas la jenan bazan funkcion por SMS-mesaĝoj:
Sendi Poŝtelefonajn Finitajn (MT) SMS-mesaĝojn, kiel tekstajn aŭ binarajn (ekz. WAP Push) superajn kaj normajn tarifmesaĝojn.
Ricevante liverajn raportojn por senditaj MT-mesaĝoj.
Ricevante Poŝtelefonajn Originajn (MO) SMS-mesaĝojn, altkvalitan kaj norman tarifon.
La SMS REST API estas dediĉita al sendado de norma tarifo MT SMS-mesaĝoj.
La API sendas ĉiujn SMS-mesaĝojn nesinkrone, ebligante funkciojn kiel:
"Fajru kaj forgesu" - la Servoprovizanto volas havi pli antaŭvideblajn respondajn tempojn kaj ne volas atendi la rezulton de la Operaciisto.
Reprovi funkciecon - LINK Mobility resendos la mesaĝon se la Operaciisto havas provizorajn problemojn.
2.1 Sendi SMS-mesaĝon
Servoprovizanto Netsize Konsumanto
- Sendu MT-mesaĝon
- Resendu mesaĝon ID
- Sendu SMS-mesaĝon
- Liveru liveran raporton
- Sendu liveran raporton
La baza fluo por sendi SMSajn mesaĝojn estas priskribita jene:
La Servoprovizanto petas sendi SMS-mesaĝon al ricevanto per la sistemo LINK Mobility.
Mesaĝa ID estas resendita al la Servoprovizanto. Ĉi tiu identigilo povas esti uzata por ekz. korelacii la mesaĝon kun la ĝusta liveraporto.
LINK Mobility pritraktas vojigon kaj liveras la SMS-mesaĝon al la alparolata Konsumanto.
Livera raporto estas ekigita, ekz. kiam la SMS-mesaĝo estas liverita al la aparato de la Konsumanto.
La transdona raporto estas sendita al la Servoprovizanto. La raporto enhavas la saman mesaĝon-identigilon kiel resenditan en la paŝo 2.
Alternativa fluo: Nevalida peto
Se la provizitaj parametroj aŭ uzantkreditaĵoj en la peto estas nevalidaj, eraro estas resendita al la Servoprovizanto. La eraro indikas la kialon de la malakcepto kaj la fluo finiĝas. Neniuj mesaĝidentigiloj estas resenditaj.
3. Finpunkto
La SMS-rimedo estas alirita per la vojo:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Por konekta sekureco la LINK Mobility REST API estas nur alirebla per HTTPS.
La servila atestilo de Link Mobility estas subskribita de Thawte Server CA.
4. Operacioj
La SMS-servo disponigas la jenajn operaciojn:
| Nomo | Vojo |
| Sendu | /restapi/v1/sms/send |
4.1 Sendu
La senda operacio estas uzata por sendi SMS al ununura ricevanto.
Ĉi tiu operacio estas destinita kaj por bazaj kaj progresintaj uzantoj. En la plej simpla kazo, nur cela adreso, kaj la mesaĝteksto estas postulataj por liveri SMS. LINK Mobility detektos la Datuman Kodigan Skemon kaj faros aŭtomatan kunligon de mesaĝo en plurajn mesaĝajn partojn se necese.
Por altnivela uzado, la Servoprovizanto povas uzi laŭvolajn parametrojn por totala kontrolo de la mesaĝformatado inkluzive de la uzanta datumokapo.
La Servoprovizanto povas sendi kunligitajn mesaĝojn, sed la preparado de la uzantdatumoj kaj uzantdatumkapo devas esti farita de la Servoprovizanto kaj la mesaĝo devas esti sendita per multoblaj sendaj petoj al LINK Mobility.
5. Aŭtentikigo
Uzantnomo kaj pasvorto estas senditaj en ĉiu peto uzante HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Akreditaĵoj estas senditaj en Rajtigo-kapo en la HTTP-peto. La kliento konstruas la kaplinion kiel priskribite ĉi tie:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Por ekzample, se la uzantnomo estas john kaj changeme estas la pasvorto, tiam la rezulta Rajtigo-kapo estas:
Rajtigo: Baza am9objpjaGFuZ2VtZSA=
Kiel rezerva la uzantnomo kaj pasvorto povas esti senditaj kiel petaj parametroj. Ĉi tio estas rekomendita nur por klientoj, kiuj ne subtenas Basic Auth.
6. Sendante peton
6.1 Demanda ĉeno
Petaj parametroj estas senditaj kiel demandŝnuro enhavanta nom/valorparojn. La demandŝnuro estas kodita per Procenta Kodado (URL kodado).
http://www.w3schools.com/tags/ref_urlencode.asp
Por ekzample, Saluton Mondo! estas kodita kiel Hello+World%21.
6.2 Devigaj petaj parametroj
| Nomo | Maksimuma longo | Priskribo |
| destinoAdreso | 40 | La MSISDN al kiu la SMS-mesaĝo devas esti sendita, komencante per landokodo. Ekzample: 46123456789. Por iuj merkatoj (kie la Konsumanto MSISDN devas esti malklarigita) ĉi tiu valoro ankaŭ povas esti alfanombra kaŝnomo, prefiksita per "#". |
| mesaĝoTeksto | 1600 | La enhavo de SMS-mesaĝo. |
6.3 Laŭvolaj petaj parametroj (por altnivela uzado)
| Nomo | Maksimuma longo | Priskribo |
| origina Adreso | 16 | La origina adreso por la eksiĝinta SMS-mesaĝo. Tipo de origina adreso estas difinita per la parametro originatorTON. Maksimuma longo de mallonga nombro estas 16. Alfanombra sendinto estas limigita al GSM defaŭlta Alfabeto kun maksimuma longo de 11 signoj. MSISDN-maksimuma longo de sendinto estas 15 (uzante la saman formaton kiel la elemento Address de destino). Povas esti preterlasita kiam originingAddress kaj originatingTON estas elektitaj de la sistemo. Ĉi tiu funkcio dependas de merkato kaj agordo. Konduto povas varii laŭ Operator-integriĝoj. |
| kreintoTON | 1 | La numero-tipo de la origina adreso (TON): 0 – Mallonga nombro 1 - Alfanombra (maksimuma longo 11) 2 - MSISDN Povas esti preterlasita kiam originingAdreso kaj originatingTON estos elektita de la sistemo. Ĉi tiu funkcio dependas de merkato kaj agordo. Konduto povas varii laŭ Operator-integriĝoj. |
| userDataHeader | 280 | Uzanto-datumo-kapo kune kun la uzant-datumo povas enhavi ĝis 140, t.e. 280 kiam heks-kodigitaj, oktetoj. Ĉi tiu parametro estas ĉiam deks-kodita. |
| DCS | 3 | Datumkodiga skemo. Konduto povas varii laŭ Operator-integriĝoj. |
| PID | 3 | Protokolo ID. Konduto povas varii laŭ Operator-integriĝoj. |
| relativeValidityTime | 6 | Relativa validectempo en sekundoj (rilate al la tempo por la submetiĝo al LINK Mobility). Maksimuma valoro estas 604800 (7 tagoj) kaj la defaŭlta estas 48 horoj. Konduto povas varii laŭ Operator-integriĝoj. |
| livertempo | 20 | Timestamp kiam SMS-mesaĝo devas esti transdonita (malfrua livertempo). Vidu sekcion pri data tempo formato. |
| statusReportFlags | 1 | Liveru raportpeton: 0 - Neniu livera raporto (defaŭlte) 1 – Livera raporto petita 9 - Servila livera raporto petita (LINK Mobility ne plusendas la raporton al la Servoprovizanto sed disponigas ĝin en raportoj ktp.) |
| campaignName | 50 | La LINK Mobility-transakcioj estas tagged kun ĉi tiu nomo. Ĝi estas uzata por grupigi transakciojn en raportoj de Link Mobility. |
| maxConcatenatedMessages | 1 | Valoro inter 1 kaj 10 kiu difinas kiom da kunligitaj mesaĝoj kiuj estas permesitaj. Defaŭlte estas 3. |
| korelacioId | 100 | ID provizita de Servoprovizanto, kiu estos ripetita en Livera Raporto. |
| uzantnomo | 100 | Provizite kiel alternativo al HTTP Baza Aŭtentigo. |
| pasvorto | 100 | Provizite kiel alternativo al HTTP Baza Aŭtentigo. |
6.4 HTTP-Peto-Metodoj
Por maksimuma kunfunkciebleco, la API subtenas ambaŭ petajn metodojn HTTP GET kaj POST. Neniuj aliaj HTTP-metodoj estas permesitaj.
6.4.1 GET
La kodita demandŝnuro estas almetita al la URL.
GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Saluton+Mondo%21
Rajtigo: Baza am9objpjaGFuZ2VtZSA=
6.4.2 POST
La kodita demandŝnuro estas sendita en la HTTP-peta mesaĝkorpo. Enhavo-Tipo estas aplikaĵo/x-www-form-urlkodita.
POST https://europe.ipx.com/restapi/v1/sms/send
Gastiganto: europe.ipx.com
Enhava-Tipo: application / x-www-form-urlkodita
Rajtigo: Baza am9objpjaGFuZ2VtZSA=
Enhavo-longo: 57
destinationAddress=46123456789&messageText=Saluton+World%21
6.5 Dato kaj horo
Parametroj en la REST API reprezentantaj daton kaj horon ĉiam estas en UTC-horzono (Coordinated Universal Time). Timestamps estas reprezentitaj kiel ĉeno kun ĉi tiu preciza formato:
2017-04-25T23:20:50Z
Ĉi tio reprezentas 20 minutojn kaj 50 sekundojn post la 23-a horo de la 25-a de aprilo 2017 en UTC.
7. Respondmesaĝo
Post ricevado kaj interpretado de petomesaĝo la API respondas per HTTP-respondmesaĝo.
7.1 HTTP-statusa kodo
La REST API ĉiam resendas HTTP-statuskodon 200 OK por prilaboritaj petoj. La mesaĝkorpo enhavas parametron respondkodon, kiu estas uzata por determini la precizan rezulton.
7.2 Mesaĝkorpo
La mesaĝkorpo konsistas el JSON priskribanta la rezulton de la peto.
http://json.org/
Link Mobility JSON konformas al la Stilo-Gvidilo de Google JSON.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Respondaj parametroj
| Nomo | Maksimuma longo | Priskribo |
| respondkodo | 3 | 0 indikas sukcesan transakcion. |
| respondMesaĝo | 255 | Responda teksta priskribo, ekz. erara teksto. |
| timestamp | 20 | Dato kaj horo kiam LINK Mobility prilaboris la peton. (Vidu al la sekcio de formato de dato/hora). |
| traceId | 36 | Interna identigilo de Link Mobility. Uzita por subteno kaj solvo de problemoj. |
| mesaĝidentoj | 10 x 36 | Tabelo de unikaj mesaĝidentigiloj de LINK Mobility por ĉiu sukcesa mesaĝo (multoblaj mesaĝidentigiloj estas resenditaj se la mesaĝo estas kunligita). Forlasita en kazo de fiasko. |
7.4 Ekzample respondoj
Sukceso
HTTP/1.1 200 Bone
Enhavo-Tipo: aplikaĵo/json
Enhavo-longo: 144
Dato: ĵaŭ, 15 sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Sukceso”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Jen la sama JSON formatita por legebleco:
{
“respondkodo":0,
“respondMesaĝo":"Sukceso",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“mesaĝidentoj":["1-4850879008"] }
Fiasko
HTTP/1.1 200 Bone
Enhavo-Tipo: aplikaĵo/json
Enhavo-longo: 148
Dato: ĵaŭ, 15 sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nevalida ensaluto aŭ neaŭtorizita API-uzado”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Sukceso
HTTP/1.1 200 Bone
Enhavo-Tipo: aplikaĵo/json
Enhavo-longo: 144
Dato: ĵaŭ, 15 sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Sukceso”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Jen la sama JSON formatita por legebleco:
{
“respondkodo":0,
“respondMesaĝo":"Sukceso",
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“mesaĝidentoj":["1-4850879008"] }
Fiasko
HTTP/1.1 200 Bone
Enhavo-Tipo: aplikaĵo/json
Enhavo-longo: 148
Dato: ĵaŭ, 15 sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nevalida ensaluto aŭ neaŭtorizita API-uzado”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Respondkodoj
La sekvaj respondkodoj povas esti resenditaj en la senda respondo:
| Kodo | Teksto | Priskribo |
| 0 | Sukceso | Sukcese efektivigita. |
| 1 | Nevalida ensaluto aŭ neaŭtorizita API-uzado | Malĝusta uzantnomo aŭ pasvorto aŭ Servoprovizanto estas malpermesita de LINK Mobility. |
| 2 | Konsumanto estas blokita de Link Mobility | La Konsumanto estas blokita de LINK Mobility. |
| 3 | Funkciado ne estas provizita de LINK Mobility | La operacio estas blokita por la Servoprovizanto. |
| 4 | La konsumanto estas nekonata de LINK Mobility | La Konsumanto estas nekonata al LINK Mobility. Aŭ se kaŝnomo estis uzata en la peto; kaŝnomo ne trovita. |
| 5 | Konsumanto blokis ĉi tiun servon en LINK Mobility | La Konsumanto blokis ĉi tiun servon en LINK Mobility. |
| 6 | La origina adreso ne estas subtenata | La origina adreso ne estas subtenata. |
| 7 | Alfa-devena adreso ne subtenata de konto | La alfa-devena adreso ne estas subtenata de konto. |
| 8 | MSISDN-devena adreso ne subtenata | La origina adreso de MSISDN ne estas subtenata. |
| 9 | GSM etendita ne subtenata | GSM etendita ne subtenata. |
| 10 | Unikodo ne subtenata | Unikodo ne subtenata. |
| 11 | Staturaporto ne subtenata | Staturaporto ne subtenata. |
| 12 | Bezonata kapablo ne subtenata | La bezonata kapablo (krom la supre) por sendi la mesaĝon ne estas subtenata. |
| 13 | La enhavprovizanto-maksimuma strigla indico estas superita | La Servoprovizanto sendas la SMS-mesaĝojn al LINK Mobility tro rapide. |
| 14 | Protokolo ID ne subtenata de konto | Protokolo ID ne subtenata. |
| 15 | Mesaĝa limo superita | La nombro da kunligitaj mesaĝoj superas la maksimuman nombron petitan. |
| 16 | Ne eblas direkti mesaĝon. | LINK Mobility ne povis direkti la mesaĝon. |
| 17 | Malpermesita tempoperiodo | Ne permesite sendi mesaĝon dum tempoperiodo |
| 18 | Tro malalta ekvilibro en konto de servoprovizanto | Servoprovizanto estas blokita pro Tro malalta ekvilibro |
| 50 | Parta sukceso | Parta sukceso kiam vi sendas SMS-mesaĝon al pluraj ricevantoj. |
| 99 | Interna servila eraro | Alia eraro de Link Mobility, kontaktu LINK Mobility-subtenon por pliaj informoj. |
| 100 | Nevalida cela adreso | La cela adreso (MSISDN, aŭ kaŝnomo) estas nevalida. |
| 102 | Nevalida referencita (ligita) ID | La referenca ID estas nevalida, eble la referenca ID estas jam uzata, tro malnova aŭ nekonata. |
| 103 | Nevalida kontonomo | La kontnomo estas nevalida. |
| 105 | Nevalidaj servaj metadatenoj | La metadatumoj de la servo estas nevalidaj. |
| 106 | Nevalida devena adreso | La origina adreso estas malvalida. |
| 107 | Nevalida alfanombra origina adreso | La alfanombra origina adreso estas malvalida. |
| 108 | Nevalida validtempo | La validectempo estas nevalida. |
| 109 | Nevalida livertempo | La livertempo estas nevalida. |
| 110 | Nevalida mesaĝo enhavo/uzantdatenoj | La uzantdatenoj, te la SMS-mesaĝo, estas nevalidaj. |
| 111 | Nevalida mesaĝolongo | La longeco de SMS-mesaĝo estas nevalida. |
| 112 | Nevalida kaplinio pri uzanto-datumoj | La kaplinio de uzantdatumoj ne validas. |
| 113 | Nevalida datuma kodiga skemo | La DCS estas nevalida. |
| 114 | Nevalida protokolo ID | La PID estas nevalida. |
| 115 | Nevalidaj statoraportmarkoj | La flagoj de statoraporto estas nevalidaj. |
| 116 | Nevalida TON | La kreinto TON estas nevalida. |
| 117 | Nevalida ĉampaign nomo | La ĉampaign-nomo estas nevalida. |
| 120 | Nevalida limo por maksimuma nombro da kunligitaj mesaĝoj | La maksimuma nombro da kunligitaj mesaĝoj estas nevalida. |
| 121 | Nevalida devena adreso de msdn | La origina adreso de MSISDN estas malvalida. |
| 122 | Nevalida korelacia ID | La korelacia ID estas nevalida. |
8. Laŭvolaj trajtoj
8.1 MSISDN-Korekto
MSISDN-korekto estas laŭvola funkcio, kiu povas esti ebligita de LINK Mobility-subteno se pete.
Ĉi tiu funkcio korektos celajn adresojn kaj vicigos ilin al la bezonata E.164-formato. Aldone al formatĝustigo la sistemo ankaŭ povas elfari merkatspecifan funkciecon kiel ekzemple tradukado de internaciaj francaj nombroj por korekti DOM-TOM (départements et territoires d'outre-mer) nombrojn kiam uzeble.
Malsupre estas kelkaj ekzampkorektoj:
| Sendita Celo-Adreso | Korektita Celo-Adreso |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Franca nombro tradukita al DOM-TOM-nombro) |
Aldone, eblas permesi naciajn telefonnumerojn por elektita merkato. Kiam ĉi tiu funkcio estas ebligita, ĉiuj internaciaj nombroj por aliaj merkatoj devas esti senditaj kun komenca signo "+" por distingi ilin de la elektita merkato.
Malsupre estas pluraj ekzampkorektoj faritaj uzante Svedion (landkodo 46) kiel defaŭltan merkaton por naciaj nombroj.
| Sendita Celo-Adreso | Korektita Celo-Adreso |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Nevalida ĉar la signo '+' mankas |
Notu, ke la korektita MSISDN estos uzata de LINK Mobility kaj ĝi estos resendita en la transdonaj raportoj.
Bonvolu kontakti LINK Mobility-subtenon por pliaj informoj.
8.2 Anstataŭigo de Signoj
Karaktero-anstataŭigo estas laŭvola funkcio, kiu povas esti ebligita de LINK Mobility-subteno se pete.
Ĉi tiu funkcio tradukos ne-GSM-alfabetajn signojn en la uzantdatumoj (SMS-teksto) al ekvivalentaj GSM-alfabetaj signoj kiam la DCS estas agordita al "GSM" (17). Por ekzample “Seqüência de teste em Português” estos tradukita al “Seqüencia de teste em Portugues”.
9. Liveraj raportoj
La Servoprovizanto povas, se provizita, peti raportojn pri transdono de SMS-mesaĝoj aŭ sciigojn pri liverado de la MT-mesaĝoj senditaj. Ĉi tiuj raportoj estas ekigitaj en la Operaciisto SMSC kiam la MT-mesaĝo estas aŭ liverita al la celata Konsumanto aŭ forigita, ekz., eksvalidiĝinta aŭ, ial, ne enrugebla.
Nur fina stato de la SMS-mesaĝo estas raportita al la Servoprovizanto, t.e., transdonita aŭ forigita. Nur unu raporto per MT-mesaĝo estas generita. Kun la forigita statuso, kialo-kodo povas validi. Ĉi tiu kaŭzokodo precizigas la kialon por ke la SMS-mesaĝo ne estas liverita.
La raportoj estas senditaj per LINK Mobility kaj senditaj al la Servoprovizanto uzante la HTTP-protokolon.
Por ricevi raportojn, la Servoprovizanto devas efektivigi ekzamplevu Java Servlet aŭ paĝon ASP.NET. Ambaŭ ricevas petojn HTTP GET aŭ POST.
Parametroj
La peto inkluzivas la jenajn parametrojn:
| Parametro | Tajpu | M/O/I* | Defaŭlta Valoro | Maksimuma longo | Priskribo |
| MessageId | ŝnuro | M | – | 22 | La mesaĝo ID de la MT-mesaĝo al kiu ĉi tiu raporto respondas. |
| Destinadreso | ŝnuro | M | – | 40 | La MSISDN de la Konsumanto, te la cel-adreso de la origina MT-mesaĝo. |
| StatusCode | entjero | M | 1 | Statuskodo indikas la staton de la MT-mesaĝo. Aplikeblaj statuskodoj estas: 0 – Liverita 2 - Forigita (kiala kodo validas) |
|
| Tempo St.amp | ŝnuro | M | – | 20 | Tempo indikanta kiam la liveraporto estis ricevita de LINK Mobility. La horzono de la tempojamp estas CET aŭ CEST (kun somera horo kiel difinita por EU). Formato: jjjjMMj HH:mm:ss. |
| Operatoro | ŝnuro | M | – | 100 | La nomo de la Operaciisto uzata dum sendado de la SMS-mesaĝo aŭ la kontonomo uzata dum sendado de la SMS-mesaĝo. Listo de disponeblaj Operaciantoj estas provizita de LINK Mobility-subteno. |
| ReasonCode | entjero | O | – | 3 | Kialokodo indikas kial la mesaĝo finiĝis en la statuso forigita. Apkeblaj kialo-kodoj estas: 100 - Eksvalidiĝis 101 – Malakceptita 102 – Formateraro 103 – Alia eraro 110 - Abonanto nekonata 111 – Abonanto malpermesita 112 – Abonanto ne provizita 113 – Abonanto nedisponebla 120 - Fiasko de SMSC 121 - SMSC-ŝtopiĝo 122 - SMSC vaganta 130 - Eraro de la telefontelefono 131 – Telefona memoro superita Konduto povas varii laŭ Operator-integriĝoj. |
| OperatorTimeStamp | ŝnuro | O | – | 20 | Tempo indikanta kiam la raporto estis ekigita en la SMSC de la Operaciisto (se provizite de la Operaciisto). La horzono de la tempojamp estas CET aŭ CEST (kun somera horo kiel difinita por EU). Formato: jjjjMMj HH:mm:ss. |
| StatusTexto | ŝnuro | O | – | 255 | Anstataŭilo por pliaj informoj de la Operaciisto, ekz. klarteksta priskribo de la stato/kialo. Konduto povas varii laŭ Operator-integriĝoj. |
| KorelacioId | ŝnuro | O | – | 100 | La korelacia ID provizita en la SendRequest aŭ SendTextRequest. |
| OperatorNetworkCode | entjero | O | – | 6 | La Poŝtelefona Reto Kodo (MCC + MNC) de la Operaciisto. |
* M = Deviga, O = Nedeviga, I = Ignorita.
La Servoprovizanto devas provizi LINK Mobility kun la celo URL por liverraportoj (laŭvole inkluzive de akreditaĵoj por HTTP-baza aŭtentigo). La Servoprovizanto povas elekti kiun preferatan HTTP-metodon uzi:
HTTP POST (rekomendita)
HTTP GET.
Example uzanta HTTP GET (sukcese liverita):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example uzanta HTTP GET (ne liverita, la Operaciisto liveris tempon plejamp por la evento):
La parametroj estas URL encodedi.
Karaktera kodado:
La Servoprovizanto povas elekti kiun preferatan kodigon de karakteroj uzi:
UTF-8 (rekomendita)
ISO-8859-1.
9.1 Agnosko de Servoprovizanto
La Servoprovizanto devas agnoski ĉiun liveran raporton. La agnosko povas esti pozitiva, t.e. transdona raporto sukcese ricevita, aŭ negativa, t.e. malsukceso.
Bonvolu noti: LINK Mobility havas legtempon por agnoskoj de 30 sekundoj por liveraj raportoj. Tempo ekigos liveran reprovon (se reprovo ebligita) aŭ nuligon de la livero (se reprovo malŝaltita). Ĉi tio signifas, ke la aplikaĵo de Servoprovizanto devas certigi rapidajn respondajn tempojn, precipe dum alta ŝarĝo.
Estas tre rekomendite agnoski la transdonan raporton al LINK Mobility antaŭ ol prilabori ĝin.
La regulo por pozitiva kaj negativa agnosko estas priskribita jene:
Pozitiva agnosko, ACK, livera raporto liverita:
HTTP 200-intervala respondkodo en kombinaĵo kun la sekva XML formatita enhavo:
Negativa agnosko, NAK, livera raporto ne liverita:
Ajna respondo krom pozitiva agnosko, ekzample, negativa agnosko estas ekigita de iu HTTP-erara kodo aŭ la sekva XML-enhavo:
La XML-enhavo povas esti uzata por kontroli la LINK Mobility-reprovan mekanismon. NAK kaŭzos reprovon, se ĝi estas ebligita. Por Servaj Provizantoj ne agordis por la reprova mekanismo, la XML-enhavo estas laŭvola.
Malsupre estas HTTP-POST-peto kaj respondo ekzampdosiero de transdona raporto transdonita al Servoprovizanto:
HTTP-Peto:
POST/kunteksto/app HTTP/1.1
Enhava-Tipo: application / x-www-form-urlkodita;charset=utf-8
Gastiganto: servilo:porto
Enhavo-longo: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-Respondo:
HTTP/1.1 200 Bone
Enhavo-Tipo: teksto/ebenaĵo
9.2 Reprovi
La LINK Mobility-sistemo povas fari reprovojn por malsukcesaj, t.e. ne agnoskitaj, liveraj raportoj. La Servoprovizanto povas elekti la preferatan reprovan konduton:
Neniu reprovo (defaŭlte) - la mesaĝo estos forĵetita se la provo de konekto malsukcesas, legu tempo-malpermeson aŭ por ajna HTTP-erara kodo.
Reprovi – la mesaĝo estos resendita por ĉiu speco de konektoproblemo, legotempo aŭ negativa agnosko.
Kiam reprovo por NAK estas ebligita, estas grave kompreni kiuj scenaroj generos reprovan provon de LINK Mobility kaj kiel la reprovo funkcias. Ĉiu Servoprovizanto havas sian propran reprovovicon, kie mesaĝoj estas ordigitaj laŭ la mesaĝtempoamp. Link Mobility ĉiam provas liveri pli malnovajn mesaĝojn unue, kvankam la individua ordo de mesaĝoj liverita al la Servoprovizanto ne estas garantiita. La ĉefa kialo por ke mesaĝoj estas forĵetitaj de la reprovovico estas unu el du kialoj: aŭ la mesaĝo TTL eksvalidiĝas aŭ (teorie) la reprovovico iĝas plena. La TTL estas Funkciisto kaj konto dependa, t.e., povas varii depende de Operaciisto kaj aŭ mesaĝo-tipo, ekz., altkvalita SMS aŭ norma tarifo SMS-mesaĝo.
Servoprovizantoj kun reprovo ebligita devas kontroli la unikan identigilon de la MT-mesaĝo por certigi, ke la mesaĝo ne jam estis ricevita.
Gravas por la Servoprovizanto observi ĉi tiujn simplajn regulojn kiam eraro okazas dum la prilaborado de transdona raporto se la kialo de la eraro estas: Provizora, ekz. datumbazo ne havebla, NAK estu resendita. LINK Mobility resendos la mesaĝon.
Konstanta kaj reprovo verŝajne kaŭzos la saman specon de problemo, ACK devus esti resendita. Por ekzample, kiam la mesaĝo ne povis esti ĝuste analizita aŭ kaŭzis neatenditan rultempan eraron.
Agi laŭe certigos, ke neniu blokado aŭ trairado-degenero estas kaŭzita pro livera raporto resendita plurfoje.
10. Efektivigaj konsiletoj
1. Eblas uzi vian web retumilo por sendi petojn al la API. Ĉi tio tre facilas esplori kaj taksi la servojn sen iuj disvolvaj iloj.
2. Kromo aŭ Fajrovulpo estas rekomenditaj kune kun etendaĵo kiel JSONView por montri bele formatitan JSON.
3. Ni uzis SoapUI por testi POST, Bazan Aŭtentigon kaj por inspekti la krudajn HTTP-petojn kaj respondajn mesaĝojn.
4. La ĉURL ilo estas utila por sendi POST-petojn kun Baza Aŭtentigo. Vidu ekzample sube.
curl POST \
-H "Enhavo-Tipo: aplikaĵo/x-www-formo-urlkodita” \
-H “Rajtigo: Baza am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–datumoj “destinationAddress=46123456789&messageText=Saluton+World%21”
_______________
Transformante personigitajn komunikadojn
Dokumentoj/Rimedoj
 |
LINK Mobility Implementation Guide REST API SMS [pdf] Uzantogvidilo Moviĝebla Efektiviga Gvidilo REST API SMS, Moviĝeblo, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
