LINK Mobility Implementation Guide REST API SMS
LINK Mobility pakub sõnumite edastamise, mikromaksete ja asukohapõhiste teenuste teenust. Platvorm toimib teenusepakkujate ja operaatorite vahelise läbipaistva valge märgistusega sisu hankijana ja tehingute ruuterina.
LINK Mobility pakub RESTful API-d, mida saab kasutada juurdepääsuks LINK Mobility teenustele, näiteks SMS-ide saatmiseks. See API on loodud hõlpsasti kasutatavaks ja ühilduvaks kõigi kaasaegsete keelte ja raamistikega. Kasutades teie valitud keelt, saab teie rakendus kasutada Link Mobility REST API-t, et rakendada võimsaid sõnumside- ja maksevõimalusi
© LINK Mobility, 10. märts 2021
Juriidiline teave
Selles dokumendis esitatud teave on Netsize'i ainuomand ja autoriõigus. See on konfidentsiaalne ja mõeldud ainult informatiivseks kasutamiseks. See ei ole siduv ja seda võidakse ette teatamata muuta. Igasugust volitamata avaldamist või kasutamist loetakse ebaseaduslikuks.
Netsize™ ja linkmobility™ on kaitstud Prantsusmaa, EMÜ ja rahvusvaheliste intellektuaalomandi seadustega.
Kõik muud tsiteeritud kaubamärgid on nende vastavate omanike ainuomand.
Midagi siin sisalduvat ei tõlgendata Netsize'i patendi, autoriõiguse või kaubamärgi alusel litsentsi või õigusi andvana.
NETSIZE
Société anonyme au capital de 5 478 070 eurot
Siège social :62, avenue Emile Zola 92100 Boulogne – Prantsusmaa
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Dokumendi ulatus
See dokument kirjeldab, kuidas teenusepakkuja kasutab SMS-i jaoks LINK Mobility REST API-t. See on mõeldud tehnilistele arhitektidele ja projekteerijatele, kes teostavad teenusepakkuja teenuseid.
1. Põhikasutus
SMS-i saatmine on väga lihtne. Saadate HTTP-päringu saidile LINK Mobility, mida saab täita lihtsalt a web brauser.
2. Funktsionaalne üleview
LINK Mobility süsteem pakub SMS-sõnumite jaoks järgmisi põhifunktsioone:
Mobiiliga lõpetatud (MT) SMS-sõnumite, näiteks teksti- või kahendsõnumite (nt WAP Push) lisatasu ja standardtariifiga sõnumite saatmine.
Saadetud MT-sõnumite tarnearuannete vastuvõtmine.
Mobiilist pärinevate (MO) SMS-sõnumite vastuvõtmine tasulise ja tavahinnaga.
SMS REST API on mõeldud standardkiirusega MT SMS-sõnumite saatmiseks.
API saadab kõik SMS-id asünkroonselt, võimaldades selliseid funktsioone nagu:
“Tule-ja-unusta” – Teenusepakkuja soovib etteaimatavamaid reageerimisaegu ega taha oodata operaatorilt tulemust.
Proovige uuesti – LINK Mobility saadab sõnumi uuesti, kui operaatoril on ajutisi probleeme.
2.1 SMS-sõnumi saatmine
Teenusepakkuja Netsize Consumer
- Saada MT sõnum
- Tagasta sõnumi ID
- Saada SMS-sõnum
- Edastage tarnearuanne
- Saatke tarnearuanne
SMS-sõnumite saatmise põhiprotsessi kirjeldatakse järgmiselt.
Teenusepakkuja teeb taotluse saata adressaadile SMS-sõnum LINK Mobility süsteemi kaudu.
Teenusepakkujale tagastatakse sõnumi ID. Seda ID-d saab kasutada näiteks sõnumi korreleerimiseks õige tarneraportiga.
LINK Mobility tegeleb marsruutimisega ja edastab SMS-sõnumi adresseeritud Tarbijale.
Käivitub kohaletoimetamisraport, nt SMS-sõnumi edastamisel Tarbija seadmesse.
Tarnearuanne saadetakse Teenusepakkujale. Aruanne sisaldab sama sõnumi ID-d, mis tagastati sammus 2.
Alternatiivne voog: kehtetu taotlus
Kui päringus esitatud parameetrid või kasutaja mandaadid on kehtetud, tagastatakse teenusepakkujale veateade. Viga näitab tagasilükkamise põhjust ja voog lõpeb. Sõnumi ID-sid ei tagastata.
3. Lõpp-punkt
SMS-i ressursile pääseb juurde teed kasutades:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Ühenduse turvalisuse tagamiseks on LINK Mobility REST API-le juurdepääs ainult HTTPS-i kaudu.
Link Mobility serveri sertifikaadi allkirjastab Thawte Server CA.
4. Operatsioonid
SMS-teenus pakub järgmisi toiminguid:
| Nimi | Tee |
| Saada | /restapi/v1/sms/send |
4.1 Saada
Saatmistoimingut kasutatakse SMS-i saatmiseks ühele adressaadile.
See toiming on mõeldud nii tavakasutajatele kui ka edasijõudnutele. Lihtsamal juhul on SMS-i edastamiseks vaja ainult sihtkoha aadressi ja sõnumi teksti. LINK Mobility tuvastab andmete kodeerimisskeemi ja ühendab vajaduse korral sõnumi automaatse mitmeks sõnumiosaks.
Täpsemaks kasutamiseks saab teenusepakkuja kasutada valikulisi parameetreid sõnumi vormingu täielikuks juhtimiseks, sealhulgas kasutajaandmete päise üle.
Teenusepakkuja võib saata liitsõnumeid, kuid kasutajaandmete ja kasutajaandmete päise peab koostama Teenusepakkuja ning sõnum tuleb saata mitme saatmispäringu teel LINK Mobility suunas.
5. Autentimine
Kasutajanimi ja parool esitatakse iga päringuga, kasutades HTTP põhiautentimisskeemi.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Mandaat saadetakse HTTP päringu autoriseerimispäises. Klient koostab päisevälja, nagu siin kirjeldatud:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Näiteksample, kui kasutajanimi on john ja parool on changeme, on tulemuseks autoriseerimispäis:
Volitus: põhiline am9objpjaGFuZ2VtZSA=
Tagavarana saab päringu parameetritena esitada kasutajanime ja parooli. Seda soovitatakse ainult klientidele, kes ei toeta põhiautentimist.
6. Taotluse esitamine
6.1 Päringu string
Taotluse parameetrid esitatakse päringustringina, mis sisaldab nime/väärtuse paare. Päringu string on kodeeritud kasutades protsenti kodeeringut (URL kodeering).
http://www.w3schools.com/tags/ref_urlencode.asp
Näiteksample, tere maailm! on kodeeritud kui Hello+World%21.
6.2 Päringu kohustuslikud parameetrid
| Nimi | Max pikkus | Kirjeldus |
| sihtkoha aadress | 40 | MSISDN, millele SMS-sõnum tuleb saata, alustades riigikoodist. Ntamptel: 46123456789. Mõne turu puhul (kus tarbija MSISDN tuleb hägustada) võib see väärtus olla ka tähtnumbriline pseudonüüm, mille ees on „#”. |
| sõnumTekst | 1600 | SMS-sõnumi sisu. |
6.3 Valikulised päringu parameetrid (täpsemaks kasutamiseks)
| Nimi | Max pikkus | Kirjeldus |
| lähteaadress | 16 | Väljuva SMS-sõnumi lähteaadress. Algaadressi tüüp määratakse parameetriga originatorTON. Lühinumbri maksimaalne pikkus on 16. Tähtnumbriline saatja on piiratud GSM-i vaiketähestikuga, mille maksimaalne pikkus on 11 tähemärki. MSISDN-i saatja maksimaalne pikkus on 15 (kasutades sama vormingut kui elemendi sihtkoha aadress). Saab ära jätta, kui süsteem valib aadressi originatingAddress ja originatingTON. See funktsioon sõltub turust ja konfiguratsioonist. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| algatajaTON | 1 | Algaadressi numbri tüüp (TON): 0 – Lühinumber 1 – tähtnumbriline (maksimaalne pikkus 11) 2 – MSISDN Saab ära jätta, kui originatingAddress ja originatingTON valib süsteem. See funktsioon sõltub turust ja konfiguratsioonist. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| userDataHeader | 280 | Kasutajaandmete päis koos kasutajaandmetega võib sisaldada kuni 140, st 280 kuueteistkümnendikku kodeeritud oktetti. See parameeter on alati hex-kodeeritud. |
| DCS | 3 | Andmete kodeerimise skeem. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| PID | 3 | Protokolli ID. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| suhtelineValidityTime | 6 | Suhteline kehtivusaeg sekundites (suhteliselt LINK Mobility'ile esitamise ajaga). Maksimaalne väärtus on 604800 (7 päeva) ja vaikeväärtus on 48 tundi. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| tarneaeg | 20 | Aegsaimamp millal SMS-sõnum tuleks kohale toimetada (edastusaeg hilineb). Vaadake jaotist kuupäeva ja kellaaja vormingu kohta. |
| staatusReportFlags | 1 | Esitage aruanne: 0 – tarnearuanne puudub (vaikimisi) 1 – nõutud tarnearuanne 9 – Nõutud serveri edastamise aruannet (LINK Mobility ei edasta aruannet teenusepakkujale, vaid teeb selle kättesaadavaks aruannetes jne) |
| campaignName | 50 | LINK Mobility tehingud on tagged selle nimega. Seda kasutatakse tehingute rühmitamiseks Link Mobility aruannetes. |
| maxConcatenatedMessages | 1 | Väärtus vahemikus 1 kuni 10, mis määrab, mitu ühendatud sõnumit on lubatud. Vaikimisi on 3. |
| korrelatsiooniId | 100 | Teenusepakkuja antud ID, mida kajastatakse tarneraportis. |
| kasutajanimi | 100 | Pakutakse alternatiivina HTTP põhiautentimisele. |
| parool | 100 | Pakutakse alternatiivina HTTP põhiautentimisele. |
6.4 HTTP päringu meetodid
Maksimaalse koostalitlusvõime tagamiseks toetab API nii HTTP GET-i kui ka POST-i päringu meetodeid. Muud HTTP-meetodid pole lubatud.
6.4.1 SAADA
Kodeeritud päringustring lisatakse URL.
SAADA
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Tere+Maailm%21
Volitus: põhiline am9objpjaGFuZ2VtZSA=
6.4.2 POSTITUS
Kodeeritud päringustring esitatakse HTTP päringu sõnumi kehasse. Sisu tüüp on rakendus/x-www-vorm-urlkodeeritud.
POSTITA https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Sisu tüüp: application / x-www-form-urlkodeeritud
Volitus: põhiline am9objpjaGFuZ2VtZSA=
Sisu pikkus: 57
destinationAddress=46123456789&messageText=Tere+maailm%21
6.5 Kuupäev ja kellaaeg
Kuupäeva ja kellaaega tähistavad parameetrid REST API-s on alati UTC ajavööndis (koordineeritud universaalaeg). Timestamps on esitatud stringina täpselt järgmises vormingus:
2017-04-25T23:20:50Z
See tähistab 20 minutit ja 50 sekundit pärast 23. aprillil 25 UTC 2017. tundi.
7. Vastusteade
Pärast päringusõnumi vastuvõtmist ja tõlgendamist vastab API HTTP-vastussõnumiga.
7.1 HTTP olekukood
REST API tagastab töödeldud päringute puhul alati HTTP olekukoodi 200 OK. Sõnumi sisu sisaldab parameetrit responseCode, mida kasutatakse täpse tulemuse määramiseks.
7.2 Sõnumi sisu
Sõnumi sisu koosneb JSON-ist, mis kirjeldab päringu tulemust.
http://json.org/
Link Mobility JSON järgib Google'i JSON-stiilijuhendit.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Vastuse parameetrid
| Nimi | Max pikkus | Kirjeldus |
| vastusekood | 3 | 0 näitab edukat tehingut. |
| vastussõnum | 255 | Vastuse tekstiline kirjeldus, nt veatekst. |
| kordaamp | 20 | Kuupäev ja kellaaeg, millal LINK Mobility taotlust töötles. (Vaadake kuupäeva/kellaaja vormingu jaotist). |
| traceId | 36 | Link Mobility sisemine identifikaator. Kasutatakse toe ja tõrkeotsingu jaoks. |
| sõnumi ID-d | 10 x 36 | LINK Mobility unikaalsete sõnumi ID-de massiiv iga eduka kirja jaoks (kui sõnum on ühendatud, tagastatakse mitu sõnumi ID-d). Ebaõnnestumise korral jäetakse välja. |
7.4 Ntample vastuseid
Edu
HTTP/1.1 200 OK
Sisutüüp: rakendus/json
Sisu pikkus: 144
Kuupäev: neljapäev, 15. september 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Siin on loetavuse huvides vormindatud sama JSON:
{
„vastusekood":0,
„vastussõnum":"Edu",
„kordaamp“:”2016-0915T13:20:31Z”,
„traceId“:”f678d30879fd4adc25f2”,
„sõnumi ID-d":["1-4850879008"] }
Ebaõnnestumine
HTTP/1.1 200 OK
Sisutüüp: rakendus/json
Sisu pikkus: 148
Kuupäev: neljapäev, 15. september 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" Kehtetu sisselogimine või volitamata API kasutus","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Edu
HTTP/1.1 200 OK
Sisutüüp: rakendus/json
Sisu pikkus: 144
Kuupäev: neljapäev, 15. september 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Siin on loetavuse huvides vormindatud sama JSON:
{
„vastusekood":0,
„vastussõnum":"Edu",
„kordaamp“:”2016-0915T13:20:31Z”,
„traceId“:”f678d30879fd4adc25f2”,
„sõnumi ID-d":["1-4850879008"] }
Ebaõnnestumine
HTTP/1.1 200 OK
Sisutüüp: rakendus/json
Sisu pikkus: 148
Kuupäev: neljapäev, 15. september 2016 13:20:31 GMT
{"responseCode":1,"responseMessage":" Kehtetu sisselogimine või volitamata API kasutus","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Vastuse koodid
Saadavas vastuses saab tagastada järgmised vastusekoodid:
| Kood | Tekst | Kirjeldus |
| 0 | Edu | Edukalt teostatud. |
| 1 | Kehtetu sisselogimine või volitamata API kasutus | Vale kasutajanimi või parool või teenusepakkuja on LINK Mobility poolt keelatud. |
| 2 | Link Mobility blokeerib tarbija | LINK Mobility blokeerib tarbija. |
| 3 | Toimingut ei paku LINK Mobility | Toiming on teenusepakkuja jaoks blokeeritud. |
| 4 | Tarbija on LINK Mobility jaoks tundmatu | Tarbija pole LINK Mobility'ile teada. Või kui päringus kasutati varjunime; aliast ei leitud. |
| 5 | Tarbija on selle teenuse teenuses LINK Mobility blokeerinud | Tarbija on selle teenuse teenuses LINK Mobility blokeerinud. |
| 6 | Algaadressi ei toetata | Algaadressi ei toetata. |
| 7 | Alfa-aadressi konto ei toeta | Konto ei toeta alfa-aadressi. |
| 8 | MSISDN-i lähteaadressi ei toetata | MSISDN-i lähteaadressi ei toetata. |
| 9 | Laiendatud GSM-i ei toetata | Laiendatud GSM-i ei toetata. |
| 10 | Unicode'i ei toetata | Unicode'i ei toetata. |
| 11 | Olekuaruannet ei toetata | Olekuaruannet ei toetata. |
| 12 | Nõutavat võimalust ei toetata | Sõnumi saatmiseks vajalikku võimalust (muud kui ülalnimetatud) ei toetata. |
| 13 | Sisupakkuja maksimaalne piiramissagedus on ületatud | Teenusepakkuja saadab SMS-i lingile LINK Mobility liiga kiiresti. |
| 14 | Konto ei toeta protokolli ID-d | Protokolli ID-d ei toetata. |
| 15 | Sõnumite ühendamise limiit on ületatud | Ühendatud sõnumite arv ületab maksimaalse nõutud arvu. |
| 16 | Sõnumit ei saa suunata. | LINK Mobility ei saanud sõnumit suunata. |
| 17 | Keelatud ajavahemik | Aja jooksul pole lubatud sõnumit saata |
| 18 | Liiga madal saldo teenusepakkuja kontol | Teenusepakkuja on liiga madala saldo tõttu blokeeritud |
| 50 | Osaline edu | Osaline edu SMS-i saatmisel mitmele adressaadile. |
| 99 | Siseserveri viga | Muu lingi mobiilsuse viga, lisateabe saamiseks võtke ühendust LINK Mobility toega. |
| 100 | Vale sihtkoha aadress | Sihtkoha aadress (MSISDN või pseudonüüm) on kehtetu. |
| 102 | Vigane viidatud (lingitud) ID | Viite ID on kehtetu, võib-olla on viite ID juba kasutatud, liiga vana või teadmata. |
| 103 | Kehtetu konto nimi | Konto nimi on kehtetu. |
| 105 | Kehtetud teenuse metaandmed | Teenuse metaandmed on kehtetud. |
| 106 | Vale lähteaadress | Algne aadress on kehtetu. |
| 107 | Vale tähtnumbriline lähteaadress | Tähtnumbriline lähteaadress on kehtetu. |
| 108 | Kehtetu kehtivusaeg | Kehtivusaeg on kehtetu. |
| 109 | Kehtetu tarneaeg | Tarneaeg on kehtetu. |
| 110 | Sõnumi sisu/kasutaja andmed on kehtetud | Kasutaja andmed ehk SMS sõnum on kehtetud. |
| 111 | Vale sõnumi pikkus | SMS-sõnumi pikkus on vale. |
| 112 | Kehtetu kasutajaandmete päis | Kasutajaandmete päis on kehtetu. |
| 113 | Kehtetu andmete kodeerimisskeem | DCS on kehtetu. |
| 114 | Vigane protokolli ID | PID on kehtetu. |
| 115 | Kehtetud olekuaruande lipud | Olekuaruande lipud on kehtetud. |
| 116 | Kehtetu TON | Algne TON on kehtetu. |
| 117 | Kehtetu campaign nimi | CampAign nimi on kehtetu. |
| 120 | Seotud sõnumite maksimaalse arvu piirang on kehtetu | Ühendatud sõnumite maksimaalne arv on kehtetu. |
| 121 | Vale msisdn-i lähteaadress | MSISDN-i lähteaadress on kehtetu. |
| 122 | Kehtetu korrelatsiooni ID | Korrelatsiooni ID on kehtetu. |
8. Valikulised funktsioonid
8.1 MSISDN-i parandus
MSISDN-i parandus on valikuline funktsioon, mille saab soovi korral lubada LINK Mobility toega.
See funktsioon parandab sihtkoha aadressid ja joondab need nõutavale E.164 vormingule. Lisaks vormingu korrigeerimisele võib süsteem teostada ka turuspetsiifilisi funktsioone, näiteks tõlkida rahvusvahelised prantsuse numbrid DOM-TOM (départements et territoires d'outre-mer) numbrite parandamiseks, kui see on asjakohane.
Allpool on toodud hulk endisiampvähem parandusi:
| Edastatud sihtkoha aadress | Sihtkoha aadress on parandatud |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Prantsuse number tõlgitud DOM-TOM numbriks) |
Lisaks on võimalik teatud turul lubada riiklikke telefoninumbreid. Kui see funktsioon on lubatud, tuleb teiste turgude rahvusvahelised numbrid saata koos esialgse märgiga "+", et eristada neid valitud turust.
Allpool on mitu endistampRootsi (riigikood 46) kasutamisel riiklike numbrite vaiketuruna tehtud parandused.
| Edastatud sihtkoha aadress | Sihtkoha aadress on parandatud |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Kehtetu, kuna märk „+” puudub |
Pange tähele, et parandatud MSISDN-i kasutab LINK Mobility ja see tagastatakse tarnearuannetes.
Lisateabe saamiseks võtke ühendust LINK Mobility toega.
8.2 Tähemärgi asendamine
Tähemärgi asendamine on valikuline funktsioon, mille saab soovi korral lubada LINK Mobility toega.
See funktsioon tõlgib kasutajaandmetes (SMS-i tekstis) olevad mitte-GSM-tähemärgid samaväärseteks GSM-tähemärkideks, kui DCS on seatud olekusse “GSM” (17). Näiteksample "Seqüência de teste em Português" tõlgitakse "Seqüencia de teste em Portugues".
9. Tarnearuanded
Teenusepakkujal on võimalik tellida saadetud MT-sõnumite kohta SMS-sõnumite edastamise aruandeid või kättetoimetamise teateid. Need aruanded käivituvad operaatori SMSC-s, kui MT-sõnum kas sihttarbijale toimetatakse või kustutatakse, nt aegunud või mingil põhjusel ei ole marsruutitav.
Teenusepakkujale teatatakse ainult SMS-sõnumi lõplik olek ehk edastatud või kustutatud. MT-teate kohta genereeritakse ainult üks aruanne. Kustutatud oleku korral võib kehtida põhjuskood. See põhjuskood määrab SMS-sõnumi kohaletoimetamata jätmise põhjuse.
Aruanded suunatakse LINK Mobility kaudu ja saadetakse HTTP-protokolli kasutades teenusepakkujale.
Aruannete saamiseks peab teenusepakkuja rakendama ntample Java Servlet või ASP.NET leht. Mõlemad saavad HTTP GET- või POST-päringuid.
Parameetrid
Taotlus sisaldab järgmisi parameetreid:
| Parameeter | Tüüp | M/O/I* | Vaikeväärtus | Max pikkus | Kirjeldus |
| Sõnumi ID | string | M | – | 22 | Selle MT-teate sõnumi ID, millele see aruanne vastab. |
| Sihtkoha aadress | string | M | – | 40 | Tarbija MSISDN ehk algse MT-teate sihtkoha aadress. |
| Olekukood | täisarv | M | 1 | Olekukood näitab MT-teate olekut. Kohaldatavad olekukoodid on: 0 – tarnitud 2 – kustutatud (kehtib põhjuse kood) |
|
| TimeStamp | string | M | – | 20 | Aeg, mis näitab, millal LINK Mobility tarneraporti kätte sai. Ajavööndamp on CET või CEST (Euroopa Liidus määratletud suveajaga). Vorming: yyyyKKdd HH:mm:ss. |
| Operaator | string | M | – | 100 | SMS-sõnumi saatmisel kasutatud operaatori nimi või SMS-sõnumi saatmisel kasutatud konto nimi. Saadaolevate operaatorite loendi pakub LINK Mobility tugi. |
| Põhjuskood | täisarv | O | – | 3 | Põhjuskood näitab, miks sõnum jõudis olekusse kustutatud. Kohaldatavad põhjuskoodid on järgmised: 100 – aegunud 101 – tagasi lükatud 102 – vormingu viga 103 – muu viga 110 – Tellija teadmata 111 – Abonent on keelatud 112 – Abonent pole ette nähtud 113 – tellija pole saadaval 120 – SMSC rike 121 – SMSC ummikud 122 – SMSC rändlus 130 – telefonitoru viga 131 – Telefoni mälu on ületatud Käitumine võib olenevalt operaatori integratsioonist erineda. |
| OperaatorTimeStamp | string | O | – | 20 | Kellaaeg, mis näitab, millal aruanne käivitus operaatori SMSC-s (kui operaator seda pakub). Ajavööndamp on CET või CEST (Euroopa Liidus määratletud suveajaga). Vorming: yyyyKKdd HH:mm:ss. |
| Olekutekst | string | O | – | 255 | Kohatäide operaatorilt saadava lisateabe jaoks, nt oleku/põhjuse selge tekstikirjeldus. Käitumine võib olenevalt operaatori integratsioonist erineda. |
| CorrelationId | string | O | – | 100 | SendRequestis või SendTextRequestis esitatud korrelatsiooni ID. |
| OperaatorNetworkCode | täisarv | O | – | 6 | Operaatori mobiilsidevõrgu kood (MCC + MNC). |
* M = kohustuslik, O = valikuline, I = ignoreeritud.
Teenusepakkuja peab andma LINK Mobility'i koos sihtmärgiga URL tarnearuannete jaoks (valikuliselt kaasa arvatud mandaadid HTTP-põhiautentimiseks). Teenusepakkuja saab valida, millist eelistatud HTTP-meetodit kasutada:
HTTP POST (soovitatav)
HTTP GET.
Example kasutades HTTP GET-i (edukalt tarnitud):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example kasutades HTTP GET-i (ei tarnitud, operaator on edastanud timestamp ürituse jaoks):
Parameetrid on URL kodeeritud.
Tähemärgi kodeering:
Teenusepakkuja saab valida, millist eelistatud märgikodeeringut kasutada:
UTF-8 (soovitatav)
ISO-8859-1.
9.1 Teenusepakkuja kinnitus
Teenusepakkuja peaks iga tarnearuannet kinnitama. Kinnitus võib olla positiivne, st tarnearuanne edukalt vastu võetud, või negatiivne, st ebaõnnestumine.
Pange tähele: LINK Mobilityl on tarnearuannete kinnituste lugemise ajalõpp 30 sekundit. Aegumine käivitab kohaletoimetamise uuesti katse (kui uuesti proovimine on lubatud) või kohaletoimetamise tühistamise (kui korduskatse on keelatud). See tähendab, et teenusepakkuja rakendus peab tagama kiired reageerimisajad, eriti suure koormuse korral.
Enne LINK Mobility'i tarnearuannet on tungivalt soovitatav kinnitada enne selle töötlemist.
Positiivse ja negatiivse kinnituse reeglit kirjeldatakse järgmiselt:
Positiivne kinnitus, ACK, kohaletoimetamise aruanne:
HTTP 200 vahemiku vastusekood koos järgmise XML-vormingus sisuga:
Negatiivne kinnitus, NAK, tarnearuannet ei edastatud:
Kõik vastused peale positiivse kinnituse, ntample, käivitab negatiivse kinnituse mis tahes HTTP-tõrkekood või järgmine XML-sisu:
XML-i sisu saab kasutada LINK Mobility uuesti proovimise mehhanismi juhtimiseks. NAK põhjustab korduskatse, kui see on lubatud. Teenusepakkujate jaoks, kes pole uuesti proovimise mehhanismi jaoks konfigureeritud, on XML-i sisu valikuline.
Allpool on HTTP POST-i päring ja vastus, ntampTeenusepakkujale edastatud tarneraportist:
HTTP taotlus:
POSTITA /kontekst/rakendus HTTP/1.1
Sisu tüüp: application / x-www-form-urlkodeeritud;charset=utf-8
Host: server:port
Sisu pikkus: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP vastus:
HTTP/1.1 200 OK
Sisutüüp: tekst/lihtne
9.2 Proovige uuesti
LINK Mobility süsteem võib sooritada korduskatseid ebaõnnestunud, st kinnitamata tarnearuannete edastamise korral. Teenusepakkuja saab valida eelistatud uuesti proovimise käitumise:
Ei proovi uuesti (vaikimisi) – teade tühistatakse, kui ühenduskatse ebaõnnestub, lugemise ajalõpp või HTTP veakood.
Proovi uuesti – teade saadetakse uuesti igat tüüpi ühendusprobleemide, lugemise ajalõpu või negatiivse kinnituse korral.
Kui NAK-i uuesti proovimine on lubatud, on oluline mõista, millised stsenaariumid loovad LINK Mobility'i korduskatse ja kuidas korduskatse töötab. Igal Teenusepakkujal on oma korduskatsejärjekord, kus sõnumid järjestatakse vastavalt sõnumite ajavahemikuleamp. Link Mobility püüab alati esmalt kohale toimetada vanemad sõnumid, kuigi teenusepakkujale saadetavate sõnumite individuaalne järjekord ei ole garanteeritud. Peamine põhjus, miks sõnumid korduskatsejärjekorrast kõrvale jäetakse, on üks kahest põhjusest: kas sõnumi TTL aegub või (teoreetiliselt) saab uuesti proovimise järjekord täis. TTL sõltub operaatorist ja kontost, st võib varieeruda olenevalt operaatorist ja/või sõnumi tüübist, nt tasuline SMS või standardtariifne SMS.
Teenusepakkujad, kellel on lubatud uuesti proovimine, peavad kontrollima MT-sõnumi kordumatut ID-d, et veenduda, et sõnum pole juba vastu võetud.
Teenusepakkujal on oluline järgida neid lihtsaid reegleid, kui tarneraporti töötlemisel ilmneb tõrge, kui vea põhjus on: Ajutine, nt andmebaas pole saadaval, tuleb tagastada NAK. LINK Mobility saadab sõnumi uuesti.
Püsiv ja korduskatse põhjustavad tõenäoliselt sama tüüpi probleemi, tuleks tagastada ACK. Näiteksample, kui teadet ei õnnestunud õigesti sõeluda või see põhjustas ootamatu käitusaja tõrke.
Vastavalt sellele toimides tagatakse, et tarneraporti korduv saatmine ei põhjusta blokeerimist ega läbilaskevõime halvenemist.
10. Rakendamise näpunäited
1. Võimalik on kasutada oma web brauser API-le taotluste esitamiseks. See muudab teenuste uurimise ja hindamise ilma arendustööriistadeta väga lihtsaks.
2. Soovitatav on Chrome või Firefox koos laiendusega, näiteks JSONView ilusti vormindatud JSON-i kuvamiseks.
3. Oleme kasutanud SoapUI-d POST-i, põhiautentimise testimiseks ning töötlemata HTTP päringu- ja vastusesõnumite kontrollimiseks.
4. CURL tööriist on kasulik põhiautentimisega POST-päringute esitamiseks. Vaata ntample allpool.
curl POSTITA \
-H „Sisutüüp: rakendus/x-www-vorm-urlkodeeritud" \
-H “Autoriseerimine: põhiline am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–andmed “destinationAddress=46123456789&messageText=Tere+maailm%21”
_______________
Isikupärastatud suhtluse muutmine
Dokumendid / Ressursid
 |
LINK Mobility Implementation Guide REST API SMS [pdfKasutusjuhend Mobility Implementation Guide REST API SMS, Mobility, juurutusjuhend REST API SMS, REST API SMS, API SMS, SMS |
