LINK Mobility Implementation Guide REST API SMS
LINK Mobility tarjoaa palvelun viestien välitykseen, mikromaksuihin ja sijaintiin perustuviin palveluihin. Alusta toimii läpinäkyvänä, white label -sisällön hankkijana ja tapahtumareitittimenä palveluntarjoajien ja operaattoreiden välillä.
LINK Mobility tarjoaa RESTful API:n, jota voidaan käyttää LINK Mobility -palveluihin, kuten tekstiviestien lähettämiseen. Tämä API on suunniteltu helppokäyttöiseksi ja yhteensopivaksi kaikkien nykyaikaisten kielten ja kehysten kanssa. Valitsemallasi kielellä sovelluksesi voi käyttää Link Mobility REST API -sovellusliittymää tehokkaiden viesti- ja maksuominaisuuksien toteuttamiseen.
© LINK Mobility, 10. maaliskuuta 2021
Lakitiedot
Tässä asiakirjassa annetut tiedot ovat Netsizen yksinomaista omaisuutta ja tekijänoikeuksia. Se on luottamuksellinen ja tarkoitettu vain tiedoksi. Se ei ole sitova ja sitä voidaan muuttaa ilman erillistä ilmoitusta. Kaikki luvaton luovuttaminen tai käyttö katsotaan laittomaksi.
Netsize™ ja linkmobility™ ovat Ranskan, ETY:n ja kansainvälisten immateriaalioikeuslakien suojaamia.
Kaikki muut mainitut tavaramerkit ovat omistajiensa omaisuutta.
Mitään tämän sisällön ei tule tulkita myöntävän Netsizen patentin, tekijänoikeuden tai tavaramerkin alaisia lisenssejä tai oikeuksia.
NETSIZE
Société anonyme au capital de 5 478 070 euroa
Siège social :62, avenue Emile Zola 92100 Boulogne – Ranska
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Asiakirjan laajuus
Tässä asiakirjassa kuvataan, kuinka palveluntarjoaja käyttää LINK Mobility REST -sovellusliittymää tekstiviesteissä. Se on tarkoitettu teknisille arkkitehdeille ja suunnittelijoille, jotka toteuttavat Palveluntarjoajan palveluita.
1. Peruskäyttö
Tekstiviestin lähettäminen on erittäin helppoa. Lähetät HTTP-pyynnön LINK Mobilitylle, joka voidaan suorittaa käyttämällä vain a web selain.
2. Toiminnallinen yliview
LINK Mobility -järjestelmä tarjoaa seuraavat perustoiminnot tekstiviesteille:
Mobiilipäätettävien (MT) tekstiviestien, kuten teksti- tai binääriviestien (esim. WAP Push) lähettäminen premium- ja normaalihintaisten viestien lähettämiseen.
Lähetettyjen MT-viestien toimitusraporttien vastaanottaminen.
Mobiilialkuperäisten (MO) tekstiviestien vastaanottaminen lisämaksusta ja normaalihinnasta.
SMS REST API on omistettu normaalihintaisten MT-tekstiviestien lähettämiseen.
API lähettää kaikki tekstiviestit asynkronisesti mahdollistaen ominaisuudet, kuten:
”Tulta ja unohda” – Palveluntarjoaja haluaa ennustettavampia vasteaikoja, eikä halua odottaa tulosta Operaattorilta.
Yritä uudelleen - LINK Mobility lähettää viestin uudelleen, jos operaattorilla on tilapäisiä ongelmia.
2.1 Tekstiviestin lähettäminen
Palveluntarjoaja Netsize Consumer
- Lähetä MT-viesti
- Palautusviestin tunnus
- Lähetä tekstiviesti
- Toimita toimitusraportti
- Lähetä toimitusraportti
SMS-viestien lähettämisen peruskulku on kuvattu seuraavasti:
Palveluntarjoaja pyytää lähettämään tekstiviestin vastaanottajalle LINK Mobility -järjestelmän kautta.
Palveluntarjoajalle palautetaan viestitunnus. Tämän tunnuksen avulla voidaan esim. korreloida viesti oikean toimitusraportin kanssa.
LINK Mobility hoitaa reitityksen ja toimittaa tekstiviestin osoitetulle Kuluttajalle.
Toimitusraportti laukeaa esim. kun tekstiviesti toimitetaan Kuluttajan laitteeseen.
Toimitusraportti lähetetään Palveluntarjoajalle. Raportti sisältää saman viestitunnuksen, joka palautettiin vaiheessa 2.
Vaihtoehtoinen kulku: Virheellinen pyyntö
Jos pyynnössä annetut parametrit tai käyttäjätunnukset ovat virheellisiä, palveluntarjoajalle palautetaan virhe. Virhe osoittaa hylkäämisen syyn ja virtaus päättyy. Viestitunnuksia ei palauteta.
3. Päätepiste
SMS-resurssiin päästään polkulla:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Yhteyden turvallisuuden vuoksi LINK Mobility REST API on käytettävissä vain HTTPS:n kautta.
Link Mobility -palvelimen varmenteen on allekirjoittanut Thawte Server CA.
4. Toiminnot
SMS-palvelu tarjoaa seuraavat toiminnot:
| Nimi | Polku |
| Lähetä | /restapi/v1/sms/send |
4.1 Lähetä
Lähetystoimintoa käytetään tekstiviestin lähettämiseen yhdelle vastaanottajalle.
Tämä toiminto on tarkoitettu sekä perus- että edistyneille käyttäjille. Yksinkertaisimmassa tapauksessa tekstiviestin toimittamiseen tarvitaan vain kohdeosoite ja viestin teksti. LINK Mobility havaitsee Data Coding Scheme -järjestelmän ja suorittaa tarvittaessa viestin automaattisen ketjutuksen useisiin viestin osiin.
Edistyneeseen käyttöön palveluntarjoaja voi käyttää valinnaisia parametreja viestin muotoilun täydelliseen hallintaan, mukaan lukien käyttäjätietojen otsikko.
Palveluntarjoaja voi lähettää ketjutettuja viestejä, mutta käyttäjätietojen ja käyttäjätietojen otsikon valmistelu tulee tehdä Palveluntarjoajan toimesta ja viesti on lähetettävä useilla lähetyspyynnöillä LINK Mobilitylle.
5. Todennus
Käyttäjätunnus ja salasana lähetetään jokaisessa HTTP Basic Authentication Scheme -pyynnössä.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Tunnistetiedot lähetetään HTTP-pyynnön Authorization-otsikossa. Asiakas rakentaa otsikkokentän tässä kuvatulla tavalla:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
esimample, jos käyttäjänimi on john ja changeme on salasana, tuloksena oleva Authorization-otsikko on:
Valtuutus: Basic am9objpjaGFuZ2VtZSA=
Varajäsenenä käyttäjätunnus ja salasana voidaan lähettää pyyntöparametreina. Tätä suositellaan vain asiakkaille, jotka eivät tue perustodennusta.
6. Pyynnön lähettäminen
6.1 Kyselymerkkijono
Pyyntöparametrit lähetetään kyselymerkkijonona, joka sisältää nimi/arvo-parit. Kyselymerkkijono on koodattu käyttämällä prosenttikoodausta (URL koodaus).
http://www.w3schools.com/tags/ref_urlencode.asp
esimample, hei maailma! on koodattu nimellä Hello+World%21.
6.2 Pakolliset pyyntöparametrit
| Nimi | Max pituus | Kuvaus |
| kohdeosoite | 40 | MSISDN, johon tekstiviesti tulee lähettää, alkaen maakoodista. Esimamppuh .: 46123456789. Joillakin markkinoilla (joilla kuluttajan MSISDN on häivytettävä) tämä arvo voi olla myös aakkosnumeerinen alias, jonka etuliitteenä on "#". |
| viestiteksti | 1600 | Tekstiviestin sisältö. |
6.3 Valinnaiset pyyntöparametrit (edenneeseen käyttöön)
| Nimi | Max pituus | Kuvaus |
| lähtöosoite | 16 | Lähtevän tekstiviestin lähtöosoite. Alkuperäisen osoitteen tyyppi määritellään originatorTON-parametrilla. Lyhyen numeron enimmäispituus on 16. Aakkosnumeerinen lähettäjä on rajoitettu GSM-oletusaakkoon, jonka pituus on enintään 11 merkkiä. MSISDN-lähettimen enimmäispituus on 15 (käytetään samaa muotoa kuin destinationAddress-elementti). Voidaan jättää pois, kun järjestelmä valitsee originatingAddress ja originatingTON. Tämä toiminto on markkina- ja kokoonpanoriippuvainen. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| alullepanijaTON | 1 | Alkuperäisen osoitteen numerotyyppi (TON): 0 – lyhyt numero 1 – alfanumeerinen (maksimipituus 11) 2 – MSISDN Voidaan jättää pois, kun järjestelmä valitsee originatingAddress ja originatingTON. Tämä toiminto on markkina- ja kokoonpanoriippuvainen. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| userDataHeader | 280 | User Data Header yhdessä User Datan kanssa voi sisältää enintään 140 eli 280 heksadesimaalikoodattua oktettia. Tämä parametri on aina hex-koodattu. |
| DCS | 3 | Tietojen koodauskaavio. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| PID | 3 | Protokollan tunnus. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| suhteellinenValidityTime | 6 | Suhteellinen voimassaoloaika sekunteina (suhteessa LINK Mobilitylle lähetysaikaan). Enimmäisarvo on 604800 (7 päivää) ja oletusarvo on 48 tuntia. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| toimitusaika | 20 | Aikaisinamp milloin tekstiviesti pitäisi toimittaa (viivästynyt toimitusaika). Katso päivämäärän ja kellonajan muotoa koskeva kohta. |
| statusReportFlags | 1 | Toimita raporttipyyntö: 0 – Ei toimitusraporttia (oletus) 1 – Toimitusraportti pyydetty 9 – Palvelimen toimitusraportti pyydetty (LINK Mobility ei välitä raporttia palveluntarjoajalle, vaan antaa sen saataville raporteissa jne.) |
| campaignName | 50 | LINK Mobility -tapahtumat ovat tagged tällä nimellä. Sitä käytetään tapahtumien ryhmittelyyn Link Mobility -raporteissa. |
| maxConcatenatedMessages | 1 | Arvo väliltä 1–10, joka määrittää, kuinka monta ketjutettua viestiä on sallittu. Oletusarvo on 3. |
| korrelaatioId | 100 | Palveluntarjoajan antama tunnus, joka toistetaan toimitusraportissa. |
| käyttäjätunnus | 100 | Toimitetaan vaihtoehtona HTTP-perustodennuksen käyttöön. |
| salasana | 100 | Toimitetaan vaihtoehtona HTTP-perustodennuksen käyttöön. |
6.4 HTTP-pyyntömenetelmät
Maksimaalisen yhteentoimivuuden saavuttamiseksi API tukee sekä HTTP GET- että POST-pyyntömenetelmiä. Muita HTTP-menetelmiä ei sallita.
6.4.1 HANKI
Koodattu kyselymerkkijono liitetään URL.
SAADA
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hei+Maailma%21
Valtuutus: Basic am9objpjaGFuZ2VtZSA=
6.4.2 POST
Koodattu kyselymerkkijono lähetetään HTTP-pyyntöviestin rungossa. Sisältötyyppi on hakemus/x-www-lomake-urlkoodattu.
LÄHETTÄÄ https://europe.ipx.com/restapi/v1/sms/send
Isäntä: europe.ipx.com
Sisältötyyppi: application / x-www-form-urlkoodattu
Valtuutus: Basic am9objpjaGFuZ2VtZSA=
Sisällön pituus: 57
destinationAddress=46123456789&messageText=Hei+Maailma%21
6.5 Päivämäärä ja aika
REST API:n parametrit, jotka edustavat päivämäärää ja aikaa, ovat aina UTC-aikavyöhykkeellä (Coordinated Universal Time). Timestamps esitetään merkkijonona täsmälleen tässä muodossa:
2017-04-25T23:20:50Z
Tämä tarkoittaa 20 minuuttia ja 50 sekuntia 23. tunnin jälkeen 25. huhtikuuta 2017 UTC:ssä.
7. Vastausviesti
Pyyntöviestin vastaanottamisen ja tulkinnan jälkeen API vastaa HTTP-vastausviestillä.
7.1 HTTP-tilakoodi
REST API palauttaa aina HTTP-tilakoodin 200 OK käsitellyille pyynnöille. Viestin runko sisältää parametrin responseCode, jota käytetään tarkan tuloksen määrittämiseen.
7.2 Viestin runko
Viestin runko koostuu JSON:sta, joka kuvaa pyynnön tulosta.
http://json.org/
Link Mobility JSON on Googlen JSON-tyylioppaan mukainen.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Vastausparametrit
| Nimi | Max pituus | Kuvaus |
| vastauskoodi | 3 | 0 osoittaa onnistuneen tapahtuman. |
| vastausviesti | 255 | Vastauksen tekstikuvaus, esim. virheteksti. |
| kertaaamp | 20 | Päivämäärä ja aika, jolloin LINK Mobility käsitteli pyynnön. (Katso päivämäärän ja kellonajan muoto-osio). |
| jäljitystunnus | 36 | Link Mobilityn sisäinen tunniste. Käytetään tukeen ja vianetsintään. |
| viestitunnukset | 10 x 36 | Joukko yksilöllisiä LINK Mobility -viestitunnuksia kullekin onnistuneelle viestille (useampia viestitunnuksia palautetaan, jos viesti ketjutetaan). Poistetaan epäonnistumisen sattuessa. |
7.4 Esimample vastauksia
Menestys
HTTP/1.1 200 OK
Sisältötyyppi: sovellus/json
Sisällön pituus: 144
Päivämäärä: torstai 15. syyskuuta 2016 klo 13 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Tässä on sama JSON-muotoiltu luettavuutta varten:
{
“vastauskoodi":0,
“vastausviesti":"Menestys",
“kertaaamp“:”2016-0915T13:20:31Z”,
“jäljitystunnus“:”f678d30879fd4adc25f2”,
“viestitunnukset":["1-4850879008"] }
Epäonnistuminen
HTTP/1.1 200 OK
Sisältötyyppi: sovellus/json
Sisällön pituus: 148
Päivämäärä: torstai 15. syyskuuta 2016 klo 13 GMT
{"responseCode":1,"responseMessage":" Virheellinen kirjautuminen tai luvaton API-käyttö","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Menestys
HTTP/1.1 200 OK
Sisältötyyppi: sovellus/json
Sisällön pituus: 144
Päivämäärä: torstai 15. syyskuuta 2016 klo 13 GMT
{"responseCode":0,"responseMessage":"Success","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Tässä on sama JSON-muotoiltu luettavuutta varten:
{
“vastauskoodi":0,
“vastausviesti":"Menestys",
“kertaaamp“:”2016-0915T13:20:31Z”,
“jäljitystunnus“:”f678d30879fd4adc25f2”,
“viestitunnukset":["1-4850879008"] }
Epäonnistuminen
HTTP/1.1 200 OK
Sisältötyyppi: sovellus/json
Sisällön pituus: 148
Päivämäärä: torstai 15. syyskuuta 2016 klo 13 GMT
{"responseCode":1,"responseMessage":" Virheellinen kirjautuminen tai luvaton API-käyttö","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Vastauskoodit
Seuraavat vastauskoodit voidaan palauttaa lähetysvastauksessa:
| Koodi | Teksti | Kuvaus |
| 0 | Menestys | Suoritettu onnistuneesti. |
| 1 | Virheellinen kirjautuminen tai luvaton API-käyttö | LINK Mobility estää väärän käyttäjänimen tai salasanan tai palveluntarjoajan. |
| 2 | Link Mobility estää kuluttajan | LINK Mobility estää kuluttajan. |
| 3 | LINK Mobility ei tarjoa toimintaa | Toiminto on estetty Palveluntarjoajalta. |
| 4 | Kuluttaja on tuntematon LINK Mobilitylle | LINK Mobility ei tunne kuluttajaa. Tai jos pyynnössä käytettiin aliasta; aliasta ei löydy. |
| 5 | Kuluttaja on estänyt tämän palvelun LINK Mobilityssa | Kuluttaja on estänyt tämän palvelun LINK Mobilityssa. |
| 6 | Alkuperäistä osoitetta ei tueta | Alkuperäistä osoitetta ei tueta. |
| 7 | Alfa-alkuperäinen osoite ei tue tiliä | Tili ei tue alfa-alkuperäistä osoitetta. |
| 8 | MSISDN-alkuperäistä osoitetta ei tueta | MSISDN-alkuperäistä osoitetta ei tueta. |
| 9 | GSM laajennettua ei tueta | GSM laajennettua ei tueta. |
| 10 | Unicodea ei tueta | Unicodea ei tueta. |
| 11 | Tilaraporttia ei tueta | Tilaraporttia ei tueta. |
| 12 | Vaadittua ominaisuutta ei tueta | Viestin lähettämiseen vaadittua kykyä (muita kuin yllä mainittuja) ei tueta. |
| 13 | Sisällöntarjoajan enimmäisrajoitusnopeus ylittyy | Palveluntarjoaja lähettää tekstiviestit LINK Mobilitylle liian nopeasti. |
| 14 | Tili ei tue protokollatunnusta | Protokollatunnusta ei tueta. |
| 15 | Viestien ketjutusraja ylitetty | Yhdistettyjen viestien määrä ylittää pyydetyn enimmäismäärän. |
| 16 | Viestiä ei voi reitittää. | LINK Mobility ei voinut reitittää viestiä. |
| 17 | Kielletty aika | Viestiä ei saa lähettää ajanjakson aikana |
| 18 | Liian pieni saldo palveluntarjoajan tilillä | Palveluntarjoaja on estetty liian alhaisen saldon vuoksi |
| 50 | Osittainen menestys | Osittainen onnistuminen lähetettäessä tekstiviesti useille vastaanottajille. |
| 99 | Sisäinen palvelinvirhe | Muu Link Mobility -virhe, ota yhteyttä LINK Mobility -tukeen saadaksesi lisätietoja. |
| 100 | Virheellinen kohdeosoite | Kohdeosoite (MSISDN tai alias) on virheellinen. |
| 102 | Virheellinen viitattu (linkitetty) tunnus | Viitetunnus on virheellinen, ehkä viitetunnus on jo käytössä, liian vanha tai tuntematon. |
| 103 | Virheellinen tilin nimi | Tilin nimi on virheellinen. |
| 105 | Virheelliset palvelun metatiedot | Palvelun metatiedot ovat virheelliset. |
| 106 | Virheellinen lähtöosoite | Alkuperäinen osoite on virheellinen. |
| 107 | Virheellinen aakkosnumeerinen lähtöosoite | Alkuperäinen aakkosnumeerinen osoite on virheellinen. |
| 108 | Virheellinen voimassaoloaika | Voimassaoloaika on virheellinen. |
| 109 | Virheellinen toimitusaika | Toimitusaika on virheellinen. |
| 110 | Virheellinen viestin sisältö/käyttäjätiedot | Käyttäjätiedot eli tekstiviesti ovat virheellisiä. |
| 111 | Virheellinen viestin pituus | Tekstiviestin pituus on virheellinen. |
| 112 | Virheellinen käyttäjätietojen otsikko | Käyttäjätietojen otsikko on virheellinen. |
| 113 | Virheellinen tietojen koodausmalli | DCS on virheellinen. |
| 114 | Virheellinen protokollatunnus | PID on virheellinen. |
| 115 | Virheelliset tilaraportin liput | Tilaraportin liput ovat virheellisiä. |
| 116 | Virheellinen TON | Alkuperäinen TON on virheellinen. |
| 117 | Virheellinen campaign nimi | Campjärjestelmän nimi on virheellinen. |
| 120 | Virheellinen ketjutettujen viestien enimmäismäärä | Yhdistettyjen viestien enimmäismäärä on virheellinen. |
| 121 | Virheellinen msisdn-alkuperäinen osoite | MSISDN-alkuperäinen osoite on virheellinen. |
| 122 | Virheellinen korrelaatiotunnus | Korrelaatiotunnus on virheellinen. |
8. Valinnaiset ominaisuudet
8.1 MSISDN-korjaus
MSISDN-korjaus on valinnainen ominaisuus, jonka LINK Mobility -tuki voi pyynnöstä ottaa käyttöön.
Tämä ominaisuus korjaa kohdeosoitteet ja kohdistaa ne vaadittuun E.164-muotoon. Muotokorjauksen lisäksi järjestelmä voi myös suorittaa markkinakohtaisia toimintoja, kuten kääntää kansainväliset ranskalaiset numerot korjaamaan DOM-TOM (départements et territoires d'outre-mer) -numeroita tarvittaessa.
Alla on joukko exampvähemmän korjauksia:
| Lähetetty kohdeosoite | Korjattu kohdeosoite |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (ranskalainen numero käännetty DOM-TOM-numeroksi) |
Lisäksi on mahdollista sallia kansalliset puhelinnumerot valituille markkinoille. Kun tämä ominaisuus on käytössä, kaikki muiden markkinoiden kansainväliset numerot on lähetettävä alkumerkillä "+" niiden erottamiseksi valituista markkinoista.
Alla on useita exampkorjauksista, jotka on tehty käytettäessä Ruotsia (maakoodi 46) kansallisten numeroiden oletusmarkkinana.
| Lähetetty kohdeosoite | Korjattu kohdeosoite |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Virheellinen, koska +-merkki puuttuu |
Huomaa, että LINK Mobility käyttää korjattua MSISDN-numeroa ja se palautetaan toimitusraporteissa.
Ota yhteyttä LINK Mobility -tukeen saadaksesi lisätietoja.
8.2 Merkkien vaihto
Merkkien korvaaminen on valinnainen ominaisuus, jonka LINK Mobility -tuki voi tarvittaessa ottaa käyttöön.
Tämä ominaisuus kääntää muut kuin GSM-aakkosten merkit käyttäjätiedoissa (SMS-teksti) vastaaviksi GSM-aakkosten merkeiksi, kun DCS on asetettu tilaan "GSM" (17). esimample "Seqüência de teste em Português" käännetään "Seqüencia de teste em Portugues".
9. Toimitusraportit
Palveluntarjoaja voi pyynnöstä pyytää tekstiviestien toimitusraportteja tai toimitusilmoituksia lähetetyistä MT-viesteistä. Nämä raportit laukeavat Operaattorin SMSC:ssä, kun MT-sanoma joko toimitetaan kohdekuluttajalle tai poistetaan, esim. vanhentunut tai jostain syystä ei reititetä.
Palveluntarjoajalle raportoidaan vain tekstiviestin lopullinen tila eli toimitettu tai poistettu. Vain yksi raportti MT-sanomaa kohti luodaan. Kun tila on poistettu, syykoodi saattaa olla voimassa. Tämä syykoodi määrittää syyn, miksi tekstiviestiä ei toimitettu.
Raportit reititetään LINK Mobilityn kautta ja lähetetään palveluntarjoajalle HTTP-protokollaa käyttäen.
Raporttien vastaanottamiseksi Palveluntarjoajan on otettava käyttöön esimampJava Servlet- tai ASP.NET-sivu. Molemmat vastaanottavat HTTP GET- tai POST-pyynnöt.
Parametrit
Pyyntö sisältää seuraavat parametrit:
| Parametri | Tyyppi | M/O/I* | Oletusarvo | Max pituus | Kuvaus |
| Viestitunnus | merkkijono | M | – | 22 | Sen MT-sanoman viestitunnus, jota tämä raportti vastaa. |
| DestinationAddress | merkkijono | M | – | 40 | Kuluttajan MSISDN eli alkuperäisen MT-viestin kohdeosoite. |
| StatusCode | kokonaisluku | M | 1 | Tilakoodi ilmaisee MT-viestin tilan. Käytettävissä olevat tilakoodit ovat: 0 – Toimitettu 2 – Poistettu (syykoodi pätee) |
|
| AikaStamp | merkkijono | M | – | 20 | Aika, joka osoittaa, milloin LINK Mobility vastaanotti toimitusraportin. Aikavyöhykeamp on CET tai CEST (EU:lle määritelty kesäaika). Muoto: vvvvKKpp HH:mm:ss. |
| Operaattori | merkkijono | M | – | 100 | SMS-viestiä lähetettäessä käytetyn Operaattorin nimi tai tekstiviestiä lähetettäessä käytetyn tilin nimi. LINK Mobility -tuki tarjoaa luettelon käytettävissä olevista operaattoreista. |
| ReasonCode | kokonaisluku | O | – | 3 | Syykoodi kertoo, miksi viesti päätyi tilaan poistettu. Käytettävissä olevat syykoodit ovat: 100 – Vanhentunut 101 – Hylätty 102 – Muotoiluvirhe 103 – Muu virhe 110 – Tilaaja tuntematon 111 – Tilaajakielto 112 – Tilaajaa ei ole varattu 113 – Tilaaja ei tavoitettavissa 120 – SMSC-virhe 121 – SMSC-ruuhkat 122 – SMSC-roaming 130 – Luurivirhe 131 – Luurin muisti ylitetty Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| OperatorTimeStamp | merkkijono | O | – | 20 | Aika, joka ilmaisee, milloin raportti laukaistiin operaattorin SMSC:ssä (jos operaattori tarjoaa). Aikavyöhykeamp on CET tai CEST (EU:lle määritelty kesäaika). Muoto: vvvvKKpp HH:mm:ss. |
| Tilateksti | merkkijono | O | – | 255 | Paikkamerkki lisätiedoille Operaattorilta, esim. selkeä tekstikuvaus tilasta/syystä. Käyttäytyminen voi vaihdella operaattoriintegraatioiden mukaan. |
| CorrelationId | merkkijono | O | – | 100 | SendRequest- tai SendTextRequestissä annettu korrelaatiotunnus. |
| OperatorNetworkCode | kokonaisluku | O | – | 6 | Operaattorin mobiiliverkkokoodi (MCC + MNC). |
* M = Pakollinen, O = Valinnainen, I = Ohitettu.
Palveluntarjoajan on annettava kohde LINK Mobilitylle URL toimitusraportteja varten (valinnaisesti mukaan lukien tunnistetiedot HTTP-perustodennusta varten). Palveluntarjoaja voi valita käytettävän ensisijaisen HTTP-menetelmän:
HTTP POST (suositus)
HTTP GET.
Example käyttäen HTTP GET:tä (toimitettu onnistuneesti):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Example käyttäen HTTP GET:tä (ei toimitettu, operaattori on toimittanut timestamp tapahtumaa varten):
Parametrit ovat URL koodattu.
Merkkikoodaus:
Palveluntarjoaja voi valita, mitä ensisijaista merkkikoodausta käyttää:
UTF-8 (suositus)
ISO-8859-1.
9.1 Palveluntarjoajan kuittaus
Palveluntarjoajan tulee kuitata jokainen toimitusraportti. Kuittaus voi olla positiivinen eli toimitusraportti onnistuneesti vastaanotettu tai negatiivinen eli epäonnistunut.
Huomaa: LINK Mobilityssä on 30 sekunnin lukuaikakatkaisu toimitusraporttien kuittauksille. Aikakatkaisu käynnistää toimituksen uudelleenyrityksen (jos uudelleenyritys on käytössä) tai toimituksen peruuttamisen (jos uudelleenyritys ei ole käytössä). Tämä tarkoittaa, että palveluntarjoajan sovelluksen on varmistettava nopeat vasteajat erityisesti suuren kuormituksen aikana.
On erittäin suositeltavaa hyväksyä toimitusraportti LINK Mobilitylle ennen sen käsittelyä.
Positiivisen ja negatiivisen kuittauksen sääntö on kuvattu seuraavasti:
Positiivinen kuittaus, ACK, toimitusraportti toimitettu:
HTTP 200 -alueen vastauskoodi yhdessä seuraavan XML-muotoisen sisällön kanssa:
Negatiivinen kuittaus, NAK, toimitusraporttia ei toimitettu:
Kaikki muut vastaukset kuin myönteinen kuittaus, esimample, negatiivisen kuittauksen laukaisee mikä tahansa HTTP-virhekoodi tai seuraava XML-sisältö:
XML-sisältöä voidaan käyttää LINK Mobility -uudelleenyritysmekanismin ohjaamiseen. NAK aiheuttaa uudelleenyrityksen, jos se on käytössä. Palveluntarjoajille, joita ei ole määritetty uudelleenyritysmekanismia varten, XML-sisältö on valinnainen.
Alla on HTTP POST -pyyntö ja vastaus esimampPalveluntarjoajalle toimitetusta toimitusraportista:
HTTP-pyyntö:
POST /context/app HTTP/1.1
Sisältötyyppi: application / x-www-form-urlkoodattu;merkkiset=utf-8
Isäntä: palvelin:portti
Sisältö-pituus: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP-vastaus:
HTTP/1.1 200 OK
Sisältötyyppi: teksti/tavallinen
9.2 Yritä uudelleen
LINK Mobility -järjestelmä voi tehdä uudelleenyrityksiä epäonnistuneille eli kuitattamattomille toimitusraporttien toimituksille. Palveluntarjoaja voi valita haluamasi uudelleenyrityskäyttäytymisen:
Ei uudelleenyritystä (oletus) – viesti hylätään, jos yhteysyritys epäonnistuu, lukuaikakatkaisu tai HTTP-virhekoodi.
Yritä uudelleen – Viesti lähetetään uudelleen kaikentyyppisten yhteysongelmien, lukuaikakatkaisun tai negatiivisen kuittauksen yhteydessä.
Kun NAK:n uudelleenyritys on käytössä, on tärkeää ymmärtää, mitkä skenaariot luovat uudelleenyrityksen LINK Mobilitysta ja kuinka uudelleenyritys toimii. Jokaisella Palveluntarjoajalla on oma uudelleenyritysjononsa, jossa viestit järjestetään sanomaajan mukaanamp. Link Mobility yrittää aina toimittaa ensin vanhemmat viestit, vaikka palveluntarjoajalle toimitettujen viestien yksittäistä järjestystä ei taata. Pääsyy viestien hylkäämiseen uudelleenyritysjonosta on toinen kahdesta syystä: joko sanoman TTL vanhenee tai (teoreettisesti) uudelleenyritysjono täyttyy. TTL on operaattori- ja tiliriippuvainen, eli se voi vaihdella operaattorin ja/tai viestin tyypin mukaan, esim. premium-tekstiviesti tai normaalihintainen tekstiviesti.
Palveluntarjoajan, jonka uudelleenyritys on käytössä, on tarkistettava MT-viestin yksilöllinen tunnus varmistaakseen, ettei viestiä ole jo vastaanotettu.
Palveluntarjoajan on tärkeää noudattaa näitä yksinkertaisia sääntöjä, kun toimitusraportin käsittelyssä tapahtuu virhe, jos virheen syy on: Tilapäinen, esim. tietokanta ei ole käytettävissä, tulee palauttaa NAK. LINK Mobility lähettää viestin uudelleen.
Pysyvä ja uudelleenyritys aiheuttavat todennäköisesti samanlaisen ongelman, ACK tulee palauttaa. esimample, kun viestiä ei voitu jäsentää oikein tai se aiheutti odottamattoman ajonaikaisen virheen.
Toimimalla vastaavalla tavalla varmistetaan, ettei toimitusraportin toistuvan uudelleenlähetyksen vuoksi aiheudu esteitä tai suorituskyvyn heikkenemistä.
10. Käyttöönottovinkkejä
1. On mahdollista käyttää omaa web selain lähettää pyyntöjä API:lle. Näin palveluiden tutkiminen ja arviointi on erittäin helppoa ilman kehitystyökaluja.
2. Chromea tai Firefoxia suositellaan yhdessä laajennuksen, kuten JSON, kanssaView näyttääkseen kauniisti muotoillun JSONin.
3. Olemme käyttäneet SoapUI:ta POST:n, Basic Authenticationin ja raaka HTTP-pyyntö- ja vastausviestien tarkastamiseen.
4. CURL työkalu on hyödyllinen POST-pyyntöjen lähettämiseen perustodennuksen kanssa. Katso esimample alla.
curl LÄHETÄ \
-H “Sisältötyyppi: hakemus/x-www-lomake-urlkoodattu" \
-H “Valtuutus: Perus am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hei+Maailma%21”
_______________
Henkilökohtaisen viestinnän muuttaminen
Asiakirjat / Resurssit
 |
LINK Mobility Implementation Guide REST API SMS [pdfKäyttöopas Mobility Implementation Guide REST API SMS, Mobility, Implementation Guide REST API SMS, REST API SMS, API SMS, SMS |
