LINK Mobilitātes ieviešanas rokasgrāmata REST API SMS
LINK Mobility nodrošina pakalpojumu ziņojumu piegādei, mikromaksājumiem un uz atrašanās vietu balstītiem pakalpojumiem. Platforma darbojas kā caurspīdīgs, baltā marķējuma satura ieguvējs un darījumu maršrutētājs starp pakalpojumu sniedzējiem un operatoriem.
LINK Mobility nodrošina RESTful API, ko var izmantot, lai piekļūtu LINK Mobility pakalpojumiem, piemēram, īsziņu sūtīšanai. Šī API ir izstrādāta tā, lai tā būtu viegli lietojama un saderīga ar visām mūsdienu valodām un ietvariem. Izmantojot jūsu izvēlēto valodu, jūsu lietojumprogramma var izmantot Link Mobility REST API, lai ieviestu jaudīgas ziņojumapmaiņas un maksājumu iespējas
© LINK Mobility, 10. gada 2021. marts
Juridiskā informācija
Šajā dokumentā sniegtā informācija ir vienīgais Netsize īpašums un autortiesības. Tas ir konfidenciāls un paredzēts tikai informatīvai lietošanai. Tas nav saistošs un var tikt mainīts bez brīdinājuma. Jebkura neatļauta izpaušana vai izmantošana tiek uzskatīta par nelikumīgu.
Netsize™ un linkmobility™ aizsargā Francijas, EEK un starptautiskie intelektuālā īpašuma likumi.
Visas pārējās citētās preču zīmes ir to attiecīgo īpašnieku vienīgais īpašums.
Nekas no šeit ietvertā nevar tikt interpretēts kā tāds, kas piešķir licenci vai tiesības saskaņā ar Netsize patentu, autortiesībām vai preču zīmi.
NETSIZE
Société anonyme au capital de 5 478 070 eiro
Siège social :62, avenue Emile Zola92100 Boulogne – Francija
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Dokumenta apjoms
Šajā dokumentā ir aprakstīts, kā pakalpojumu sniedzējs īsziņām izmanto LINK Mobility REST API. Tas ir paredzēts tehniskajiem arhitektiem un dizaineriem, kuri īsteno Pakalpojumu sniedzēja pakalpojumus.
1. Pamata lietošana
Nosūtīt SMS ir ļoti vienkārši. Jūs nosūtāt HTTP pieprasījumu uz LINK Mobility, ko var izpildīt, izmantojot tikai a web pārlūkprogramma.
2. Functional Overview
Sistēma LINK Mobility nodrošina šādas pamata funkcionalitātes īsziņām:
Mobilo sakaru terminētu (MT) SMS īsziņu sūtīšana, piemēram, teksta vai bināro (piemēram, WAP Push) maksas un standarta tarifa ziņojumu sūtīšana.
Piegādes atskaišu saņemšana par iesniegtajiem MT ziņojumiem.
Mobilās izcelsmes (MO) SMS īsziņu saņemšana, paaugstināta un standarta likme.
SMS REST API ir paredzēta standarta ātruma MT SMS īsziņu nosūtīšanai.
API nosūta visas SMS ziņas asinhroni, iespējot tādas funkcijas kā:
“Uguns un aizmirsti” – Pakalpojuma sniedzējs vēlas prognozējamākus atbildes laikus un nevēlas gaidīt rezultātu no Operatora.
Mēģiniet vēlreiz — LINK Mobility atkārtoti nosūtīs ziņojumu, ja operatoram radīsies īslaicīgas problēmas.
2.1 SMS īsziņas nosūtīšana
Pakalpojumu sniedzējs Netsize Consumer
- Nosūtiet MT ziņojumu
- Atgriezties ziņojuma ID
- Nosūtiet SMS ziņu
- Piegādājiet piegādes atskaiti
- Nosūtiet piegādes atskaiti
SMS īsziņu nosūtīšanas pamatplūsma ir aprakstīta šādi:
Pakalpojumu sniedzējs izsaka pieprasījumu nosūtīt SMS īsziņu adresātam, izmantojot sistēmu LINK Mobility.
Pakalpojumu sniedzējam tiek atgriezts ziņojuma ID. Šo ID var izmantot, piemēram, ziņojuma korelēšanai ar pareizo piegādes atskaiti.
LINK Mobility apstrādā maršrutēšanu un piegādā SMS īsziņu adresētajam Patērētājam.
Piegādes atskaite tiek aktivizēta, piemēram, kad SMS ziņa tiek piegādāta Patērētāja ierīcē.
Piegādes atskaite tiek nosūtīta Pakalpojumu sniedzējam. Pārskatā ir tas pats ziņojuma ID, kas tika atgriezts 2. darbībā.
Alternatīva plūsma: nederīgs pieprasījums
Ja pieprasījumā norādītie parametri vai lietotāja akreditācijas dati ir nederīgi, Pakalpojumu sniedzējam tiek atgriezta kļūda. Kļūda norāda noraidīšanas iemeslu un plūsma beidzas. Ziņojumu ID netiek atgriezti.
3. Galapunkts
SMS resursam var piekļūt, izmantojot ceļu:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Savienojuma drošības nolūkos LINK Mobility REST API ir pieejams tikai, izmantojot HTTPS.
Saites mobilitātes servera sertifikātu paraksta Thawte Server CA.
4. Operācijas
SMS pakalpojums nodrošina šādas darbības:
| Vārds | Ceļš |
| Sūtīt | /restapi/v1/sms/send |
4.1 Sūtīt
Sūtīšanas darbība tiek izmantota, lai nosūtītu SMS vienam adresātam.
Šī darbība ir paredzēta gan pamata, gan pieredzējušiem lietotājiem. Vienkāršākajā gadījumā SMS piegādei ir nepieciešama tikai galamērķa adrese un ziņas teksts. LINK Mobility noteiks datu kodēšanas shēmu un, ja nepieciešams, veiks automātisku ziņojuma savienošanu vairākās ziņojuma daļās.
Uzlabotai lietošanai Pakalpojumu sniedzējs var izmantot izvēles parametrus, lai pilnībā kontrolētu ziņojuma formatējumu, tostarp lietotāja datu galveni.
Pakalpojumu sniedzējs var nosūtīt sasaistītus ziņojumus, taču lietotāja datu un lietotāja datu galvenes sagatavošana jāveic Pakalpojumu sniedzējam un ziņojums jānosūta, izmantojot vairākus sūtīšanas pieprasījumus uz LINK Mobility.
5. Autentifikācija
Lietotājvārds un parole tiek iesniegti katrā pieprasījumā, izmantojot HTTP pamata autentifikācijas shēmu.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Akreditācijas dati tiek nosūtīti HTTP pieprasījuma galvenē Autorizācija. Klients izveido galvenes lauku, kā aprakstīts šeit:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Piemēram,ampja lietotājvārds ir john un changeme ir parole, tad autorizācijas galvene ir:
Autorizācija: Pamata am9objpjaGFuZ2VtZSA=
Lietotājvārdu un paroli var iesniegt kā pieprasījuma parametrus. Tas ir ieteicams tikai tiem klientiem, kuri neatbalsta pamata autentifikāciju.
6. Pieprasījuma iesniegšana
6.1. Vaicājuma virkne
Pieprasījuma parametri tiek iesniegti kā vaicājuma virkne, kas satur nosaukumu/vērtību pārus. Vaicājuma virkne ir kodēta, izmantojot procentuālo kodējumu (URL kodējums).
http://www.w3schools.com/tags/ref_urlencode.asp
Piemēram,ample, Sveika pasaule! ir kodēts kā Hello+World%21.
6.2. Obligātie pieprasījuma parametri
| Vārds | Maksimālais garums | Apraksts |
| galamērķa adrese | 40 | MSISDN, uz kuru jānosūta īsziņa, sākot ar valsts kodu. Piemamptālr .: 46123456789. Dažos tirgos (kur patērētāja MSISDN ir jābūt apslēptam) šī vērtība var būt arī burtciparu aizstājvārds ar prefiksu “#”. |
| ziņaTeksts | 1600 | SMS ziņas saturs. |
6.3. Izvēles pieprasījuma parametri (papildu lietošanai)
| Vārds | Maksimālais garums | Apraksts |
| izcelsmes adrese | 16 | Izejošās īsziņas sākuma adrese. Sākotnējās adreses veidu nosaka parametrs iniciatorTON. Īsā numura maksimālais garums ir 16. Burtu un ciparu sūtītājs ir ierobežots ar GSM noklusējuma alfabētu ar maksimālo garumu 11 rakstzīmes. MSISDN sūtītāja maksimālais garums ir 15 (izmantojot to pašu formātu kā elements destinationAddress). Var izlaist, ja sistēma atlasa originatingAddress un originatingTON. Šī funkcija ir atkarīga no tirgus un konfigurācijas. Darbība var atšķirties atkarībā no operatora integrācijas. |
| iniciatorsTON | 1 | Sākotnējās adreses numura veids (TON): 0 – īsais numurs 1 — burtu un ciparu (maksimālais garums 11) 2 — MSISDN Var izlaist, ja sistēma atlasīs adresi originatingAddress un originatingTON. Šī funkcija ir atkarīga no tirgus un konfigurācijas. Darbība var atšķirties atkarībā no operatora integrācijas. |
| userDataHeader | 280 | Lietotāja datu galvenē kopā ar lietotāja datiem var būt līdz 140, ti, 280 oktetiem, ja tie ir kodēti ar heksadeci. Šis parametrs vienmēr ir hex-kodēts. |
| DCS | 3 | Datu kodēšanas shēma. Darbība var atšķirties atkarībā no operatora integrācijas. |
| PID | 3 | Protokola ID. Darbība var atšķirties atkarībā no operatora integrācijas. |
| relatīvaisValidityTime | 6 | Relatīvais derīguma laiks sekundēs (attiecībā pret iesniegšanas laiku vietnē LINK Mobility). Maksimālā vērtība ir 604800 7 (48 dienas), un noklusējuma vērtība ir XNUMX stundas. Darbība var atšķirties atkarībā no operatora integrācijas. |
| piegādes laiks | 20 | Vislaicīgākaisamp kad jāpiegādā SMS ziņa (aizkavēta piegādes laiks). Skatiet sadaļu par datuma un laika formātu. |
| statusReportFlags | 1 | Piegādāt atskaites pieprasījumu: 0 — nav piegādes atskaites (noklusējums) 1 — pieprasīta piegādes atskaite 9 — pieprasīta servera piegādes atskaite (LINK Mobility ziņojumu nepārsūta pakalpojumu sniedzējam, bet padara to pieejamu pārskatos utt.) |
| campaignName | 50 | LINK mobilitātes darījumi ir tagged ar šo vārdu. To izmanto, lai grupētu darījumus saites mobilitātes pārskatos. |
| maxConcatenatedMessages | 1 | Vērtība no 1 līdz 10, kas nosaka atļauto sasaistīto ziņojumu skaitu. Noklusējums ir 3. |
| korelācijasId | 100 | Pakalpojumu sniedzēja nodrošinātais ID, kas tiks atspoguļots piegādes pārskatā. |
| lietotājvārds | 100 | Tiek nodrošināta kā alternatīva HTTP pamata autentifikācijai. |
| parole | 100 | Tiek nodrošināta kā alternatīva HTTP pamata autentifikācijai. |
6.4. HTTP pieprasījuma metodes
Maksimālai savietojamībai API atbalsta gan HTTP GET, gan POST pieprasījuma metodes. Citas HTTP metodes nav atļautas.
6.4.1. IEGŪT
Kodētā vaicājuma virkne tiek pievienota URL.
IEGŪT
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Sveiki+Pasaule%21
Autorizācija: Pamata am9objpjaGFuZ2VtZSA=
6.4.2 POST
Kodētā vaicājuma virkne tiek iesniegta HTTP pieprasījuma ziņojuma pamattekstā. Satura veids ir Application/x-www-form-urlkodēti.
POSTĪT https://europe.ipx.com/restapi/v1/sms/send
Saimnieks: europe.ipx.com
Satura tips: application / x-www-form-urlkodēti
Autorizācija: Pamata am9objpjaGFuZ2VtZSA=
Satura garums: 57
destinationAddress=46123456789&messageText=Sveiki+Pasaule%21
6.5. Datums un laiks
REST API parametri, kas attēlo datumu un laiku, vienmēr ir UTC laika joslā (koordinētais universālais laiks). Timestamps tiek attēloti kā virkne ar šo precīzu formātu:
2017-04-25T23:20:50Z
Tas ir 20 minūtes un 50 sekundes pēc 23. gada 25. aprīļa 2017. stundas pēc UTC.
7. Atbildes ziņojums
Pēc pieprasījuma ziņojuma saņemšanas un interpretācijas API atbild ar HTTP atbildes ziņojumu.
7.1 HTTP statusa kods
REST API apstrādātajiem pieprasījumiem vienmēr atgriež HTTP statusa kodu 200 OK. Ziņojuma pamattekstā ir ietverts parametra atbildes kods, ko izmanto, lai noteiktu precīzu rezultātu.
7.2. Ziņojuma pamatteksts
Ziņojuma pamattekstu veido JSON, kas apraksta pieprasījuma iznākumu.
http://json.org/
Link Mobility JSON atbilst Google JSON stila rokasgrāmatai.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3. Atbildes parametri
| Vārds | Maksimālais garums | Apraksts |
| atbildes kods | 3 | 0 norāda uz veiksmīgu darījumu. |
| atbildes ziņojums | 255 | Atbildes teksta apraksts, piemēram, kļūdas teksts. |
| reizesamp | 20 | Datums un laiks, kad LINK Mobility apstrādāja pieprasījumu. (Skatiet sadaļu datuma/laika formāts). |
| traceID | 36 | Saites mobilitātes iekšējais identifikators. Izmanto atbalstam un problēmu novēršanai. |
| ziņojumu ID | 10 x 36 | LINK Mobility unikālo ziņojumu ID masīvs katram veiksmīgam ziņojumam (ja ziņojums ir savienots, tiek atgriezti vairāki ziņojumu ID). Neveiksmes gadījumā izlaists. |
7.4 Piemample atbildes
Panākumi
HTTP/1.1 200 OK
Satura veids: lietojumprogramma/json
Satura garums: 144
Datums: ceturtdiena, 15. gada 2016. septembris, 13:20:31 GMT
{"responseCode":0,"responseMessage":"Veiksme","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Šeit ir tas pats JSON, kas formatēts lasāmībai:
{
“atbildes kods":0,
“atbildes ziņojums":"Veiksme",
“reizesamp“:”2016-0915T13:20:31Z”,
“traceID“:”f678d30879fd4adc25f2”,
“ziņojumu ID“:[“1-4850879008”] }
Neveiksme
HTTP/1.1 200 OK
Satura veids: lietojumprogramma/json
Satura garums: 148
Datums: ceturtdiena, 15. gada 2016. septembris, 13:20:31 GMT
{"responseCode":1,"responseMessage":" Nederīga pieteikšanās vai neautorizēts API lietojums","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Panākumi
HTTP/1.1 200 OK
Satura veids: lietojumprogramma/json
Satura garums: 144
Datums: ceturtdiena, 15. gada 2016. septembris, 13:20:31 GMT
{"responseCode":0,"responseMessage":"Veiksme","timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Šeit ir tas pats JSON, kas formatēts lasāmībai:
{
“atbildes kods":0,
“atbildes ziņojums":"Veiksme",
“reizesamp“:”2016-0915T13:20:31Z”,
“traceID“:”f678d30879fd4adc25f2”,
“ziņojumu ID“:[“1-4850879008”] }
Neveiksme
HTTP/1.1 200 OK
Satura veids: lietojumprogramma/json
Satura garums: 148
Datums: ceturtdiena, 15. gada 2016. septembris, 13:20:31 GMT
{"responseCode":1,"responseMessage":" Nederīga pieteikšanās vai neautorizēts API lietojums","timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5. Atbildes kodi
Sūtīšanas atbildē var atgriezt šādus atbildes kodus:
| Kods | Teksts | Apraksts |
| 0 | Panākumi | Veiksmīgi izpildīts. |
| 1 | Nederīga pieteikšanās vai neautorizēts API lietojums | Nepareizu lietotājvārdu vai paroli vai pakalpojumu sniedzēju liedz LINK Mobility. |
| 2 | Patērētāju bloķē Link Mobility | LINK Mobility bloķē patērētāju. |
| 3 | Darbību nenodrošina LINK Mobility | Pakalpojumu sniedzējam darbība ir bloķēta. |
| 4 | LINK Mobility patērētājs nav zināms | LINK Mobility patērētājs nav zināms. Vai arī pieprasījumā tika izmantots aizstājvārds; aizstājvārds nav atrasts. |
| 5 | Patērētājs ir bloķējis šo pakalpojumu pakalpojumā LINK Mobility | Patērētājs ir bloķējis šo pakalpojumu pakalpojumā LINK Mobility. |
| 6 | Sākotnējā adrese netiek atbalstīta | Sākotnējā adrese netiek atbalstīta. |
| 7 | Konts neatbalsta alfa izcelsmes adresi | Konts neatbalsta alfa izcelsmes adresi. |
| 8 | MSISDN izcelsmes adrese netiek atbalstīta | MSISDN izcelsmes adrese netiek atbalstīta. |
| 9 | GSM paplašinātais tīkls netiek atbalstīts | GSM paplašinātais tīkls netiek atbalstīts. |
| 10 | Unicode netiek atbalstīts | Unicode netiek atbalstīts. |
| 11 | Statusa pārskats netiek atbalstīts | Statusa pārskats netiek atbalstīts. |
| 12 | Nepieciešamā iespēja netiek atbalstīta | Nepieciešamā iespēja (izņemot iepriekš minēto) ziņojuma nosūtīšanai netiek atbalstīta. |
| 13 | Satura nodrošinātāja maksimālais ierobežošanas ātrums ir pārsniegts | Pakalpojumu sniedzējs pārāk ātri sūta SMS ziņas uz LINK Mobility. |
| 14 | Konts neatbalsta protokola ID | Protokola ID netiek atbalstīts. |
| 15 | Pārsniegts ziņojumu savienošanas ierobežojums | Savienoto ziņojumu skaits pārsniedz maksimālo pieprasīto skaitu. |
| 16 | Nevar nosūtīt ziņojumu. | LINK Mobilitāte nevarēja novirzīt ziņojumu. |
| 17 | Aizliegtais laika posms | Nav atļauts sūtīt ziņojumu laika periodā |
| 18 | Pārāk mazs atlikums pakalpojumu sniedzēja kontā | Pakalpojumu sniedzējs ir bloķēts pārāk zema bilances dēļ |
| 50 | Daļēji panākumi | Daļēji panākumi, nosūtot īsziņu vairākiem adresātiem. |
| 99 | Iekšējā servera kļūda | Cita saites mobilitātes kļūda. Lai iegūtu papildinformāciju, sazinieties ar LINK Mobility atbalsta dienestu. |
| 100 | Nederīga galamērķa adrese | Galamērķa adrese (MSISDN vai aizstājvārds) nav derīga. |
| 102 | Nederīgs atsauces (saistītais) ID | Atsauces ID nav derīgs, iespējams, atsauces ID jau ir izmantots, pārāk vecs vai nezināms. |
| 103 | Nederīgs konta nosaukums | Konta nosaukums nav derīgs. |
| 105 | Nederīgi pakalpojuma metadati | Pakalpojuma metadati nav derīgi. |
| 106 | Nederīga izcelsmes adrese | Sākotnējā adrese nav derīga. |
| 107 | Nederīga burtciparu izcelsmes adrese | Burtciparu izcelsmes adrese nav derīga. |
| 108 | Nederīgs derīguma laiks | Derīguma laiks nav derīgs. |
| 109 | Nederīgs piegādes laiks | Piegādes laiks nav derīgs. |
| 110 | Nederīgs ziņojuma saturs/lietotāja dati | Lietotāja dati, ti, SMS ziņa, nav derīgi. |
| 111 | Nederīgs ziņojuma garums | Īsziņas garums nav derīgs. |
| 112 | Nederīga lietotāja datu galvene | Lietotāja datu galvene nav derīga. |
| 113 | Nederīga datu kodēšanas shēma | DCS nav derīgs. |
| 114 | Nederīgs protokola ID | PID nav derīgs. |
| 115 | Nederīgi statusa ziņojuma karodziņi | Statusa ziņojuma karodziņi nav derīgi. |
| 116 | Nederīgs TON | Sākotnējais TON nav derīgs. |
| 117 | Nederīgs campaign nosaukums | CampAignes nosaukums nav derīgs. |
| 120 | Nederīgs maksimālais sasaistīto ziņojumu skaita ierobežojums | Maksimālais savienoto ziņojumu skaits nav derīgs. |
| 121 | Nederīga msisdn izcelsmes adrese | MSISDN izcelsmes adrese nav derīga. |
| 122 | Nederīgs korelācijas ID | Korelācijas ID nav derīgs. |
8. Izvēles funkcijas
8.1 MSISDN labojums
MSISDN labošana ir izvēles līdzeklis, ko pēc pieprasījuma var iespējot LINK mobilitātes atbalsts.
Šī funkcija labos galamērķa adreses un līdzinās tās vajadzīgajam E.164 formātam. Papildus formāta korekcijai sistēma var veikt arī tirgus specifiskas funkcijas, piemēram, starptautisko franču numuru tulkošanu, lai vajadzības gadījumā labotu DOM-TOM (départements et territoires d'outre-mer) numurus.
Zemāk ir vairāki exampmazāk labojumu:
| Iesniegtā galamērķa adrese | Izlabota galamērķa adrese |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 XNUMX XNUMX XNUMX | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Francijas numurs tulkots DOM-TOM numurā) |
Turklāt ir iespējams atļaut valsts tālruņu numurus atlasītajam tirgum. Kad šī funkcija ir iespējota, jebkuri starptautiskie numuri citiem tirgiem ir jānosūta ar sākotnējo zīmi "+", lai tos atšķirtu no atlasītā tirgus.
Zemāk ir vairāki bijušieamplabojumi, kas veikti, izmantojot Zviedriju (valsts kods 46) kā noklusējuma tirgu nacionālajiem numuriem.
| Iesniegtā galamērķa adrese | Izlabota galamērķa adrese |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 XNUMX XNUMX XNUMX | 46702233445 |
| +458022334455 XNUMX XNUMX XNUMX | 458022334455 |
| 45802233445 | Nederīgs, jo trūkst zīmes “+”. |
Ņemiet vērā, ka LINK Mobility izmantos laboto MSISDN un tas tiks atgriezts piegādes pārskatos.
Lai iegūtu papildinformāciju, lūdzu, sazinieties ar LINK mobilitātes atbalstu.
8.2. Rakstzīmju nomaiņa
Rakstzīmju aizstāšana ir izvēles funkcija, kuru pēc pieprasījuma var iespējot LINK mobilitātes atbalsts.
Šī funkcija pārtulkos ne GSM alfabēta rakstzīmes lietotāja datos (SMS tekstā) par līdzvērtīgām GSM alfabēta rakstzīmēm, ja DCS ir iestatīts uz “GSM” (17). Piemēram,ample “Seqüência de teste em Português” tiks tulkots kā “Seqüencia de teste em Portugues”.
9. Piegādes atskaites
Pakalpojumu sniedzējs, ja tas ir nodrošināts, var pieprasīt SMS ziņojumu piegādes atskaites vai piegādes paziņojumus par nosūtītajām MT ziņām. Šie ziņojumi tiek aktivizēti operatora SMSC, kad MT ziņojums tiek piegādāts mērķa patērētājam vai tiek dzēsts, piemēram, beidzies derīguma termiņš vai kādu iemeslu dēļ tas nav maršrutējams.
Pakalpojumu sniedzējam tiek paziņots tikai SMS ziņojuma galīgais statuss, ti, piegādāts vai dzēsts. Katram MT ziņojumam tiek ģenerēts tikai viens ziņojums. Ja statuss ir dzēsts, var tikt piemērots iemesla kods. Šis iemesla kods norāda iemeslu, kāpēc īsziņa netiek piegādāta.
Pārskati tiek maršrutēti caur LINK Mobility un nosūtīti pakalpojumu sniedzējam, izmantojot HTTP protokolu.
Lai saņemtu atskaites, Pakalpojumu sniedzējam ir jāievieš piemampJava Servlet vai ASP.NET lapa. Abi saņem HTTP GET vai POST pieprasījumus.
Parametri
Pieprasījums ietver šādus parametrus:
| Parametrs | Tips | M/O/I* | Noklusējuma vērtība | Maksimālais garums | Apraksts |
| Ziņojuma ID | virkne | M | – | 22 | Ziņojuma ID MT ziņojumam, kuram atbilst šī atskaite. |
| Galamērķa adrese | virkne | M | – | 40 | Patērētāja MSISDN, ti, sākotnējā MT ziņojuma galamērķa adrese. |
| Statusa kods | vesels skaitlis | M | 1 | Statusa kods norāda MT ziņojuma statusu. Piemērojamie statusa kodi ir: 0 – piegādāts 2 — dzēsts (ir spēkā iemesla kods) |
|
| TimeStamp | virkne | M | – | 20 | Laiks, kas norāda, kad LINK Mobility saņēma piegādes atskaiti. Laika josla laika ziņāamp ir CET vai CEST (ar vasaras laiku, kā noteikts ES). Formāts: ggggMMdd HH:mm:ss. |
| Operators | virkne | M | – | 100 | Operatora vārds, kas izmantots, nosūtot SMS īsziņu, vai konta nosaukums, kas izmantots, nosūtot SMS īsziņu. Pieejamo operatoru sarakstu nodrošina LINK Mobility atbalsts. |
| Iemesla kods | vesels skaitlis | O | – | 3 | Iemesla kods norāda, kāpēc ziņojuma statuss ir dzēsts. Piemērojamie iemeslu kodi ir: 100 – beidzies derīguma termiņš 101 – Noraidīts 102 — formāta kļūda 103 — cita kļūda 110 — abonents nav zināms 111. Abonentam ir liegts 112 — abonents nav nodrošināts 113 — abonents nav pieejams 120 – SMSC kļūme 121 – SMSC sastrēgumi 122 – SMSC viesabonēšana 130 – klausules kļūda 131 – Pārsniegta klausules atmiņa Darbība var atšķirties atkarībā no operatora integrācijas. |
| OperatorTimeStamp | virkne | O | – | 20 | Laiks, kas norāda, kad ziņojums tika aktivizēts Operatora SMSC (ja to nodrošina operators). Laika josla laika ziņāamp ir CET vai CEST (ar vasaras laiku, kā noteikts ES). Formāts: ggggMMdd HH:mm:ss. |
| Statusa teksts | virkne | O | – | 255 | Vietturis papildu informācijai no Operatora, piemēram, skaidra statusa/iemesla apraksta tekstā. Darbība var atšķirties atkarībā no operatora integrācijas. |
| CorrelationId | virkne | O | – | 100 | SendRequest vai SendTextRequest norādītais korelācijas ID. |
| OperatorNetworkCode | vesels skaitlis | O | – | 6 | Operatora mobilā tīkla kods (MCC + MNC). |
* M = obligāti, O = neobligāti, I = ignorēts.
Pakalpojuma sniedzējam ir jānodrošina LINK Mobility ar mērķi URL piegādes atskaitēm (pēc izvēles iekļaujot HTTP pamata autentifikācijas akreditācijas datus). Pakalpojumu sniedzējs var izvēlēties, kuru HTTP metodi izmantot:
HTTP POST (ieteicams)
HTTP GET.
Example, izmantojot HTTP GET (sekmīgi piegādāts):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Exampizmantojot HTTP GET (nav piegādāts, operators ir piegādājis timestamp pasākumam):
Parametri ir URL kodēti.
Rakstzīmju kodējums:
Pakalpojumu sniedzējs var izvēlēties, kuru vēlamo rakstzīmju kodējumu izmantot:
UTF-8 (ieteicams)
ISO-8859-1.
9.1. Pakalpojuma sniedzēja apstiprinājums
Pakalpojuma sniedzējam ir jāapstiprina katrs piegādes ziņojums. Apstiprinājums var būt pozitīvs, ti, piegādes ziņojums ir veiksmīgi saņemts, vai negatīvs, ti, neveiksme.
Lūdzu, ņemiet vērā: LINK Mobility ir 30 sekunžu nolasīšanas taimauts piegādes ziņojumu apstiprinājuma saņemšanai. Taimauts aktivizēs piegādes atkārtotu mēģinājumu (ja ir iespējots atkārtots mēģinājums) vai piegādes atcelšanu (ja atkārtots mēģinājums ir atspējots). Tas nozīmē, ka pakalpojumu sniedzēja lietojumprogrammai ir jānodrošina ātrs reakcijas laiks, īpaši lielas slodzes laikā.
Pirms apstrādes ir ļoti ieteicams apstiprināt piegādes ziņojumu LINK Mobility.
Noteikums par pozitīvu un negatīvu apstiprinājumu ir aprakstīts šādi:
Pozitīvs apstiprinājums, ACK, piegādes ziņojums piegādāts:
HTTP 200 diapazona atbildes kods kombinācijā ar šādu XML formāta saturu:
Negatīvs apstiprinājums, NAK, piegādes ziņojums nav piegādāts:
Jebkura atbilde, izņemot pozitīvu apstiprinājumu, piemēram,ample, negatīvu apstiprinājumu aktivizē jebkurš HTTP kļūdas kods vai šāds XML saturs:
XML saturu var izmantot, lai kontrolētu LINK mobilitātes atkārtošanas mehānismu. NAK izraisīs atkārtota mēģinājuma mēģinājumu, ja tas ir iespējots. Pakalpojumu sniedzējiem, kas nav konfigurēti atkārtota mēģinājuma mehānismam, XML saturs nav obligāts.
Tālāk ir sniegts HTTP POST pieprasījums un atbilde, piemēramampPakalpojumu sniedzējam piegādātā piegādes atskaite:
HTTP pieprasījums:
POST /context/app HTTP/1.1
Satura tips: application / x-www-form-urlkodēts;charset=utf-8
Resursdators: serveris: ports
Satura garums: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP atbilde:
HTTP/1.1 200 OK
Satura veids: teksts/vienkāršs
9.2 Mēģiniet vēlreiz
Sistēma LINK Mobility var veikt atkārtotus mēģinājumus neveiksmīgu, ti, neapstiprinātu piegādes atskaites piegādes gadījumā. Pakalpojumu sniedzējs var izvēlēties vēlamo atkārtotā mēģinājuma darbību:
Nav atkārtota mēģinājuma (noklusējums) — ziņojums tiks atmests, ja savienojuma mēģinājums neizdodas, lasīšanas taimauts vai HTTP kļūdas kods.
Mēģiniet vēlreiz – ziņojums tiks nosūtīts atkārtoti par katru savienojuma problēmu veidu, lasīšanas taimautu vai negatīvu apstiprinājumu.
Kad ir iespējots NAK atkārtotais mēģinājums, ir svarīgi saprast, kuri scenāriji ģenerēs atkārtota mēģinājuma mēģinājumu no LINK Mobility un kā notiek atkārtots mēģinājums. Katram Pakalpojumu sniedzējam ir sava atkārtošanas rinda, kurā ziņojumi tiek sakārtoti atbilstoši ziņojumu laikiemamp. Link Mobility vienmēr vispirms cenšas piegādāt vecākus ziņojumus, lai gan netiek garantēta individuālā Pakalpojumu sniedzējam piegādāto ziņojumu secība. Galvenais iemesls, kāpēc ziņojumi tiek izmesti no atkārtotas mēģinājuma rindas, ir viens no diviem iemesliem: vai nu ziņojuma TTL derīguma termiņš beidzas, vai (teorētiski) atkārtošanās rinda ir pilna. TTL ir atkarīgs no operatora un konta, ti, var atšķirties atkarībā no operatora un/vai ziņojuma veida, piemēram, premium SMS vai standarta tarifa SMS īsziņa.
Pakalpojumu sniedzējiem ar iespējotu atkārtotu mēģinājumu ir jāpārbauda MT ziņojuma unikālais ID, lai pārliecinātos, ka ziņojums vēl nav saņemts.
Pakalpojuma sniedzējam ir svarīgi ievērot šos vienkāršos noteikumus, kad piegādes atskaites apstrādes laikā rodas kļūda, ja kļūdas iemesls ir: Pagaidu, piemēram, datubāze nav pieejama, ir jāatgriež NAK. LINK Mobilitāte atkārtoti nosūtīs ziņojumu.
Pastāvīgs un atkārtots mēģinājums, visticamāk, radīs tāda paša veida problēmu, ir jāatdod ACK. Piemēram,ample, kad ziņojumu nevarēja pareizi parsēt vai tas izraisīja neparedzētu izpildlaika kļūdu.
Rīkojoties atbilstoši, tiks nodrošināts, ka piegādes atskaites atkārtotas atkārtotas nosūtīšanas dēļ netiek izraisīta bloķēšana vai caurlaidspējas pasliktināšanās.
10. Ieviešanas padomi
1. Ir iespējams izmantot savu web pārlūkprogrammā, lai iesniegtu pieprasījumus API. Tas ļauj ļoti viegli izpētīt un novērtēt pakalpojumus bez izstrādes rīkiem.
2. Chrome vai Firefox ieteicams lietot kopā ar paplašinājumu, piemēram, JSONView lai parādītu diezgan formatētu JSON.
3. Mēs esam izmantojuši SoapUI, lai pārbaudītu POST, pamata autentifikāciju un pārbaudītu neapstrādātus HTTP pieprasījumu un atbildes ziņojumus.
4. CURL rīks ir noderīgs, lai iesniegtu POST pieprasījumus ar pamata autentifikāciju. Skatīt example zemāk.
curl POSTĪT \
-H “Satura veids: pieteikums/x-www-form-urlkodēts” \
-H “Autorizācija: pamata am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–dati “destinationAddress=46123456789&messageText=Sveiki+Pasaule%21”
_______________
Personalizētās komunikācijas pārveidošana
Dokumenti / Resursi
 |
LINK Mobilitātes ieviešanas rokasgrāmata REST API SMS [pdfLietotāja rokasgrāmata Mobilitātes ieviešanas rokasgrāmata REST API SMS, mobilitāte, ieviešanas ceļvedis REST API SMS, REST API SMS, API SMS, SMS |
