LINK Mobility Implementation Guide REST API SMS
LINK Mobility poskytuje službu na doručovanie správ, mikroplatby a služby založené na polohe. Platforma funguje ako transparentný príjemca obsahu a transakčný smerovač medzi poskytovateľmi služieb a operátormi.
LINK Mobility poskytuje RESTful API, ktoré možno použiť na prístup k službám LINK Mobility, ako je posielanie SMS. Toto API je navrhnuté tak, aby sa ľahko používalo a bolo kompatibilné so všetkými modernými jazykmi a rámcami. Pomocou vami zvoleného jazyka môže vaša aplikácia použiť rozhranie Link Mobility REST API na implementáciu výkonných možností odosielania správ a platieb
© LINK Mobility, 10. marca 2021
Právne informácie
Informácie uvedené v tomto dokumente sú výhradným vlastníctvom a autorským právom spoločnosti Netsize. Je dôverný a určený na čisto informačné použitie. Nie je záväzné a môže podliehať zmenám bez upozornenia. Akékoľvek neoprávnené zverejnenie alebo použitie sa bude považovať za nezákonné.
Netsize™ a linkmobility™ sú chránené francúzskymi, EHS a medzinárodnými zákonmi o duševnom vlastníctve.
Všetky ostatné citované ochranné známky sú výhradným vlastníctvom ich príslušných vlastníkov.
Nič z toho, čo je tu uvedené, nemožno vykladať tak, že udeľuje licenciu alebo právo v rámci patentu, autorských práv alebo ochrannej známky spoločnosti Netsize.
NETSIZE
Société anonyme au capital de 5 478 070 eur
Siège social :62, avenue Emile Zola92100 Boulogne – Francúzsko
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Rozsah dokumentu
Tento dokument popisuje, ako poskytovateľ služieb používa LINK Mobility REST API pre SMS. Je určený pre technických architektov a projektantov, ktorí realizujú služby Poskytovateľa služieb.
1. Základné použitie
Poslanie SMS je veľmi jednoduché. Do LINK Mobility odošlete požiadavku HTTP, ktorú je možné vykonať iba pomocou a web prehliadač.
2. Funkčný Overview
Systém LINK Mobility poskytuje nasledujúce základné funkcie pre SMS správy:
Odosielanie správ SMS s mobilným ukončením (MT), ako sú textové alebo binárne (napr. WAP Push) správy s prémiovou a štandardnou sadzbou.
Prijímanie správ o doručení zaslaných správ MT.
Prijímanie správ Mobile Originated (MO) SMS, prémiová a štandardná sadzba.
SMS REST API je určené na odosielanie SMS správ štandardnej sadzby MT.
Rozhranie API odosiela všetky SMS správy asynchrónne, čím umožňuje funkcie ako:
„Ohni a zabudni“ – Poskytovateľ služby chce mať predvídateľnejšie časy odozvy a nechce čakať na výsledok od Prevádzkovateľa.
Funkcia opätovného pokusu – LINK Mobility znova odošle správu, ak má operátor dočasné problémy.
2.1 Odoslanie SMS správy
Poskytovateľ služieb Netsize Consumer
- Odoslať správu MT
- Vrátiť ID správy
- Odoslať SMS správu
- Doručiť správu o doručení
- Odoslať správu o doručení
Základný postup odosielania SMS správ je opísaný takto:
Poskytovateľ služby požiada o zaslanie SMS správy príjemcovi prostredníctvom systému LINK Mobility.
ID správy sa vráti poskytovateľovi služby. Toto ID možno použiť napr. na koreláciu správy so správnym hlásením o doručení.
LINK Mobility spracováva smerovanie a doručuje SMS správu adresovanému spotrebiteľovi.
Hlásenie o doručení sa spustí napr. pri doručení SMS správy do zariadenia spotrebiteľa.
Správa o doručení sa odošle Poskytovateľovi služby. Správa obsahuje rovnaké ID správy, aké sa vrátilo v kroku 2.
Alternatívny postup: Neplatná požiadavka
Ak sú zadané parametre alebo používateľské poverenia v požiadavke neplatné, Poskytovateľovi služby sa vráti chyba. Chyba označuje dôvod odmietnutia a tok končí. Nevracajú sa žiadne ID správ.
3. Koncový bod
K prostriedku SMS sa pristupuje pomocou cesty:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Kvôli bezpečnosti pripojenia je LINK Mobility REST API prístupné iba cez HTTPS.
Certifikát servera Link Mobility je podpísaný Thawte Server CA.
4. Operácie
Služba SMS poskytuje nasledujúce operácie:
| Meno | Cesta |
| Odoslať | /restapi/v1/sms/odoslať |
4.1 Odoslať
Operácia odoslania sa používa na odoslanie SMS jednému príjemcovi.
Táto operácia je určená pre základných aj pokročilých používateľov. V najjednoduchšom prípade je na doručenie SMS potrebná iba cieľová adresa a text správy. LINK Mobility zistí schému kódovania údajov a v prípade potreby vykoná automatické zreťazenie správy do viacerých častí správy.
Pre pokročilé použitie môže poskytovateľ služby použiť voliteľné parametre na úplnú kontrolu nad formátovaním správy vrátane hlavičky používateľských údajov.
Poskytovateľ služby môže posielať zreťazené správy, ale príprava používateľských údajov a hlavičky používateľských údajov musí byť vykonaná poskytovateľom služby a správa musí byť odoslaná prostredníctvom viacerých žiadostí o odoslanie smerom k LINK Mobility.
5. Autentifikácia
Používateľské meno a heslo sa odosielajú v každej žiadosti pomocou schémy základnej autentifikácie HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Prihlasovacie údaje sa odosielajú v hlavičke Autorizácia v požiadavke HTTP. Klient vytvorí pole hlavičky, ako je opísané tu:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Napríkladample, ak je používateľské meno john a changeme je heslo, výsledná hlavička Autorizácie je:
Oprávnenie: Základné am9objpjaGFuZ2VtZSA=
Ako rezervu je možné zadať používateľské meno a heslo ako parametre požiadavky. Toto sa odporúča len pre klientov, ktorí nepodporujú Basic Auth.
6. Odoslanie žiadosti
6.1 Reťazec dopytu
Parametre požiadavky sa odosielajú ako reťazec dopytu obsahujúci páry názov/hodnota. Reťazec dopytu je zakódovaný pomocou Percent Encoding (URL kódovanie).
http://www.w3schools.com/tags/ref_urlencode.asp
Napríkladample, Ahoj svet! je zakódovaný ako Hello+World%21.
6.2 Povinné parametre požiadavky
| Meno | Maximálna dĺžka | Popis |
| cieľová adresa | 40 | MSISDN, na ktoré sa má SMS správa odoslať, počnúc kódom krajiny. Naprample: 46123456789. Na niektorých trhoch (kde musí byť MSISDN spotrebiteľa obfuskované) môže byť touto hodnotou aj alfanumerický alias s predponou „#“. |
| messageText | 1600 | Obsah SMS správy. |
6.3 Voliteľné parametre požiadavky (pre pokročilé použitie)
| Meno | Maximálna dĺžka | Popis |
| pôvodná adresa | 16 | Pôvodná adresa pre odchádzajúcu SMS správu. Typ pôvodnej adresy je definovaný parametrom originatorTON. Krátke číslo, maximálna dĺžka je 16. Alfanumerický odosielateľ je obmedzený na predvolenú abecedu GSM s maximálnou dĺžkou 11 znakov. Maximálna dĺžka odosielateľa MSISDN je 15 (s použitím rovnakého formátu ako prvok destinationAddress). Môže byť vynechané, keď pôvodnú adresu a pôvodnú TON vyberie systém. Táto funkcia závisí od trhu a konfigurácie. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| pôvodcaTON | 1 | Typ čísla pôvodnej adresy (TON): 0 – krátke číslo 1 – Alfanumerické (maximálna dĺžka 11) 2 – MSISDN Môže sa vynechať, keď pôvodná adresa a pôvodná TON vyberie systém. Táto funkcia závisí od trhu a konfigurácie. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| userDataHeader | 280 | Hlavička užívateľských dát spolu s užívateľskými dátami môže obsahovať až 140, tj 280 pri hex-kódovaní oktetov. Tento parameter je vždy hex-kódovaný. |
| DCS | 3 | Schéma kódovania údajov. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| PID | 3 | ID protokolu. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| relatívny čas platnosti | 6 | Relatívny čas platnosti v sekundách (v pomere k času odoslania do LINK Mobility). Maximálna hodnota je 604800 (7 dní) a predvolená hodnota je 48 hodín. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| dodacia lehota | 20 | Časamp kedy má byť SMS správa doručená (oneskorený čas doručenia). Pozrite si časť o formáte dátumu a času. |
| statusReportFlags | 1 | Doručiť žiadosť o správu: 0 – Žiadna správa o doručení (predvolené) 1 – Požadovaná správa o doručení 9 – Požadovaná správa o doručení servera (LINK Mobility nepošle správu poskytovateľovi služby, ale sprístupní ju v správach atď.) |
| campaignName | 50 | Transakcie LINK Mobility sú tags týmto menom. Používa sa na zoskupenie transakcií v prehľadoch mobility odkazov. |
| maxConcatenatedMessages | 1 | Hodnota medzi 1 a 10, ktorá definuje, koľko zreťazených správ je povolených. Predvolená hodnota je 3. |
| correlationId | 100 | ID poskytnuté poskytovateľom služieb, ktoré bude uvedené v správe o doručení. |
| užívateľské meno | 100 | Poskytuje sa ako alternatíva k základnému overeniu HTTP. |
| heslo | 100 | Poskytuje sa ako alternatíva k základnému overeniu HTTP. |
6.4 Metódy požiadaviek HTTP
Pre maximálnu interoperabilitu rozhranie API podporuje metódy požiadaviek HTTP GET aj POST. Žiadne iné metódy HTTP nie sú povolené.
6.4.1 ZÍSKAJTE
Zakódovaný reťazec dopytu sa pripojí k súboru URL.
GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Ahoj+svet%21
Oprávnenie: Základné am9objpjaGFuZ2VtZSA=
6.4.2 POST
Zakódovaný reťazec dotazu sa odošle v tele správy požiadavky HTTP. Content-Type je application/x-www-form-urlzakódované.
POST https://europe.ipx.com/restapi/v1/sms/send
Hostiteľ: europe.ipx.com
Typ obsahu: application / x-www-form-urlzakódované
Oprávnenie: Základné am9objpjaGFuZ2VtZSA=
Obsah - dĺžka: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Dátum a čas
Parametre v REST API predstavujúce dátum a čas sú vždy v časovom pásme UTC (Coordinated Universal Time). Timestamps sú reprezentované ako reťazec s týmto presným formátom:
2017-04-25T23:20:50Z
To predstavuje 20 minút a 50 sekúnd po 23. hodine 25. apríla 2017 v UTC.
7. Správa s odpoveďou
Po prijatí a interpretácii správy s požiadavkou API odpovie správou HTTP odpovede.
7.1 Stavový kód HTTP
REST API vždy vráti stavový kód HTTP 200 OK pre spracované požiadavky. Telo správy obsahuje parameter responseCode, ktorý sa používa na určenie presného výsledku.
7.2 Telo správy
Telo správy pozostáva z JSON popisujúceho výsledok požiadavky.
http://json.org/
Link Mobility JSON je v súlade s Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parametre odozvy
| Meno | Maximálna dĺžka | Popis |
| responseCode | 3 | 0 znamená úspešnú transakciu. |
| responseMessage | 255 | Textový popis odpovede, napr. text chyby. |
| timestamp | 20 | Dátum a čas, kedy LINK Mobility spracovala požiadavku. (Pozrite si časť Formát dátumu/času). |
| traceId | 36 | Interný identifikátor Link Mobility. Používa sa na podporu a riešenie problémov. |
| messageIds | 10 x 36 | Pole jedinečných ID správ LINK Mobility pre každú úspešnú správu (ak je správa zreťazená, vráti sa viacero ID správ). Vynechané v prípade poruchy. |
7.4 Prample odpovede
Úspech
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - dĺžka: 144
Dátum: Št, 15. september 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Tu je rovnaký formát JSON pre čitateľnosť:
{
“responseCode“:0,
“responseMessage“:”Úspech”,
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Neúspech
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - dĺžka: 148
Dátum: Št, 15. september 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Neplatné prihlásenie alebo neautorizované použitie API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Úspech
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - dĺžka: 144
Dátum: Št, 15. september 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Tu je rovnaký formát JSON pre čitateľnosť:
{
“responseCode“:0,
“responseMessage“:”Úspech”,
“timestamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Neúspech
HTTP/1.1 200 OK
Content-Type: application/json
Obsah - dĺžka: 148
Dátum: Št, 15. september 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Neplatné prihlásenie alebo neautorizované použitie API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Kódy odpovedí
V odpovedi na odoslanie možno vrátiť nasledujúce kódy odpovede:
| kód | Text | Popis |
| 0 | Úspech | Úspešne vykonaná. |
| 1 | Neplatné prihlásenie alebo neautorizované použitie rozhrania API | Nesprávne používateľské meno alebo heslo alebo Poskytovateľ služieb je blokovaný službou LINK Mobility. |
| 2 | Spotrebiteľ je blokovaný funkciou Link Mobility | Spotrebiteľ je blokovaný službou LINK Mobility. |
| 3 | Prevádzku nezabezpečuje LINK Mobility | Operácia je pre Poskytovateľa služby zablokovaná. |
| 4 | Spotrebiteľa LINK Mobility nepozná | LINK Mobility spotrebiteľa nepozná. Alebo ak bol v žiadosti použitý alias; alias sa nenašiel. |
| 5 | Zákazník zablokoval túto službu v LINK Mobility | Zákazník zablokoval túto službu v LINK Mobility. |
| 6 | Pôvodná adresa nie je podporovaná | Pôvodná adresa nie je podporovaná. |
| 7 | Pôvodná adresa alfa nie je podporovaná účtom | Pôvodná adresa alfa nie je podporovaná účtom. |
| 8 | Pôvodná adresa MSISDN nie je podporovaná | Pôvodná adresa MSISDN nie je podporovaná. |
| 9 | Rozšírenie GSM nie je podporované | Rozšírenie GSM nie je podporované. |
| 10 | Unicode nie je podporované | Unicode nie je podporované. |
| 11 | Správa o stave nie je podporovaná | Správa o stave nie je podporovaná. |
| 12 | Požadovaná funkcia nie je podporovaná | Požadovaná schopnosť (iná ako vyššie uvedená) na odoslanie správy nie je podporovaná. |
| 13 | Maximálna miera obmedzenia poskytovateľa obsahu bola prekročená | Poskytovateľ služby posiela SMS správy do LINK Mobility príliš rýchlo. |
| 14 | ID protokolu nie je podporované účtom | ID protokolu nie je podporované. |
| 15 | Bol prekročený limit zreťazenia správ | Počet zreťazených správ presahuje maximálny požadovaný počet. |
| 16 | Nie je možné smerovať správu. | LINK Mobility nedokázala smerovať správu. |
| 17 | Zakázané časové obdobie | Počas časového obdobia nie je povolené odosielať správy |
| 18 | Príliš nízky zostatok na účte poskytovateľa služieb | Poskytovateľ služby je zablokovaný z dôvodu príliš nízkeho zostatku |
| 50 | Čiastočný úspech | Čiastočný úspech pri odosielaní SMS správy viacerým príjemcom. |
| 99 | Interná chyba servera | Iná chyba Link Mobility, pre viac informácií kontaktujte podporu LINK Mobility. |
| 100 | Neplatná cieľová adresa | Cieľová adresa (MSISDN alebo alias) je neplatná. |
| 102 | Neplatný odkazovaný (prepojený) identifikátor | Referenčné ID je neplatné, možno sa už používa, je príliš staré alebo neznáme. |
| 103 | Neplatný názov účtu | Názov účtu je neplatný. |
| 105 | Neplatné metadáta služby | Metadáta služby sú neplatné. |
| 106 | Neplatná pôvodná adresa | Pôvodná adresa je neplatná. |
| 107 | Neplatná alfanumerická pôvodná adresa | Alfanumerická pôvodná adresa je neplatná. |
| 108 | Neplatný čas platnosti | Čas platnosti je neplatný. |
| 109 | Neplatná dodacia lehota | Dodacia lehota je neplatná. |
| 110 | Neplatný obsah správy/údaje používateľa | Údaje používateľa, teda SMS správa, sú neplatné. |
| 111 | Neplatná dĺžka správy | Dĺžka SMS správy je neplatná. |
| 112 | Neplatná hlavička údajov používateľa | Hlavička údajov používateľa je neplatná. |
| 113 | Neplatná schéma kódovania údajov | DCS je neplatný. |
| 114 | Neplatné ID protokolu | PID je neplatné. |
| 115 | Neplatné príznaky hlásenia stavu | Príznaky správy o stave sú neplatné. |
| 116 | Neplatné TON | Pôvodca TON je neplatný. |
| 117 | Neplatné campaign meno | campaign name je neplatný. |
| 120 | Neplatný limit pre maximálny počet zreťazených správ | Maximálny počet zreťazených správ je neplatný. |
| 121 | Neplatná pôvodná adresa msisdn | Pôvodná adresa MSISDN je neplatná. |
| 122 | Neplatné ID korelácie | ID korelácie je neplatné. |
8. Voliteľné funkcie
8.1 Oprava MSISDN
Korekcia MSISDN je voliteľná funkcia, ktorú môže na požiadanie povoliť podpora LINK Mobility.
Táto funkcia opraví cieľové adresy a zarovná ich do požadovaného formátu E.164. Okrem korekcie formátu môže systém vykonávať aj funkcie špecifické pre trh, ako je preklad medzinárodných francúzskych čísel na opravu čísel DOM-TOM (départements et territoires d'outre-mer), ak je to možné.
Nižšie uvádzame niekoľko examppočet opráv:
| Odoslaná cieľová adresa | Opravená cieľová adresa |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (francúzske číslo preložené na číslo DOM-TOM) |
Okrem toho je možné povoliť národné telefónne čísla pre vybraný trh. Keď je táto funkcia povolená, všetky medzinárodné čísla pre iné trhy musia byť odoslané s počiatočným znakom „+“, aby sa odlíšili od zvoleného trhu.
Nižšie uvádzame niekoľko examppočet opráv vykonaných pri použití Švédska (kód krajiny 46) ako predvoleného trhu pre národné čísla.
| Odoslaná cieľová adresa | Opravená cieľová adresa |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Neplatné, pretože chýba znak „+“. |
Upozorňujeme, že opravené MSISDN použije LINK Mobility a vráti sa do správ o doručení.
Ďalšie informácie získate od podpory LINK Mobility.
8.2 Nahradenie postavy
Nahradenie znakov je voliteľná funkcia, ktorú môže na požiadanie povoliť podpora LINK Mobility.
Táto funkcia preloží znaky abecedy, ktoré nie sú GSM, v používateľských údajoch (text SMS) na ekvivalentné znaky abecedy GSM, keď je DCS nastavený na „GSM“ (17). Napríkladample „Seqüência de teste em Português“ sa preloží ako „Seqüencia de teste em Portugues“.
9. Správy o doručení
Poskytovateľ služby si môže, ak je to zriadené, vyžiadať správy o doručení SMS správ alebo oznámenia o doručení pre odoslané správy MT. Tieto hlásenia sa spúšťajú v SMSC operátora, keď je správa MT buď doručená cieľovému spotrebiteľovi, alebo je vymazaná, napr. vypršala alebo z nejakého dôvodu nie je smerovateľná.
Poskytovateľovi služby sa oznamuje iba konečný stav SMS správy, tj doručená alebo vymazaná. Vygeneruje sa iba jedna správa na správu MT. Pri stave vymazania sa môže použiť kód príčiny. Tento kód príčiny špecifikuje dôvod, prečo SMS správa nebola doručená.
Hlásenia sa smerujú cez LINK Mobility a odosielajú sa poskytovateľovi služieb pomocou protokolu HTTP.
Na prijímanie správ musí poskytovateľ služby implementovať naprample Java Servlet alebo stránka ASP.NET. Obaja prijímajú požiadavky HTTP GET alebo POST.
Parametre
Žiadosť obsahuje nasledujúce parametre:
| Parameter | Typ | M/O/I* | Predvolená hodnota | Maximálna dĺžka | Popis |
| MessageId | reťazec | M | – | 22 | ID správy správy MT, ktorej zodpovedá táto správa. |
| DestinationAddress | reťazec | M | – | 40 | MSISDN spotrebiteľa, teda cieľová adresa pôvodnej MT správy. |
| StatusCode | celé číslo | M | 1 | Stavový kód označuje stav správy MT. Použiteľné stavové kódy sú: 0 – doručené 2 – vymazané (platí kód príčiny) |
|
| TimeStamp | reťazec | M | – | 20 | Čas označujúci, kedy LINK Mobility prijala správu o doručení. Časové pásmo časuamp je SEČ alebo SELČ (s letným časom definovaným pre EÚ). Formát: yyyyMMdd HH:mm:ss. |
| Operátor | reťazec | M | – | 100 | Meno Prevádzkovateľa použité pri odosielaní SMS správy alebo názov účtu použitého pri odosielaní SMS správy. Zoznam dostupných operátorov poskytuje podpora LINK Mobility. |
| ReasonCode | celé číslo | O | – | 3 | Kód príčiny označuje, prečo správa skončila v stave vymazaná. Použiteľné kódy príčin sú: 100 – platnosť vypršala 101 – Zamietnuté 102 – Chyba formátu 103 – Iná chyba 110 – Neznámy účastník 111 – Účastník zakázaný 112 – Účastník nie je poskytnutý 113 – Účastník nedostupný 120 – porucha SMSC 121 – preťaženie SMSC 122 – SMSC roaming 130 – Chyba slúchadla 131 – Pamäť slúchadla je prekročená Správanie sa môže líšiť v závislosti od integrácií operátora. |
| OperatorTimeStamp | reťazec | O | – | 20 | Čas označujúci, kedy bolo hlásenie spustené v SMSC Prevádzkovateľa (ak ho Prevádzkovateľ poskytuje). Časové pásmo časuamp je SEČ alebo SELČ (s letným časom definovaným pre EÚ). Formát: yyyyMMdd HH:mm:ss. |
| StatusText | reťazec | O | – | 255 | Zástupný symbol pre dodatočné informácie od Prevádzkovateľa, napr. jasný textový popis stavu/dôvodu. Správanie sa môže líšiť v závislosti od integrácií operátora. |
| CorrelationId | reťazec | O | – | 100 | ID korelácie poskytnuté v SendRequest alebo SendTextRequest. |
| Kód siete operátora | celé číslo | O | – | 6 | Kód mobilnej siete (MCC + MNC) Prevádzkovateľa. |
* M = povinné, O = voliteľné, I = ignorované.
Poskytovateľ služby musí poskytnúť LINK Mobility s cieľom URL pre správy o doručení (voliteľne vrátane poverení pre základnú autentifikáciu HTTP). Poskytovateľ služby si môže vybrať, ktorú preferovanú metódu HTTP použije:
HTTP POST (odporúča sa)
HTTP GET.
Example pomocou HTTP GET (úspešne doručené):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example pomocou HTTP GET (nedoručené, Prevádzkovateľ dodal timestamp na podujatie):
Parametre sú URL kódovať.
Kódovanie znakov:
Poskytovateľ služby si môže vybrať, ktoré preferované kódovanie znakov sa má použiť:
UTF-8 (odporúčané)
ISO-8859-1.
9.1 Potvrdenie poskytovateľa služieb
Poskytovateľ služby by mal potvrdiť každú správu o doručení. Potvrdenie môže byť kladné, tj doručenie úspešne prijaté, alebo záporné, tj neúspešné.
Poznámka: LINK Mobility má časový limit na čítanie potvrdení 30 sekúnd pre správy o doručení. Časový limit spustí opakovaný pokus o doručenie (ak je povolený opakovaný pokus) alebo zrušenie doručenia (ak je opakovanie zakázané). To znamená, že aplikácia Service Provider musí zabezpečiť rýchlu odozvu, najmä pri vysokej záťaži.
Dôrazne sa odporúča potvrdiť správu o doručení spoločnosti LINK Mobility pred jej spracovaním.
Pravidlo pre pozitívne a negatívne uznanie je opísané takto:
Pozitívne potvrdenie, ACK, doručená správa o doručení:
Kód odpovede rozsahu HTTP 200 v kombinácii s nasledujúcim obsahom vo formáte XML:
Negatívne potvrdenie, NAK, doručenka nebola doručená:
Akákoľvek iná odpoveď ako kladné potvrdenie, naprample, negatívne potvrdenie je spustené akýmkoľvek kódom chyby HTTP alebo nasledujúcim obsahom XML:
Obsah XML možno použiť na riadenie mechanizmu opakovania LINK Mobility. NAK spôsobí opakovaný pokus, ak je povolený. Pre poskytovateľov služieb, ktorí nie sú nakonfigurovaní pre mechanizmus opakovania, je obsah XML voliteľný.
Nižšie je uvedená požiadavka HTTP POST a odpoveď naprample správy o doručení doručenej Poskytovateľovi služby:
HTTP požiadavka:
POST /kontext/aplikácia HTTP/1.1
Typ obsahu: application / x-www-form-urlencoded;charset=utf-8
Hostiteľ: server: port
Obsah - Dĺžka: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP odpoveď:
HTTP/1.1 200 OK
Content-Type: text/plain
9.2 Skúste to znova
Systém LINK Mobility môže vykonať opakované pokusy o neúspešné, tj nepotvrdené doručenie správ o doručení. Poskytovateľ služby si môže zvoliť preferované správanie pri opakovaní:
Žiadny opakovaný pokus (predvolené) – správa sa zahodí pri neúspešnom pokuse o pripojenie, pri prekročení časového limitu čítania alebo pri akomkoľvek chybovom kóde HTTP.
Skúste to znova – správa bude odoslaná znova pre každý typ problému s pripojením, časový limit čítania alebo negatívne potvrdenie.
Keď je povolený opakovaný pokus pre NAK, je dôležité pochopiť, ktoré scenáre vygenerujú pokus o opakovanie z LINK Mobility a ako tento pokus funguje. Každý poskytovateľ služieb má svoj vlastný front opakovaní, kde sú správy zoradené podľa času správamp. Link Mobility sa vždy snaží najskôr doručiť staršie správy, aj keď nie je zaručené individuálne poradie správ doručených Poskytovateľovi služby. Hlavným dôvodom vyradenia správ z frontu opakovania je jeden z dvoch dôvodov: buď vyprší platnosť TTL správy, alebo sa (teoreticky) zaplní front opakovaní. TTL závisí od operátora a účtu, tj môže sa líšiť v závislosti od operátora a/alebo typu správy, napr. prémiová SMS alebo SMS so štandardnou sadzbou.
Poskytovatelia služieb s povoleným opakovaním musia skontrolovať jedinečné ID správy MT, aby sa ubezpečili, že správa ešte nebola prijatá.
Je dôležité, aby Poskytovateľ služby dodržiaval tieto jednoduché pravidlá, keď sa vyskytne chyba počas spracovania správy o doručení, ak je dôvodom chyby: Dočasný, napr. nedostupná databáza, treba vrátiť NAK. LINK Mobility správu odošle znova.
Trvalý a opakovaný pokus pravdepodobne spôsobia rovnaký druh problému, malo by sa vrátiť ACK. Naprample, keď správu nebolo možné správne analyzovať alebo spôsobila neočakávanú chybu behu.
Podľa toho sa zabezpečí, že nedôjde k žiadnemu blokovaniu alebo zníženiu priepustnosti v dôsledku opakovaného odosielania správy o doručení.
10. Tipy na implementáciu
1. Je možné použiť váš web prehliadač odosielať požiadavky do API. Vďaka tomu je veľmi jednoduché skúmať a hodnotiť služby bez akýchkoľvek vývojových nástrojov.
2. Chrome alebo Firefox sa odporúčajú spolu s rozšírením, ako je JSONView na zobrazenie pekne naformátovaného JSON.
3. SoapUI sme použili na testovanie POST, Basic Authentication a na kontrolu nespracovaných správ HTTP požiadaviek a odpovedí.
4. cURL nástroj je užitočný na odosielanie požiadaviek POST so základnou autentifikáciou. Pozri naprample nižšie.
curl Zverejniť \
-H “Typ obsahu: aplikácia/x-www-forma-urlzakódované” \
-H “Oprávnenie: Základné am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
________________
Transformácia personalizovanej komunikácie
Dokumenty / zdroje
 |
LINK Mobility Implementation Guide REST API SMS [pdf] Používateľská príručka Mobilita Implementation Guide REST API SMS, Mobility, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
