LINK Vodič za implementaciju mobilnosti REST API SMS
LINK Mobility pruža uslugu za isporuku poruka, mikro plaćanja i usluge zasnovane na lokaciji. Platforma se ponaša kao transparentni, bijeli akviziter sadržaja i ruter transakcija između pružatelja usluga i operatera.
LINK Mobility pruža RESTful API koji se može koristiti za pristup uslugama LINK Mobility kao što je slanje SMS-a. Ovaj API je dizajniran da bude jednostavan za korištenje i kompatibilan sa svim modernim jezicima i okvirima. Koristeći jezik po vašem izboru, vaša aplikacija može koristiti Link Mobility REST API za implementaciju moćnih mogućnosti slanja poruka i plaćanja
© LINK Mobility, 10. mart 2021
Pravne informacije
Informacije navedene u ovom dokumentu su isključivo vlasništvo i autorska prava Netsize. Povjerljiv je i namijenjen isključivo informativnoj upotrebi. Nije obavezujuće i može biti podložno promjenama bez prethodne najave. Svako neovlašteno otkrivanje ili korištenje smatrat će se nezakonitim.
Netsize™ i linkmobility™ su zaštićeni francuskim, EEZ i međunarodnim zakonima o intelektualnom vlasništvu.
Svi ostali navedeni zaštitni znakovi su isključivo vlasništvo njihovih vlasnika.
Ništa ovde sadržano neće se tumačiti kao davanje bilo koje licence ili prava pod Netsize patentom, autorskim pravom ili žigom.
NETSIZE
Société anonyme au capital de 5 478 070 eura
Siège social :62, avenue Emile Zola92100 Boulogne – Francuska
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Opseg dokumenta
Ovaj dokument opisuje kako Dobavljač usluge koristi LINK Mobility REST API za SMS. Namijenjen je tehničkim arhitektima i projektantima koji implementiraju usluge pružaoca usluga.
1. Osnovna upotreba
Vrlo je lako poslati SMS. Šaljete HTTP zahtjev na LINK Mobility koji se može postići koristeći samo a web pretraživač.
2. Funkcionalni krajview
LINK Mobility sistem pruža sljedeću osnovnu funkcionalnost za SMS poruke:
Slanje mobilnih terminalnih (MT) SMS poruka, kao što su tekstualne ili binarne (npr. WAP Push) premium i standardne poruke.
Prijem izvještaja o isporuci za dostavljene MT poruke.
Primanje SMS poruka sa mobilnog porekla (MO), premium i standardna tarifa.
SMS REST API je namenjen slanju MT SMS poruka standardne brzine.
API šalje sve SMS poruke asinhrono, omogućavajući funkcije kao što su:
“Opali i zaboravi” – Pružalac usluge želi da ima predvidljivije vrijeme odgovora i ne želi da čeka rezultat od Operatera.
Funkcionalnost ponovnog pokušaja – LINK Mobility će ponovo poslati poruku ako operater ima privremene probleme.
2.1 Slanje SMS poruke
Dobavljač usluga Netsize Consumer
- Pošaljite MT poruku
- Vrati ID poruke
- Pošaljite SMS poruku
- Dostavite izvještaj o isporuci
- Pošaljite izvještaj o isporuci
Osnovni tok za slanje SMS poruke je opisan na sljedeći način:
Pružalac usluge postavlja zahtjev za slanje SMS poruke primaocu putem LINK Mobility sistema.
ID poruke se vraća dobavljaču usluga. Ovaj ID se može koristiti za npr. povezivanje poruke sa ispravnim izvještajem o isporuci.
LINK Mobility upravlja rutiranjem i isporučuje SMS poruku adresiranom Potrošaču.
Izvještaj o isporuci se pokreće, npr. kada se SMS poruka dostavi na uređaj Potrošača.
Izvještaj o isporuci se šalje Dobavljaču usluga. Izvještaj sadrži isti ID poruke kao što je vraćeno u koraku 2.
Alternativni tok: Nevažeći zahtjev
Ako su dostavljeni parametri ili korisnički akreditivi u zahtjevu nevažeći, greška se vraća dobavljaču usluge. Greška ukazuje na razlog odbijanja i protok se završava. Ne vraćaju se ID-ovi poruka.
3. Krajnja tačka
SMS resursu se pristupa putem:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Radi sigurnosti veze, LINK Mobility REST API je dostupan samo preko HTTPS-a.
Sertifikat Link Mobility servera je potpisan od strane Thawte Server CA.
4. Operacije
SMS usluga omogućava sljedeće operacije:
| Ime | Put |
| Pošalji | /restapi/v1/sms/send |
4.1 Pošalji
Operacija slanja se koristi za slanje SMS-a jednom primaocu.
Ova operacija je namijenjena i osnovnim i naprednim korisnicima. U najjednostavnijem slučaju, za isporuku SMS-a potrebni su samo adresa odredišta i tekst poruke. LINK Mobility će otkriti šemu kodiranja podataka i izvršiti automatsku konkatenaciju poruke u više dijelova poruke ako je potrebno.
Za naprednu upotrebu, Dobavljač usluga može koristiti opcione parametre za potpunu kontrolu formatiranja poruke uključujući zaglavlje korisničkih podataka.
Pružalac usluge može slati povezane poruke, ali pripremu korisničkih podataka i zaglavlja korisničkih podataka mora izvršiti Pružalac usluge i poruka mora biti poslana putem višestrukih zahtjeva za slanje prema LINK Mobility.
5. Autentifikacija
Korisničko ime i lozinka se šalju u svakom zahtjevu koristeći HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Akreditivi se šalju u zaglavlju autorizacije u HTTP zahtjevu. Klijent konstruiše polje zaglavlja kako je ovde opisano:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Za nprample, ako je korisničko ime john, a changeme lozinka, rezultirajuće zaglavlje autorizacije je:
Autorizacija: Osnovni am9objpjaGFuZ2VtZSA=
Kao zamjenski, korisničko ime i lozinka se mogu poslati kao parametri zahtjeva. Ovo se preporučuje samo za klijente koji ne podržavaju Basic Auth.
6. Podnošenje zahtjeva
6.1 String upita
Parametri zahtjeva se šalju kao string upita koji sadrži parove ime/vrijednost. Niz upita je kodiran korištenjem procentnog kodiranja (URL kodiranje).
http://www.w3schools.com/tags/ref_urlencode.asp
Za nprample, Hello World! je kodiran kao Hello+World%21.
6.2 Obavezni parametri zahtjeva
| Ime | Max dužina | Opis |
| odredišna adresa | 40 | MSISDN na koji treba poslati SMS poruku, počevši od koda zemlje. Prample: 46123456789. Za neka tržišta (gdje potrošački MSISDN mora biti zamagljen) ova vrijednost također može biti alfanumerički pseudonim, s prefiksom „#“. |
| messageText | 1600 | Sadržaj SMS poruke. |
6.3 Opcijski parametri zahtjeva (za naprednu upotrebu)
| Ime | Max dužina | Opis |
| originatingAddress | 16 | Početna adresa za odlaznu SMS poruku. Tip izvorne adrese definiran je parametrom originatorTON. Maksimalna dužina kratkog broja je 16. Alfa numerički pošiljalac je ograničen na GSM zadanu abecedu sa maksimalnom dužinom od 11 znakova. Maksimalna dužina MSISDN pošiljaoca je 15 (koristeći isti format kao element destinationAddress). Može se izostaviti kada sistem odabere originatingAddress i originatingTON. Ova funkcija ovisi o tržištu i konfiguraciji. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| originatorTON | 1 | Vrsta broja izvorne adrese (TON): 0 – Kratak broj 1 – Alfa numerički (maksimalna dužina 11) 2 – MSISDN Može se izostaviti kada će sistem odabrati originatingAddress i originatingTON. Ova funkcija ovisi o tržištu i konfiguraciji. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| userDataHeader | 280 | Zaglavlje korisničkih podataka zajedno sa korisničkim podacima može sadržavati do 140, odnosno 280 kada je heksadecimalno kodirano, okteta. Ovaj parametar je uvijek heksadecimalni kodiran. |
| DCS | 3 | Šema kodiranja podataka. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| PID | 3 | ID protokola. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| relativnoValidityTime | 6 | Relativno vrijeme važenja u sekundama (u odnosu na vrijeme podnošenja na LINK Mobility). Maksimalna vrijednost je 604800 (7 dana), a zadana vrijednost je 48 sati. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| Vrijeme isporuke | 20 | Timestamp kada SMS poruka treba biti dostavljena (odgođeno vrijeme isporuke). Pogledajte odjeljak o formatu datuma i vremena. |
| statusReportFlags | 1 | Zahtjev za dostavu izvještaja: 0 – Nema izvještaja o isporuci (podrazumevano) 1 – Zatražen izvještaj o isporuci 9 – Zatražen je izvještaj o isporuci servera (LINK Mobility ne prosljeđuje izvještaj dobavljaču usluga, ali ga čini dostupnim u izvještajima itd.) |
| campaignName | 50 | Transakcije LINK Mobility su tagged sa ovim imenom. Koristi se za grupisanje transakcija u izvještajima o mobilnosti veza. |
| maxConcatenatedMessages | 1 | Vrijednost između 1 i 10 koja definira koliko je spojenih poruka dozvoljeno. Podrazumevano je 3. |
| correlationId | 100 | ID koji je dao pružalac usluge koji će se prikazati u Izvještaju o isporuci. |
| korisničko ime | 100 | Pruža se kao alternativa HTTP osnovnoj autentifikaciji. |
| lozinka | 100 | Pruža se kao alternativa HTTP osnovnoj autentifikaciji. |
6.4 Metode HTTP zahtjeva
Za maksimalnu interoperabilnost, API podržava i HTTP GET i POST metode zahtjeva. Druge HTTP metode nisu dozvoljene.
6.4.1 GET
Kodirani niz upita se dodaje na URL.
GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Zdravo+Svijet%21
Autorizacija: Osnovni am9objpjaGFuZ2VtZSA=
6.4.2 POST
Kodirani niz upita se šalje u tijelu poruke HTTP zahtjeva. Content-Type je aplikacija/x-www-form-urlkodiran.
POST https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Content-Type: application/x-www-form-urlkodiran
Autorizacija: Osnovni am9objpjaGFuZ2VtZSA=
Dužina sadržaja: 57
destinacijaAddress=46123456789&messageText=Zdravo+Svijet%21
6.5 Datum i vrijeme
Parametri u REST API-ju koji predstavljaju datum i vrijeme uvijek su u UTC vremenskoj zoni (koordinirano univerzalno vrijeme). Timestamps su predstavljeni kao string sa ovim tačnim formatom:
2017-04-25T23:20:50Z
Ovo predstavlja 20 minuta i 50 sekundi nakon 23. sata 25. aprila 2017. u UTC.
7. Poruka odgovora
Nakon primanja i tumačenja poruke zahtjeva, API odgovara porukom HTTP odgovora.
7.1 HTTP statusni kod
REST API uvijek vraća HTTP statusni kod 200 OK za obrađene zahtjeve. Tijelo poruke sadrži parametar responseCode koji se koristi za određivanje točnog ishoda.
7.2 Tijelo poruke
Tijelo poruke sastoji se od JSON-a koji opisuje ishod zahtjeva.
http://json.org/
Link Mobility JSON je u skladu sa Google JSON vodičem za stil.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parametri odgovora
| Ime | Max dužina | Opis |
| responseCode | 3 | 0 označava uspješnu transakciju. |
| responseMessage | 255 | Tekstualni opis odgovora, npr. tekst greške. |
| timestamp | 20 | Datum i vrijeme kada je LINK Mobility obradio zahtjev. (Pogledajte odjeljak o formatu datuma/vremena). |
| traceId | 36 | Interni identifikator Link Mobility. Koristi se za podršku i rješavanje problema. |
| messageIds | 10 x 36 | Niz jedinstvenih ID-ova poruka LINK Mobility za svaku uspješnu poruku (vraća se više ID-ova poruka ako je poruka spojena). Izostavlja se u slučaju neuspjeha. |
7.4 dokample responses
Uspjeh
HTTP/1.1 200 OK
Content-Type: application/json
Dužina sadržaja: 144
Datum: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Uspjeh”,”vremenskiamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Ovdje je isti JSON formatiran za čitljivost:
{
"responseCode“:0,
"responseMessage“:”Uspjeh”,
"timestamp“:”2016-0915T13:20:31Z”,
"traceId“:”f678d30879fd4adc25f2”,
"messageIds“:[“1-4850879008”] }
Neuspjeh
HTTP/1.1 200 OK
Content-Type: application/json
Dužina sadržaja: 148
Datum: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nevažeća prijava ili neovlašteno korištenje API-ja”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Uspjeh
HTTP/1.1 200 OK
Content-Type: application/json
Dužina sadržaja: 144
Datum: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Uspjeh”,”vremenskiamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Ovdje je isti JSON formatiran za čitljivost:
{
"responseCode“:0,
"responseMessage“:”Uspjeh”,
"timestamp“:”2016-0915T13:20:31Z”,
"traceId“:”f678d30879fd4adc25f2”,
"messageIds“:[“1-4850879008”] }
Neuspjeh
HTTP/1.1 200 OK
Content-Type: application/json
Dužina sadržaja: 148
Datum: Thu, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Nevažeća prijava ili neovlašteno korištenje API-ja”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Kodovi odgovora
Sljedeći kodovi odgovora se mogu vratiti u odgovoru za slanje:
| Kod | Tekst | Opis |
| 0 | Uspjeh | Uspješno izvršeno. |
| 1 | Nevažeća prijava ili neovlašteno korištenje API-ja | LINK Mobility zabranjuje netačno korisničko ime ili lozinku ili dobavljača usluga. |
| 2 | Link Mobility blokira korisnika | LINK Mobility blokira korisnika. |
| 3 | LINK Mobility ne obezbjeđuje rad | Operacija je blokirana za dobavljača usluge. |
| 4 | LINK Mobility je nepoznat potrošač | LINK Mobility je nepoznat potrošač. Ili ako je pseudonim korišten u zahtjevu; alias nije pronađen. |
| 5 | Korisnik je blokirao ovu uslugu u LINK Mobility | Potrošač je blokirao ovu uslugu u LINK Mobility. |
| 6 | Izvorna adresa nije podržana | Izvorna adresa nije podržana. |
| 7 | Alfa izvorna adresa nije podržana od strane naloga | Alfa izvorna adresa nije podržana od strane naloga. |
| 8 | MSISDN izvorna adresa nije podržana | MSISDN izvorna adresa nije podržana. |
| 9 | GSM prošireni nije podržan | GSM prošireni nije podržan. |
| 10 | Unicode nije podržan | Unicode nije podržan. |
| 11 | Izvještaj o statusu nije podržan | Izvještaj o statusu nije podržan. |
| 12 | Potrebna sposobnost nije podržana | Potrebna mogućnost (osim gore navedenih) za slanje poruke nije podržana. |
| 13 | Maksimalna stopa regulacije dobavljača sadržaja je premašena | Pružalac usluge prebrzo šalje SMS poruke na LINK Mobility. |
| 14 | ID protokola nije podržan od strane naloga | ID protokola nije podržan. |
| 15 | Prekoračeno je ograničenje povezivanja poruka | Broj konkateniranih poruka premašuje maksimalan broj traženih. |
| 16 | Nije moguće usmjeriti poruku. | LINK Mobility nije mogao usmjeriti poruku. |
| 17 | Zabranjeni vremenski period | Nije dozvoljeno slanje poruke tokom vremenskog perioda |
| 18 | Prenizak saldo na računu provajdera usluga | Provajder usluga je blokiran zbog preniskog stanja |
| 50 | Djelomičan uspjeh | Djelomičan uspjeh prilikom slanja SMS poruke više primatelja. |
| 99 | Interna greška servera | Druga greška Link Mobility, kontaktirajte LINK Mobility podršku za više informacija. |
| 100 | Nevažeća adresa odredišta | Odredišna adresa (MSISDN ili alias) je nevažeća. |
| 102 | Nevažeći referentni (povezani) ID | Referentni ID je nevažeći, možda je referentni ID već korišten, prestar ili nepoznat. |
| 103 | Nevažeći naziv računa | Naziv računa je nevažeći. |
| 105 | Nevažeći meta podaci usluge | Meta podaci usluge su nevažeći. |
| 106 | Nevažeća adresa porijekla | Izvorna adresa je nevažeća. |
| 107 | Nevažeća alfanumerička izvorna adresa | Alfanumerička izvorna adresa je nevažeća. |
| 108 | Nevažeće vrijeme valjanosti | Vrijeme valjanosti je nevažeće. |
| 109 | Nevažeće vrijeme isporuke | Vrijeme isporuke je nevažeće. |
| 110 | Nevažeći sadržaj poruke/korisnički podaci | Korisnički podaci, odnosno SMS poruka su nevažeći. |
| 111 | Nevažeća dužina poruke | Dužina SMS poruke je nevažeća. |
| 112 | Nevažeće zaglavlje korisničkih podataka | Zaglavlje korisničkih podataka je nevažeće. |
| 113 | Nevažeća šema kodiranja podataka | DCS je nevažeći. |
| 114 | Nevažeći ID protokola | PID je nevažeći. |
| 115 | Nevažeće oznake izvještaja o statusu | Oznake izvještaja o statusu su nevažeće. |
| 116 | Nevažeći TON | Izvornik TON je nevažeći. |
| 117 | Nevažeći campaign name | Campnaziv aign je nevažeći. |
| 120 | Nevažeće ograničenje za maksimalan broj povezanih poruka | Maksimalan broj povezanih poruka je nevažeći. |
| 121 | Nevažeća msisdn izvorna adresa | Izvorna adresa MSISDN-a je nevažeća. |
| 122 | Nevažeći ID korelacije | ID korelacije je nevažeći. |
8. Opcione karakteristike
8.1 MSISDN ispravka
MSISDN ispravka je opciona funkcija koju može omogućiti podrška LINK Mobility ako se to zatraži.
Ova funkcija će ispraviti odredišne adrese i uskladiti ih sa potrebnim E.164 formatom. Pored ispravke formata, sistem takođe može obavljati funkciju specifične za tržište, kao što je prevođenje međunarodnih francuskih brojeva za ispravljanje DOM-TOM (départements et territoires d'outre-mer) brojeva kada je to primenjivo.
Ispod je nekoliko exampispravke:
| Poslana adresa odredišta | Ispravljena adresa odredišta |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (francuski broj preveden na DOM-TOM broj) |
Dodatno, moguće je dozvoliti nacionalne telefonske brojeve za odabrano tržište. Kada je ova funkcija omogućena, bilo koji međunarodni brojevi za druga tržišta moraju biti poslani sa početnim znakom `+' kako bi se razlikovali od odabranog tržišta.
Ispod je nekoliko exampispravke učinjene kada se koristi Švedska (šifra zemlje 46) kao zadano tržište za nacionalne brojeve.
| Poslana adresa odredišta | Ispravljena adresa odredišta |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Nevažeći jer nedostaje znak '+' |
Imajte na umu da će ispravljeni MSISDN koristiti LINK Mobility i da će biti vraćen u izvještajima o isporuci.
Molimo kontaktirajte LINK Mobility podršku za više informacija.
8.2 Zamjena karaktera
Zamjena karaktera je opciona funkcija koju može omogućiti LINK Mobility podrška ako se to zatraži.
Ova funkcija će prevesti znakove ne-GSM abecede u korisničkim podacima (SMS tekst) u ekvivalentne znakove GSM abecede kada je DCS postavljen na “GSM” (17). Za nprample “Seqüência de teste em Português” će biti prevedeno u “Seqüencia de teste em Portugues”.
9. Izvještaji o isporuci
Pružalac usluga može, ako je omogućen, zahtijevati izvještaje o isporuci SMS poruka ili obavještenja o isporuci za poslane MT poruke. Ovi izvještaji se pokreću u SMSC operateru kada se MT poruka ili isporuči ciljanom potrošaču ili obriše, npr. istekla ili, iz nekog razloga, nije rutabilna.
Samo konačni status SMS poruke se prijavljuje Pružaocu usluge, odnosno isporučena ili obrisana. Generira se samo jedan izvještaj po MT poruci. Sa izbrisanim statusom može se primijeniti šifra razloga. Ova šifra razloga navodi razlog zašto SMS poruka nije isporučena.
Izvještaji se usmjeravaju preko LINK Mobility i šalju dobavljaču usluga koristeći HTTP protokol.
Da bi primio izvještaje, Pružalac usluga treba da implementira nprampna Java servlet ili ASP.NET stranicu. Oba primaju HTTP GET ili POST zahtjeve.
Parameters
Zahtjev uključuje sljedeće parametre:
| Parametar | Tip | M/O/I* | Zadana vrijednost | Max dužina | Opis |
| MessageId | string | M | – | 22 | ID poruke MT poruke kojoj ovaj izvještaj odgovara. |
| DestinationAddress | string | M | – | 40 | MSISDN korisnika, odnosno odredišna adresa originalne MT poruke. |
| StatusCode | cijeli broj | M | 1 | Statusni kod označava status MT poruke. Primjenjivi statusni kodovi su: 0 – Isporučeno 2 – Izbrisano (primjenjuje se šifra razloga) |
|
| TimeStamp | string | M | – | 20 | Vrijeme koje pokazuje kada je LINK Mobility primio izvještaj o isporuci. Vremenska zona vremenaamp je CET ili CEST (sa ljetnim računanjem vremena kako je definirano za EU). Format: ggggMMdd HH:mm:ss. |
| Operater | string | M | – | 100 | Ime Operatera koji se koristi prilikom slanja SMS poruke ili ime naloga koji se koristi prilikom slanja SMS poruke. Listu dostupnih operatera pruža LINK Mobility podrška. |
| ReasonCode | cijeli broj | O | – | 3 | Šifra razloga pokazuje zašto je poruka završila u statusu izbrisana. Primjenjivi kodovi razloga su: 100 – istekao 101 – Odbijeno 102 – Greška u formatu 103 – Druga greška 110 – Pretplatnik nepoznat 111 – Pretplatnik zabranjen 112 – Pretplatnik nije opskrbljen 113 – Pretplatnik nedostupan 120 – SMSC kvar 121 – SMSC zagušenje 122 – SMSC roming 130 – Greška slušalice 131 – Prekoračena je memorija slušalice Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| OperatorTimeStamp | string | O | – | 20 | Vrijeme koje pokazuje kada je izvještaj pokrenut u SMSC-u Operatora (ukoliko ga je dostavio Operator). Vremenska zona vremenaamp je CET ili CEST (sa ljetnim računanjem vremena kako je definirano za EU). Format: ggggMMdd HH:mm:ss. |
| StatusText | string | O | – | 255 | Čuvar mjesta za dodatne informacije od Operatera, npr. jasan tekstualni opis statusa/razloga. Ponašanje se može razlikovati u zavisnosti od integracija operatera. |
| CorrelationId | string | O | – | 100 | ID korelacije naveden u SendRequest ili SendTextRequest. |
| OperatorNetworkCode | cijeli broj | O | – | 6 | Kod mobilne mreže (MCC + MNC) Operatera. |
* M = obavezno, O = opciono, I = zanemareno.
Pružalac usluga mora obezbijediti LINK Mobility sa metom URL za izvještaje o isporuci (opcionalno uključujući vjerodajnice za HTTP osnovnu autentifikaciju). Dobavljač usluga može odabrati koji preferirani HTTP metod će koristiti:
HTTP POST (preporučeno)
HTTP GET.
Example koristeći HTTP GET (uspješno isporučeno):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example koristeći HTTP GET (nije isporučeno, Operater je dao vremenski okviramp za događaj):
Parametri su URL encodedi.
Kodiranje znakova:
Dobavljač usluga može odabrati koje će željeno kodiranje znakova koristiti:
UTF-8 (preporučeno)
ISO-8859-1.
9.1 Potvrda dobavljača usluga
Pružalac usluga treba da potvrdi svaki izvještaj o isporuci. Potvrda može biti pozitivna, odnosno izvještaj o isporuci uspješno primljen, ili negativan, odnosno neuspješan.
Napomena: LINK Mobility ima vremensko ograničenje čitanja za potvrde od 30 sekundi za izvještaje o isporuci. Vremensko ograničenje će pokrenuti ponovni pokušaj isporuke (ako je ponovni pokušaj omogućen) ili otkazivanje isporuke (ako je ponovni pokušaj onemogućen). To znači da aplikacija dobavljača usluga mora osigurati brzo vrijeme odgovora, posebno pri velikom opterećenju.
Veoma je preporučljivo da potvrdite izvještaj o isporuci LINK Mobility prije obrade.
Pravilo za pozitivnu i negativnu potvrdu je opisano kako slijedi:
Pozitivna potvrda, ACK, dostavljen izvještaj o isporuci:
HTTP 200 kod odgovora raspona u kombinaciji sa sljedećim sadržajem u XML formatu:
Negativna potvrda, NAK, izvještaj o isporuci nije dostavljen:
Svaki odgovor osim pozitivnog priznanja, nprampda, negativnu potvrdu pokreće bilo koji HTTP kod greške ili sljedeći XML sadržaj:
XML sadržaj se može koristiti za kontrolu mehanizma ponovnog pokušaja LINK Mobility. NAK će uzrokovati pokušaj ponovnog pokušaja, ako je omogućen. Za dobavljače usluga koji nisu konfigurirani za mehanizam ponovnog pokušaja, XML sadržaj je opcionalan.
Ispod je HTTP POST zahtjev i odgovor nprampzapis izvještaja o isporuci dostavljenog pružaocu usluga:
HTTP zahtjev:
POST /context/app HTTP/1.1
Content-Type: application/x-www-form-urlencoded;charset=utf-8
Host: server:port
Dužina sadržaja: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP odgovor:
HTTP/1.1 200 OK
Content-Type: text/plain
9.2 Pokušaj ponovo
Sistem LINK Mobility može izvršiti pokušaje ponovnog pokušaja za neuspješne, tj. nepotvrdjene isporuke izvještaja o isporuci. Dobavljač usluga može odabrati željeno ponašanje ponovnog pokušaja:
Nema ponovnog pokušaja (podrazumevano) – poruka će biti odbačena ako pokušaj povezivanja ne uspe, istekne vreme za čitanje ili za bilo koji HTTP kod greške.
Pokušaj ponovo – poruka će biti ponovo poslana za svaku vrstu problema sa vezom, vremensko ograničenje čitanja ili negativnu potvrdu.
Kada je omogućen ponovni pokušaj za NAK, važno je razumjeti koji scenariji će generirati pokušaj ponovnog pokušaja od LINK Mobility i kako taj ponovni pokušaj funkcionira. Svaki dobavljač usluga ima svoj vlastiti red za ponovni pokušaj, gdje su poruke poređane prema vremenu porukeamp. Link Mobility uvijek prvo pokušava isporučiti starije poruke, iako pojedinačni redoslijed poruka koje se isporučuju dobavljaču usluga nije zajamčen. Glavni razlog zašto se poruke odbacuju iz reda za ponovni pokušaj jedan je od dva razloga: ili TTL poruka ističe ili (teoretski) red za ponovni pokušaj postaje pun. TTL zavisi od operatera i naloga, tj. može varirati u zavisnosti od operatera i/ili tipa poruke, npr. premium SMS ili SMS poruka sa standardnom tarifom.
Dobavljači usluga s omogućenim ponovnim pokušajem moraju provjeriti jedinstveni ID MT poruke kako bi osigurali da poruka već nije primljena.
Važno je da se pružalac usluga pridržava ovih jednostavnih pravila kada dođe do greške tokom obrade izvještaja o isporuci ako je razlog greške: privremeni, npr. baza podataka nije dostupna, treba vratiti NAK. LINK Mobility će ponovo poslati poruku.
Trajni i pokušaj ponovnog pokušaja će vjerovatno uzrokovati istu vrstu problema, ACK bi trebao biti vraćen. Za nprample, kada poruka nije mogla biti ispravno raščlanjena ili je izazvala neočekivanu grešku u toku izvođenja.
Postupanje u skladu s tim osigurat će da ne dođe do blokiranja ili degradacije protoka zbog ponovnog slanja izvještaja o isporuci.
10. Savjeti za implementaciju
1. Moguće je koristiti svoj web pretraživač za podnošenje zahtjeva API-ju. Ovo čini vrlo lakim istraživanje i procjenu usluga bez ikakvih razvojnih alata.
2. Chrome ili Firefox se preporučuju zajedno sa ekstenzijom kao što je JSONView za prikaz prilično formatiranog JSON-a.
3. Koristili smo SoapUI za testiranje POST-a, osnovne provjere autentičnosti i za inspekciju sirovih HTTP poruka zahtjeva i odgovora.
4. CURL alat je koristan za podnošenje POST zahtjeva sa osnovnom autentifikacijom. Vidi prample ispod.
curl POST \
-H “Content-Type: application/x-www-form-urlkodirano” \
-H “Ovlašćenje: Osnovni am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–podaci “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
Transformacija personalizirane komunikacije
Dokumenti / Resursi
 |
LINK Vodič za implementaciju mobilnosti REST API SMS [pdf] Korisnički priručnik Vodič za implementaciju mobilnosti REST API SMS, mobilnost, vodič za implementaciju REST API SMS, REST API SMS, API SMS, SMS |
