LINK Mobility Implementation Guide REST API SMS
LINK Mobility veitir þjónustu fyrir skilaboðasendingar, örgreiðslur og staðsetningartengda þjónustu. Vettvangurinn virkar sem gagnsær, hvítmerkt efnisöflun og viðskiptabein milli þjónustuveitenda og rekstraraðila.
LINK Mobility veitir RESTful API sem hægt er að nota til að fá aðgang að LINK Mobility þjónustu eins og að senda SMS. Þetta API er hannað til að vera auðvelt í notkun og samhæft við öll nútíma tungumál og ramma. Með því að nota tungumálið að eigin vali getur forritið þitt notað Link Mobility REST API til að innleiða öfluga skilaboða- og greiðslumöguleika
© LINK Mobility, 10. mars 2021
Lagalegar upplýsingar
Upplýsingarnar sem gefnar eru upp í þessu skjali eru eingöngu eign og höfundarréttur Netsize. Það er trúnaðarmál og ætlað til eingöngu upplýsinganotkunar. Það er ekki bindandi og gæti tekið breytingum án fyrirvara. Öll óheimil birting eða notkun skal teljast ólögmæt.
Netsize™ og linkmobility™ eru vernduð af frönskum, EBE og alþjóðlegum hugverkalögum.
Öll önnur vörumerki sem vitnað er í eru eingöngu eign viðkomandi eigenda.
Ekkert sem hér er að finna skal túlka sem leyfi eða rétt samkvæmt Netsize einkaleyfi, höfundarrétti eða vörumerki.
NETSTÆRÐ
Société anonyme au capital de 5 478 070 evrur
Siège social :62, Avenue Emile Zola92100 Boulogne – Frakkland
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Gildissvið skjalsins
Þetta skjal lýsir því hvernig þjónustuveitan notar LINK Mobility REST API fyrir SMS. Það er ætlað tækniarkitektum og hönnuðum sem innleiða þjónustu þjónustuveitanda.
1. Grunnnotkun
Það er mjög auðvelt að senda SMS. Þú sendir HTTP beiðni til LINK Mobility sem hægt er að ná með því að nota bara a web vafra.
2. Hagnýtur Yfirview
LINK Mobility kerfið býður upp á eftirfarandi grunnvirkni fyrir SMS skilaboð:
Sending farsímaskilaboða (MT) SMS-skilaboð, svo sem texta- eða tvöfaldur (td WAP Push) aukagjaldsskilaboð og venjulegt gjald.
Móttaka afhendingarskýrslna fyrir send MT skilaboð.
Móttaka farsímauppruna (MO) SMS-skilaboða, aukagjald og venjulegt gjald.
SMS REST API er tileinkað því að senda MT SMS skilaboð með venjulegu gengi.
Forritaskilin senda öll SMS skilaboð ósamstillt, sem gerir eiginleika eins og:
„Eld-og-gleymdu“ – Þjónustuaðilinn vill hafa fyrirsjáanlegri viðbragðstíma og vill ekki bíða eftir niðurstöðu frá rekstraraðilanum.
Reyndu aftur virkni – LINK Mobility mun senda skilaboðin aftur ef rekstraraðili lendir í tímabundnum vandamálum.
2.1 Sending SMS skilaboða
Þjónustuaðili Netsize Consumer
- Sendu MT skilaboð
- Skila auðkenni skilaboða
- Sendu SMS skilaboð
- Skila afhendingarskýrslu
- Senda afhendingarskýrslu
Grunnflæðinu til að senda SMS skilaboð er lýst sem hér segir:
Þjónustuaðili leggur fram beiðni um að senda SMS skilaboð til viðtakanda í gegnum LINK Mobility kerfið.
Skilaboðaauðkenni er skilað til þjónustuveitunnar. Þetta auðkenni er td hægt að nota til að tengja skilaboðin við rétta afhendingarskýrslu.
LINK Mobility sér um leið og kemur SMS skilaboðunum til neytenda sem beint er til.
Sendingarskýrsla kemur af stað, td þegar SMS-skilaboðin eru send í tæki neytenda.
Afhendingarskýrsla er send til þjónustuaðila. Skýrslan inniheldur sama auðkenni skilaboða og skilað var í skrefi 2.
Valflæði: Ógild beiðni
Ef tilgreindar færibreytur eða notendaskilríki í beiðninni eru ógild er villa skilað til þjónustuveitunnar. Villan gefur til kynna ástæðu höfnunarinnar og flæðið lýkur. Engum skilaboðaauðkennum er skilað.
3. Endapunktur
Hægt er að nálgast SMS tilfangið með því að nota slóðina:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Fyrir öryggi tenginga er LINK Mobility REST API aðeins aðgengilegt yfir HTTPS.
Link Mobility miðlaravottorðið er undirritað af Thawte Server CA.
4. Rekstur
SMS-þjónustan býður upp á eftirfarandi aðgerðir:
| Nafn | Slóð |
| Senda | /restapi/v1/sms/senda |
4.1 Senda
Sendingaraðgerðin er notuð til að senda SMS til eins viðtakanda.
Þessi aðgerð er ætluð bæði grunnnotendum og háþróuðum notendum. Í einfaldasta tilvikinu þarf aðeins heimilisfang áfangastaðar og skilaboðatexta til að senda SMS. LINK Mobility mun greina gagnakóðakerfið og framkvæma sjálfvirka samtengingu skilaboða í marga skeytahluta ef þörf krefur.
Fyrir háþróaða notkun getur þjónustuveitan notað valfrjálsar færibreytur til að hafa fulla stjórn á sniði skilaboða, þar með talið haus notendagagna.
Þjónustuveitan getur sent samræmd skilaboð, en undirbúningur notendagagna og notendagagnahaus verður að fara fram af þjónustuveitunni og skilaboðin verða send með mörgum sendingarbeiðnum til LINK Mobility.
5. Auðkenning
Notandanafn og lykilorð eru send inn í hverri beiðni með því að nota HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Skilríki eru send í heimildarhaus í HTTP beiðninni. Viðskiptavinurinn smíðar hausreitinn eins og lýst er hér:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Til dæmisample, ef notandanafnið er john og changeme er lykilorðið þá er heimildarhausinn sem myndast:
Heimild: Basic am9objpjaGFuZ2VtZSA=
Til baka er hægt að senda inn notandanafn og lykilorð sem beiðnifæribreytur. Þetta er aðeins mælt fyrir viðskiptavini sem styðja ekki Basic Auth.
6. Skila inn beiðni
6.1 Fyrirspurnarstrengur
Beiðnifæribreytur eru sendar inn sem fyrirspurnarstrengur sem inniheldur nafn/gildi pör. Fyrirspurnarstrengurinn er kóðaður með því að nota prósentukóðun (URL kóðun).
http://www.w3schools.com/tags/ref_urlencode.asp
Til dæmisample, Halló heimur! er umritað sem Hello+World%21.
6.2 Lögboðnar færibreytur beiðni
| Nafn | Hámarks lengd | Lýsing |
| áfangastað | 40 | MSISDN-númerið sem SMS-skilaboðin á að senda á, byrja á landsnúmeri. Tdampl: 46123456789. Fyrir suma markaði (þar sem neytenda-MSISDN verður að vera óskýrt) getur þetta gildi einnig verið alfanumerískt samnefni, með forskeytinu „#“. |
| skilaboðTexti | 1600 | Innihald SMS skilaboðanna. |
6.3 Valfrjálsar beiðnifæribreytur (fyrir háþróaða notkun)
| Nafn | Hámarks lengd | Lýsing |
| upprunaheimilisfang | 16 | Upprunavistfang sendandi SMS skilaboða. Tegund upphafs heimilisfangs er skilgreint af frumbreytunni originatorTON. Stutt tala hámarkslengd er 16. Alfatölulegur sendandi takmarkast við GSM sjálfgefið stafróf með hámarkslengd 11 stafir. Hámarkslengd MSISDN sendanda er 15 (með sama sniði og destinationAddress frumefnið). Hægt að sleppa þegar originatingAddress og originatingTON eru valin af kerfinu. Þessi aðgerð er markaðs- og stillingarháð. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| upphafsmaðurTON | 1 | Númer upprunalegs heimilisfangs (TON): 0 – Stutt númer 1 – Alfatöluleg (hámarkslengd 11) 2 – MSISDN Hægt að sleppa þegar originatingAddress og originatingTON verða valin af kerfinu. Þessi aðgerð er markaðs- og stillingarháð. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| userDataHeader | 280 | User Data Header ásamt notandagögnum geta innihaldið allt að 140, þ.e. 280 þegar sexkóðaða, oktettar. Þessi færibreyta er alltaf sexkantskóðuð. |
| DCS | 3 | Gagnakóðun kerfi. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| PID | 3 | Auðkenni bókunar. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| relative ValidityTime | 6 | Hlutfallslegur gildistími í sekúndum (miðað við tíma fyrir uppgjöf til LINK Mobility). Hámarksgildi er 604800 (7 dagar) og sjálfgefið er 48 klst. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| afhendingartími | 20 | Tímabærtamp hvenær SMS skilaboð eiga að berast (seinkaður afhendingartími). Sjá kafla um snið dagsetningartíma. |
| statusReportFlags | 1 | Skila skýrslubeiðni: 0 – Engin sendingarskýrsla (sjálfgefið) 1 – Afhendingarskýrsla óskað 9 – Beðið um afhendingarskýrslu miðlara (LINK Mobility sendir skýrsluna ekki áfram til þjónustuveitunnar heldur gerir hana aðgengilega í skýrslum o.s.frv.) |
| campaignName | 50 | LINK Mobility viðskiptin eru tagged með þessu nafni. Það er notað til að flokka viðskipti í Link Mobility skýrslur. |
| maxConcatenatedMessages | 1 | Gildi á milli 1 og 10 sem skilgreinir hversu mörg samtengd skilaboð eru leyfð. Sjálfgefið er 3. |
| correlationId | 100 | Auðkenni veitt af þjónustuveitanda sem verður endurómað í afhendingarskýrslu. |
| notendanafn | 100 | Veitt sem valkostur við HTTP Basic Authentication. |
| lykilorð | 100 | Veitt sem valkostur við HTTP Basic Authentication. |
6.4 Aðferðir við HTTP beiðni
Fyrir hámarks samvirkni styður API bæði HTTP GET og POST beiðniaðferðir. Engar aðrar HTTP aðferðir eru leyfðar.
6.4.1 FÁ
Kóðaði fyrirspurnarstrengurinn er bætt við URL.
FÁ
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Halló+Heimur%21
Heimild: Basic am9objpjaGFuZ2VtZSA=
6.4.2 POST
Kóðaði fyrirspurnarstrengurinn er sendur í HTTP beiðni skilaboða meginmáli. Efnistegund er umsókn/x-www-form-urlkóðuð.
POST https://europe.ipx.com/restapi/v1/sms/send
Gestgjafi: europe.ipx.com
Efnisgerð: umsókn / x-www-form-urlkóðuð
Heimild: Basic am9objpjaGFuZ2VtZSA=
Innihaldslengd: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Dagsetning og tími
Færibreytur í REST API sem tákna dagsetningu og tíma eru alltaf á UTC tímabelti (Coordinated Universal Time). Timestamps eru táknuð sem strengur með þessu nákvæmlega sniði:
2017-04-25T23:20:50Z
Þetta táknar 20 mínútur og 50 sekúndur eftir 23. klukkustund 25. apríl 2017 í UTC.
7. Svarskilaboð
Eftir að hafa fengið og túlkað beiðniskilaboð svarar API með HTTP svarskilaboðum.
7.1 HTTP stöðukóði
REST API skilar alltaf HTTP stöðukóða 200 OK fyrir unnar beiðnir. Meginmál skilaboðanna inniheldur viðfangskóða sem er notaður til að ákvarða nákvæma niðurstöðu.
7.2 Meginmál skilaboða
Skilaboðin samanstanda af JSON sem lýsir niðurstöðu beiðninnar.
http://json.org/
Link Mobility JSON er í samræmi við Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Viðbragðsbreytur
| Nafn | Hámarks lengd | Lýsing |
| svarkóði | 3 | 0 gefur til kynna vel heppnuð viðskipti. |
| svarSkilaboð | 255 | Textalýsing svars, td villutexti. |
| tíminnamp | 20 | Dagsetning og tími þegar LINK Mobility afgreiddi beiðnina. (Sjáðu kaflann um snið dagsetningar/tíma). |
| traceId | 36 | Link Mobility innra auðkenni. Notað til stuðnings og bilanaleitar. |
| skilaboðaauðkenni | 10 x 36 | Fjöldi LINK Mobility einstakra skilaboðaauðkenna fyrir hvert vel heppnað skilaboð (mörg skilaboðaauðkenni er skilað ef skilaboðin eru samkeyrð). Sleppt ef bilun verður. |
7.4 Dæmiample svörin
Árangur
HTTP/1.1 200 Í lagi
Efnistegund: forrit/json
Innihaldslengd: 144
Dagsetning: Fim, 15. Sep. 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Árangur","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hér er sama JSON sniðið fyrir læsileika:
{
“svarkóði“:0,
“svarSkilaboð“:”Árangur”,
“tíminnamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“skilaboðaauðkenni“:[“1-4850879008”] }
Bilun
HTTP/1.1 200 Í lagi
Efnistegund: forrit/json
Innihaldslengd: 148
Dagsetning: Fim, 15. Sep. 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:“ Ógild innskráning eða óheimil API notkun“,“timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Árangur
HTTP/1.1 200 Í lagi
Efnistegund: forrit/json
Innihaldslengd: 144
Dagsetning: Fim, 15. Sep. 2016 13:20:31 GMT
{"responseCode":0,"responseMessage":"Árangur","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Hér er sama JSON sniðið fyrir læsileika:
{
“svarkóði“:0,
“svarSkilaboð“:”Árangur”,
“tíminnamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“skilaboðaauðkenni“:[“1-4850879008”] }
Bilun
HTTP/1.1 200 Í lagi
Efnistegund: forrit/json
Innihaldslengd: 148
Dagsetning: Fim, 15. Sep. 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:“ Ógild innskráning eða óheimil API notkun“,“timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Svarkóðar
Eftirfarandi svarkóða er hægt að skila í sendingarsvarinu:
| Kóði | Texti | Lýsing |
| 0 | Árangur | Tókst að framkvæma. |
| 1 | Ógild innskráning eða óheimil API notkun | Rangt notandanafn eða lykilorð eða þjónustuveitandi er útilokað af LINK Mobility. |
| 2 | Neytandi er lokað af Link Mobility | Neytandinn er lokaður af LINK Mobility. |
| 3 | Rekstur er ekki útvegaður af LINK Mobility | Aðgerðinni er lokað fyrir þjónustuveituna. |
| 4 | Neytandinn er óþekktur fyrir LINK Mobility | Neytandinn er óþekktur fyrir LINK Mobility. Eða ef samnefni var notað í beiðninni; samnefni fannst ekki. |
| 5 | Neytandi hefur lokað á þessa þjónustu í LINK Mobility | Neytandinn hefur lokað á þessa þjónustu í LINK Mobility. |
| 6 | Uppruna heimilisfangið er ekki stutt | Uppruna heimilisfangið er ekki stutt. |
| 7 | Uppruna heimilisfangið er ekki stutt af reikningi | Alfa upphafsvistfangið er ekki stutt af reikningnum. |
| 8 | Upprunavistfang MSISDN er ekki stutt | Upprunavistfang MSISDN er ekki stutt. |
| 9 | GSM framlengt ekki stutt | GSM framlengt ekki stutt. |
| 10 | Unicode ekki stutt | Unicode ekki stutt. |
| 11 | Stöðuskýrsla ekki studd | Stöðuskýrsla ekki studd. |
| 12 | Nauðsynleg geta ekki studd | Nauðsynleg möguleiki (annar en hér að ofan) til að senda skilaboðin er ekki studd. |
| 13 | Farið er yfir hámarkshraða efnisveitunnar | Þjónustuveitan sendir SMS skilaboðin til LINK Mobility of hratt. |
| 14 | Bókunarauðkenni er ekki stutt af reikningi | Bókunarauðkenni ekki stutt. |
| 15 | Farið yfir mörk samtengingar skilaboða | Fjöldi samtengdra skilaboða fer yfir hámarksfjölda sem óskað er eftir. |
| 16 | Ekki er hægt að beina skilaboðum. | LINK Mobility gat ekki beint skilaboðunum. |
| 17 | Bannað tímabil | Ekki er heimilt að senda skilaboð á tímabili |
| 18 | Of lág staða á reikningi þjónustuveitunnar | Þjónustuveitan er læst vegna of lágrar stöðu |
| 50 | Árangur að hluta | Að hluta til tókst þegar SMS-skilaboð eru send til margra viðtakenda. |
| 99 | Innri netþjónsvilla | Önnur Link Mobility villa, hafðu samband við LINK Mobility þjónustudeild fyrir frekari upplýsingar. |
| 100 | Ógilt heimilisfang áfangastaðar | Áfangastaðfangið (MSISDN, eða samnefni) er ógilt. |
| 102 | Ógilt tilvísað (tengd) auðkenni | Tilvísunarauðkennið er ógilt, kannski er tilvísunarauðkennið þegar notað, of gamalt eða óþekkt. |
| 103 | Ógilt reikningsheiti | Reikningsnafnið er ógilt. |
| 105 | Ógild lýsigögn þjónustu | Lýsigögn þjónustunnar eru ógild. |
| 106 | Ógilt uppruna heimilisfang | Heimilisfangið er ógilt. |
| 107 | Ógilt alfanumerískt upphafsfang | Alfanumerískt upphafsfang er ógilt. |
| 108 | Ógildur gildistími | Gildistíminn er ógildur. |
| 109 | Ógildur afhendingartími | Afhendingartíminn er ógildur. |
| 110 | Ógild skilaboðaefni/notendagögn | Notendagögnin, þ.e. SMS-skilaboðin, eru ógild. |
| 111 | Ógild lengd skilaboða | Lengd SMS skilaboðanna er ógild. |
| 112 | Ógildur notendagagnahaus | Notandagagnahausinn er ógildur. |
| 113 | Ógilt gagnakóðunarkerfi | DCS er ógilt. |
| 114 | Ógilt samskiptaauðkenni | PID er ógilt. |
| 115 | Ógildir stöðuskýrslufánar | Fánar stöðuskýrslunnar eru ógildar. |
| 116 | Ógilt TON | Upphafsmaðurinn TON er ógildur. |
| 117 | Ógildur campnafni nafn | The campnafn nafns er ógilt. |
| 120 | Ógild takmörk fyrir hámarksfjölda samtengdra skilaboða | Hámarksfjöldi samræmdra skilaboða er ógildur. |
| 121 | Ógilt msisdn uppruna heimilisfang | Upprunavistfang MSISDN er ógilt. |
| 122 | Ógilt fylgniauðkenni | Fylgniauðkenni er ógilt. |
8. Valfrjálsir eiginleikar
8.1 MSISDN leiðrétting
MSISDN leiðrétting er valfrjáls eiginleiki sem hægt er að virkja með LINK Mobility stuðningi ef þess er óskað.
Þessi eiginleiki mun leiðrétta áfangastaðsföng og samræma þau við tilskilið E.164 snið. Til viðbótar við sniðleiðréttingu getur kerfið einnig framkvæmt markaðssértæka virkni eins og að þýða alþjóðleg frönsk númer til að leiðrétta DOM-TOM (départements et territoires d'outre-mer) númer þegar við á.
Hér að neðan eru nokkur tdamples af leiðréttingum:
| Uppgefið heimilisfang áfangastaðar | Leiðrétt heimilisfang áfangastaðar |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Franskt númer þýtt yfir á DOM-TOM númer) |
Að auki er hægt að leyfa innlend símanúmer fyrir valinn markað. Þegar þessi eiginleiki er virkur verður að senda öll alþjóðleg númer fyrir aðra markaði með upphafsmerki „+“ til að greina þau frá völdum markaði.
Hér að neðan eru nokkur tdampLeiðréttingar sem gerðar eru þegar Svíþjóð (landsnúmer 46) er notað sem sjálfgefinn markaður fyrir landsnúmer.
| Uppgefið heimilisfang áfangastaðar | Leiðrétt heimilisfang áfangastaðar |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Ógilt þar sem '+' táknið vantar |
Athugaðu að leiðrétta MSISDN verður notað af LINK Mobility og því verður skilað í afhendingarskýrslum.
Vinsamlegast hafðu samband við LINK Mobility þjónustudeild til að fá frekari upplýsingar.
8.2 Persónuskipti
Stafaskipti er valfrjáls eiginleiki sem hægt er að virkja með LINK Mobility stuðningi ef þess er óskað.
Þessi eiginleiki mun þýða stafi sem ekki eru GSM stafróf í notendagögnum (SMS texti) yfir í samsvarandi GSM stafróf stafi þegar DCS er stillt á „GSM“ (17). Til dæmisample „Seqüência de teste em Português“ verður þýtt á „Sequüencia de teste em Portugues“.
9. Afhendingarskýrslur
Þjónustuveitan getur, ef útvegað er, beðið um sendingarskýrslur fyrir SMS skilaboð eða sendingartilkynningar fyrir MT skilaboðin sem send eru. Þessar skýrslur koma af stað í SMSC símafyrirtækinu þegar MT skilaboðin eru annaðhvort afhent til viðkomandi neytanda eða þeim eytt, td útrunnið eða, af einhverjum ástæðum, ekki hægt að beina þeim.
Aðeins endanleg staða SMS-skilaboða er tilkynnt til þjónustuveitanda, þ.e. afhent eða eytt. Aðeins ein skýrsla er búin til í hverju MT skilaboðum. Með eytt stöðu gæti ástæðukóði átt við. Þessi ástæðukóði tilgreinir ástæðu þess að SMS-skilaboðin eru ekki afhent.
Skýrslunum er vísað í gegnum LINK Mobility og sendar til þjónustuveitunnar með HTTP samskiptareglum.
Til að fá skýrslur þarf þjónustuaðilinn að innleiða tdampmeð Java Servlet eða ASP.NET síðu. Báðir fá HTTP GET eða POST beiðnir.
Færibreytur
Beiðnin inniheldur eftirfarandi færibreytur:
| Parameter | Tegund | M/O/I* | Sjálfgefið gildi | Hámarks lengd | Lýsing |
| MessageId | strengur | M | – | 22 | Skilaboðakenni MT skilaboðanna sem þessi skýrsla samsvarar. |
| DestinationAddress | strengur | M | – | 40 | MSISDN neytenda, þ.e. áfangastað upphaflegu MT skilaboðanna. |
| Stöðukóði | heiltala | M | 1 | Stöðukóði gefur til kynna stöðu MT skilaboðanna. Gildandi stöðukóðar eru: 0 - Afhent 2 – Eytt (ástæðukóði á við) |
|
| TimeStamp | strengur | M | – | 20 | Tími sem gefur til kynna hvenær afhendingarskýrslan barst LINK Mobility. Tímabelti tímamælaamp er CET eða CEST (með sumartíma eins og skilgreint er fyrir ESB). Snið: yyyyMMdd HH:mm:ss. |
| Rekstraraðili | strengur | M | – | 100 | Nafn símafyrirtækisins sem notað er þegar SMS-skilaboðin eru send eða reikningsnafnið sem notað er þegar SMS-skilaboðin eru send. Listi yfir tiltæka rekstraraðila er veittur af LINK Mobility stuðningi. |
| Ástæðukóði | heiltala | O | – | 3 | Ástæðukóði gefur til kynna hvers vegna skeytið endaði í stöðunni eytt. Gildandi ástæðukóðar eru: 100 - Útrunnið 101 – Hafnað 102 - Snið villa 103 – Önnur villa 110 – Áskrifandi óþekktur 111 - Áskrifandi útilokað 112 – Áskrifandi ekki útvegaður 113 - Áskrifandi ekki tiltækur 120 - SMSC bilun 121 - SMSC þrengsli 122 – SMSC reiki 130 - Símtól villa 131 – Farið yfir minni símtóls Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| RekstrartímiStamp | strengur | O | – | 20 | Tími sem gefur til kynna hvenær skýrslan var ræst í SMSC símafyrirtækisins (ef rekstraraðilinn gefur upp). Tímabelti tímamælaamp er CET eða CEST (með sumartíma eins og skilgreint er fyrir ESB). Snið: yyyyMMdd HH:mm:ss. |
| StatusTexti | strengur | O | – | 255 | Staðgengill fyrir frekari upplýsingar frá rekstraraðila, td skýra textalýsingu á stöðu/ástæðu. Hegðun getur verið breytileg eftir samþættingum rekstraraðila. |
| CorrelationId | strengur | O | – | 100 | Fylgniauðkennið sem gefið er upp í SendRequest eða SendTextRequest. |
| Netkerfiskóði rekstraraðila | heiltala | O | – | 6 | Farsímakerfiskóði (MCC + MNC) símafyrirtækisins. |
* M = Skylt, O = Valfrjálst, I = Hunsað.
Þjónustuveitan þarf að veita LINK Mobility markmiðið URL fyrir afhendingarskýrslur (mögulega innihalda skilríki fyrir HTTP grunn auðkenningu). Þjónustuveitan getur valið hvaða HTTP aðferð á að nota:
HTTP POST (mælt með)
HTTP FÁ.
Example með HTTP GET (afhent með góðum árangri):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example með því að nota HTTP GET (ekki afhent, rekstraraðilinn hefur gefið upp tímatöluramp fyrir viðburðinn):
Færibreyturnar eru URL encodedi.
Stafakóðun:
Þjónustuveitan getur valið hvaða stafakóðun á að nota:
UTF-8 (mælt með)
ISO-8859-1.
9.1 Staðfesting þjónustuaðila
Þjónustuaðilinn ætti að viðurkenna hverja afhendingarskýrslu. Staðfestingin getur verið jákvæð, þ.e. sendingarskýrsla hefur verið móttekin, eða neikvæð, þ.e. misheppnuð.
Vinsamlegast athugið: LINK Mobility hefur 30 sekúndna lestrartíma fyrir staðfestingar fyrir sendingarskýrslur. Tímamörk munu kalla á endurreynslu afhendingar (ef endurreynsla er virkjuð) eða hætt við afhendingu (ef endurreynsla er óvirk). Þetta þýðir að þjónustuveituforritið verður að tryggja skjótan viðbragðstíma, sérstaklega við mikið álag.
Það er mjög mælt með því að viðurkenna afhendingarskýrsluna til LINK Mobility áður en unnið er úr henni.
Reglunni um jákvæða og neikvæða viðurkenningu er lýst sem hér segir:
Jákvæð viðurkenning, ACK, sendingarskýrsla afhent:
HTTP 200 svið svarkóði ásamt eftirfarandi XML sniði efni:
Neikvæð staðfesting, NAK, afhendingarskýrsla ekki afhent:
Öll svör önnur en jákvæð viðurkenning, tdample, neikvæð viðurkenning er kveikt af hvaða HTTP villukóða sem er eða eftirfarandi XML innihald:
Hægt er að nota XML efnið til að stjórna LINK Mobility endurreynslubúnaðinum. NAK mun valda tilraun til að reyna aftur, ef það er virkt. Fyrir þjónustuveitendur sem ekki eru stilltir fyrir afturreynslukerfið er XML-efnið valfrjálst.
Hér að neðan er HTTP POST beiðni og svar tdampLeið af afhendingarskýrslu sem afhent er þjónustuveitanda:
HTTP beiðni:
POST /samhengi/app HTTP/1.1
Efnisgerð: umsókn / x-www-form-urlkóðuð;charset=utf-8
Gestgjafi: þjónn:höfn
Innihaldslengd: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP svar:
HTTP/1.1 200 Í lagi
Efnistegund: texti/látlaus
9.2 Reyndu aftur
LINK Mobility kerfið getur framkvæmt tilraunir aftur fyrir misheppnaðar, þ.e. ekki staðfestar, sendingarskýrslur. Þjónustuveitan getur valið þá hegðun sem æskilegt er að reyna aftur:
Engin tilraun aftur (sjálfgefið) – skilaboðunum verður hent ef tengingartilraun mistekst, lestrartími eða fyrir HTTP villukóða.
Reyndu aftur – skilaboðin verða send aftur fyrir allar tegundir tengingarvandamála, lestrartíma eða neikvæðrar staðfestingar.
Þegar endurreynsla fyrir NAK er virkjuð er mikilvægt að skilja hvaða atburðarás mun búa til endurreynslutilraun frá LINK Mobility og hvernig endurreynin virkar. Hver þjónustuaðili hefur sína eigin biðröð fyrir endurreynslu þar sem skilaboðum er raðað í samræmi við skilaboðatímaamp. Link Mobility reynir alltaf að koma eldri skilaboðum fyrst, jafnvel þó að einstök röð skilaboða sem send eru til þjónustuveitunnar sé ekki tryggð. Aðalástæðan fyrir því að skilaboðum er hent úr biðröðinni fyrir endurtekning er ein af tveimur ástæðum: annað hvort rennur skilaboðin TTL út eða (fræðilega séð) verður endurreynsluröðin full. TTL er háð rekstraraðila og reikningi, þ.e. getur verið breytilegt eftir símafyrirtæki og/eða tegund skilaboða, td hágæða SMS eða SMS skilaboð með venjulegu gjaldi.
Þjónustuveitur með endurreynslu virkt verða að athuga einkvæmt auðkenni MT skilaboðanna til að tryggja að skilaboðin hafi ekki þegar verið móttekin.
Mikilvægt er fyrir þjónustuaðila að fara að þessum einföldu reglum þegar villa kemur upp við vinnslu skilaskýrslu ef ástæða villunnar er: Tímabundin, td gagnagrunnur ekki tiltækur, skal skila NAK. LINK Mobility mun senda skilaboðin aftur.
Varanleg tilraun og tilraun aftur eru líkleg til að valda sams konar vandamálum, ACK ætti að skila. Til dæmisample, þegar ekki var hægt að þátta skilaboðin á réttan hátt eða olli óvæntri afturkreistingarvillu.
Að bregðast við í samræmi við það mun tryggja að engin stífla eða rýrnun á afköstum sé af völdum afhendingarskýrslu sem er endursend ítrekað.
10. Ábendingar um framkvæmd
1. Það er hægt að nota þitt web vafra til að senda beiðnir til API. Þetta gerir það mjög auðvelt að kanna og meta þjónustuna án nokkurra þróunartækja.
2. Mælt er með Chrome eða Firefox ásamt viðbótum eins og JSONView til að sýna fallegt sniðið JSON.
3. Við höfum notað SoapUI til að prófa POST, Basic Authentication og til að skoða hrá HTTP beiðni og svarskilaboð.
4. The cURL tól er gagnlegt til að senda inn POST beiðnir með grunnauðkenningu. Sjá tdample fyrir neðan.
curl POST \
-H “Content-Type: application/x-www-form-urlkóðuð“ \
-H “Heimild: Basic am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–gögn “destinationAddress=46123456789&messageText=Halló+Heimur%21”
_______________
Umbreyta persónulegum samskiptum
Skjöl / auðlindir
 |
LINK Mobility Implementation Guide REST API SMS [pdfNotendahandbók Mobility Implementation Guide REST API SMS, Mobility, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
