LINK Gabay sa Pagpapatupad ng Mobility REST API SMS
Ang LINK Mobility ay nagbibigay ng serbisyo para sa paghahatid ng mensahe, mga micro na pagbabayad, at mga serbisyong nakabatay sa lokasyon. Ang platform ay gumaganap bilang isang transparent, white-label na content acquirer at transaction router sa pagitan ng Mga Service Provider at Operator.
Ang LINK Mobility ay nagbibigay ng isang RESTful API na maaaring magamit upang ma-access ang mga serbisyo ng LINK Mobility gaya ng pagpapadala ng SMS. Ang API na ito ay idinisenyo upang maging madaling gamitin at tugma sa lahat ng modernong wika at frameworks. Gamit ang wikang iyong pinili, magagamit ng iyong application ang Link Mobility REST API upang ipatupad ang mahusay na mga kakayahan sa pagmemensahe at pagbabayad
© LINK Mobility, Marso 10, 2021
Legal na Impormasyon
Ang impormasyong ibinigay sa dokumentong ito ay ang tanging pag-aari at copyright ng Netsize. Ito ay kumpidensyal at inilaan para sa mahigpit na paggamit ng impormasyon. Hindi ito nagbubuklod at maaaring sumailalim sa mga pagbabago nang walang abiso. Anumang hindi awtorisadong pagsisiwalat o paggamit ay dapat ituring na labag sa batas.
Ang Netsize™ at linkmobility™ ay protektado ng mga batas sa French, EEC at internasyonal na intelektwal na ari-arian.
Ang lahat ng iba pang trademark na sinipi ay ang tanging pag-aari ng kani-kanilang mga may-ari.
Walang anumang nilalaman dito ang dapat ipakahulugan bilang nagbibigay ng anumang lisensya o karapatan sa ilalim ng Netsize patent, copyright, o trademark.
NETSIZE
Société anonyme au capital de 5 478 070 euros
Siège social :62, avenue Emile Zola92100 Boulogne – France
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Saklaw ng Dokumento
Inilalarawan ng dokumentong ito kung paano ginagamit ng Service Provider ang LINK Mobility REST API para sa SMS. Ito ay inilaan para sa mga teknikal na arkitekto at taga-disenyo na nagpapatupad ng mga serbisyo ng Service Provider.
1. Pangunahing Paggamit
Napakadaling magpadala ng SMS. Nagpapadala ka ng HTTP na kahilingan sa LINK Mobility na maaaring magawa gamit lamang ang isang web browser.
2. Functional Overview
Ang LINK Mobility system ay nagbibigay ng sumusunod na pangunahing pagpapagana para sa mga mensaheng SMS:
Pagpapadala ng Mobile Terminated (MT) na mga SMS na mensahe, gaya ng text o binary (eg WAP Push) premium at standard rate na mga mensahe.
Pagtanggap ng mga ulat sa paghahatid para sa mga isinumiteng mensahe sa MT.
Pagtanggap ng Mobile Originated (MO) na mga SMS na mensahe, premium at karaniwang rate.
Ang SMS REST API ay nakatuon sa pagpapadala ng karaniwang rate ng MT SMS na mga mensahe.
Ang API ay nagpapadala ng lahat ng mga mensaheng SMS nang asynchronous, na nagpapagana ng mga feature gaya ng:
“Fire-and-forget” – gusto ng Service Provider na magkaroon ng mas predictable na oras ng pagtugon at ayaw maghintay ng resulta mula sa Operator.
Subukan muli ang functionality – Ipapadala muli ng LINK Mobility ang mensahe kung ang Operator ay may mga pansamantalang problema.
2.1 Pagpapadala ng SMS message
Service Provider Netsize Consumer
- Magpadala ng mensahe sa MT
- Ibalik ang message ID
- Magsumite ng mensaheng SMS
- Maghatid ng ulat ng paghahatid
- Magpadala ng ulat ng paghahatid
Ang pangunahing daloy para sa pagpapadala ng mga mensaheng SMS ay inilarawan bilang mga sumusunod:
Ang Service Provider ay humihiling na magpadala ng SMS message sa isang tatanggap sa pamamagitan ng LINK Mobility system.
Isang message ID ang ibinalik sa Service Provider. Maaaring gamitin ang ID na ito para sa hal. iugnay ang mensahe sa tamang ulat ng paghahatid.
Pinangangasiwaan ng LINK Mobility ang pagruruta at inihahatid ang mensaheng SMS sa naka-address na Consumer.
Nati-trigger ang isang ulat sa paghahatid, hal. kapag ang mensaheng SMS ay naihatid sa device ng Consumer.
Ang ulat ng paghahatid ay ipinadala sa Service Provider. Ang ulat ay naglalaman ng parehong ID ng mensahe na ibinalik sa hakbang 2.
Alternatibong daloy: Di-wastong kahilingan
Kung ang mga ibinigay na parameter o mga kredensyal ng user sa kahilingan ay hindi wasto, isang error ang ibabalik sa Service Provider. Ang error ay nagpapahiwatig ng dahilan para sa pagtanggi at ang daloy ay nagtatapos. Walang ibinalik na message ID.
3. Endpoint
Ang mapagkukunan ng SMS ay ina-access gamit ang landas:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Para sa seguridad ng koneksyon ang LINK Mobility REST API ay maa-access lamang sa HTTPS.
Ang Link Mobility server certificate ay nilagdaan ng Thawte Server CA.
4. Mga operasyon
Ang serbisyo ng SMS ay nagbibigay ng mga sumusunod na operasyon:
| Pangalan | Daan |
| Ipadala | /restapi/v1/sms/send |
4.1 Ipadala
Ang operasyon ng pagpapadala ay ginagamit upang magpadala ng SMS sa iisang tatanggap.
Ang operasyong ito ay inilaan para sa parehong basic at advanced na mga user. Sa pinakasimpleng kaso, tanging ang patutunguhang address, at ang text ng mensahe ang kinakailangan upang makapaghatid ng SMS. Matutukoy ng LINK Mobility ang Data Coding Scheme at magsasagawa ng awtomatikong pagsasama-sama ng isang mensahe sa maraming bahagi ng mensahe kung kinakailangan.
Para sa advanced na paggamit, maaaring gumamit ang Service Provider ng mga opsyonal na parameter para sa kabuuang kontrol sa pag-format ng mensahe kasama ang header ng data ng user.
Maaaring magpadala ang Service Provider ng mga pinagsama-samang mensahe, ngunit ang paghahanda ng data ng user at header ng data ng user ay dapat gawin ng Service Provider at ang mensahe ay dapat ipadala sa pamamagitan ng maraming mga kahilingan sa pagpapadala patungo sa LINK Mobility.
5. Pagpapatunay
Ang username at password ay isinumite sa bawat kahilingan gamit ang HTTP Basic Authentication Scheme.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Ipinapadala ang mga kredensyal sa isang header ng Awtorisasyon sa kahilingan sa HTTP. Binubuo ng kliyente ang field ng header tulad ng inilarawan dito:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Para kay example, kung ang username ay john at changeme ang password, ang resultang Authorization header ay:
Awtorisasyon: Basic am9objpjaGFuZ2VtZSA=
Bilang isang fall-back ang username at password ay maaaring isumite bilang mga parameter ng kahilingan. Inirerekomenda lamang ito para sa mga kliyenteng hindi sumusuporta sa Basic Auth.
6. Pagsusumite ng kahilingan
6.1 Query string
Ang mga parameter ng kahilingan ay isinumite bilang string ng query na naglalaman ng mga pares ng pangalan/halaga. Ang query string ay naka-encode gamit ang Percent Encoding (URL encoding).
http://www.w3schools.com/tags/ref_urlencode.asp
Para kay example, Hello World! ay naka-encode bilang Hello+World%21.
6.2 Mga parameter ng ipinag-uutos na kahilingan
| Pangalan | Max haba | Paglalarawan |
| destinationAddress | 40 | Ang MSISDN kung saan dapat ipadala ang SMS message, simula sa country code. Halampang: 46123456789. Para sa ilang market (kung saan dapat i-obfuscate ang Consumer MSISDN) ang value na ito ay maaari ding alphanumeric alias, na may prefix na “#”. |
| messageText | 1600 | Ang nilalaman ng mensaheng SMS. |
6.3 Opsyonal na mga parameter ng kahilingan (para sa advanced na paggamit)
| Pangalan | Max haba | Paglalarawan |
| originatingAddress | 16 | Ang pinagmulang address para sa papalabas na mensaheng SMS. Ang uri ng pinagmulang address ay tinutukoy ng originatorTON parameter. Ang max na haba ng maikling numero ay 16. Ang alpha numeric sender ay limitado sa GSM default na Alphabet na may max na haba na 11 character. Ang max na haba ng nagpadala ng MSISDN ay 15 (gamit ang parehong format bilang elemento ng destinationAddress). Maaaring tanggalin kapag ang originatingAddress at originatingTON ay pinili ng system. Ang function na ito ay nakasalalay sa merkado at pagsasaayos. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| originatorTON | 1 | Ang uri ng numero ng pinagmulang address (TON): 0 – Maikling numero 1 – Alpha numeric (max na haba 11) 2 – MSISDN Maaaring tanggalin kapag ang originatingAddress at originatingTON ay pipiliin ng system. Ang function na ito ay nakadepende sa market at configuration. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| userDataHeader | 280 | Ang Header ng Data ng User kasama ang Data ng User ay maaaring maglaman ng hanggang 140, ibig sabihin, 280 kapag hex-encoded, octets. Palaging hex-encode ang parameter na ito. |
| DCS | 3 | Skema ng coding ng data. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| PID | 3 | Protocol ID. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| relativeValidityTime | 6 | Relatibong oras ng bisa sa mga segundo (na may kaugnayan sa oras para sa pagsusumite sa LINK Mobility). Ang maximum na halaga ay 604800 (7 araw) at ang default ay 48 oras. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| oras ng paghahatid | 20 | Orasamp kung kailan dapat maihatid ang mensaheng SMS (naantala ang oras ng paghahatid). Tingnan ang seksyon sa format ng oras ng petsa. |
| statusReportFlags | 1 | Maghatid ng kahilingan sa ulat: 0 – Walang ulat sa paghahatid (default) 1 – Hiniling ang ulat sa paghahatid 9 – Hiniling ang ulat sa paghahatid ng server (Hindi ipinapasa ng LINK Mobility ang ulat sa Service Provider ngunit ginagawa itong available sa mga ulat atbp.) |
| campaignName | 50 | Ang mga transaksyon sa LINK Mobility ay tagged na may ganitong pangalan. Ginagamit ito sa pagpapangkat ng mga transaksyon sa mga ulat ng Link Mobility. |
| maxConcatenatedMessages | 1 | Isang value sa pagitan ng 1 at 10 na tumutukoy kung gaano karaming mga pinagsama-samang mensahe ang pinapayagan. Ang default ay 3. |
| correlationId | 100 | ID na ibinigay ng Service Provider na ie-echo sa Delivery Report. |
| username | 100 | Ibinigay bilang alternatibo sa HTTP Basic Authentication. |
| password | 100 | Ibinigay bilang alternatibo sa HTTP Basic Authentication. |
6.4 Mga Paraan ng Paghiling ng HTTP
Para sa maximum na interoperability, sinusuportahan ng API ang parehong mga pamamaraan ng paghiling ng HTTP GET at POST. Walang ibang pamamaraan ng HTTP ang pinapayagan.
6.4.1 GET
Ang naka-encode na string ng query ay idinagdag sa URL.
GET
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Awtorisasyon: Basic am9objpjaGFuZ2VtZSA=
6.4.2 POST
Ang naka-encode na string ng query ay isinumite sa katawan ng mensahe ng kahilingan sa HTTP. Ang Uri ng Nilalaman ay application/x-www-form-urlnaka-encode.
POST https://europe.ipx.com/restapi/v1/sms/send
Host: europe.ipx.com
Uri ng Nilalaman: application / x-www-form-urlnaka-encode
Awtorisasyon: Basic am9objpjaGFuZ2VtZSA=
Nilalaman-Haba: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Petsa at oras
Ang mga parameter sa REST API na kumakatawan sa petsa at oras ay palaging nasa UTC time zone (Coordinated Universal Time). Orasamps ay kinakatawan bilang isang string na may ganitong eksaktong format:
2017-04-25T23:20:50Z
Ito ay kumakatawan sa 20 minuto at 50 segundo pagkatapos ng ika-23 oras ng Abril 25, 2017 sa UTC.
7. Mensahe ng tugon
Pagkatapos matanggap at bigyang-kahulugan ang isang mensahe ng kahilingan ang API ay tumutugon sa isang mensahe ng tugon ng HTTP.
7.1 HTTP status code
Ang REST API ay palaging nagbabalik ng HTTP status code 200 OK para sa mga naprosesong kahilingan. Ang katawan ng mensahe ay naglalaman ng isang parameter responseCode na ginagamit upang matukoy ang eksaktong resulta.
7.2 Katawan ng mensahe
Ang katawan ng mensahe ay binubuo ng JSON na naglalarawan sa kinalabasan ng kahilingan.
http://json.org/
Sumusunod ang Link Mobility JSON sa Google JSON Style Guide.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Mga parameter ng pagtugon
| Pangalan | Max haba | Paglalarawan |
| responseCode | 3 | 0 ay nagpapahiwatig ng matagumpay na transaksyon. |
| tugonMensahe | 255 | Tekstuwal na paglalarawan ng tugon, hal. error na teksto. |
| orasamp | 20 | Petsa at oras kung kailan naproseso ng LINK Mobility ang kahilingan. (Sumangguni sa seksyon ng format ng petsa/oras). |
| traceId | 36 | I-link ang panloob na identifier ng Mobility. Ginagamit para sa suporta at pag-troubleshoot. |
| messageIds | 10 x 36 | Array ng LINK Mobility natatanging message ID para sa bawat matagumpay na mensahe (maraming message ID ang ibinabalik kung ang mensahe ay pinagsama-sama). Inalis sa kaso ng pagkabigo. |
7.4 Halample mga tugon
Tagumpay
HTTP/1.1 200 OK
Uri ng Nilalaman: application/json
Nilalaman-Haba: 144
Petsa: Huwebes, 15 Set 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Narito ang parehong JSON na na-format para sa pagiging madaling mabasa:
{
“responseCode“:0,
“tugonMensahe“:”Tagumpay”,
“orasamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Kabiguan
HTTP/1.1 200 OK
Uri ng Nilalaman: application/json
Nilalaman-Haba: 148
Petsa: Huwebes, 15 Set 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Di-wastong pag-login o hindi awtorisadong paggamit ng API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Tagumpay
HTTP/1.1 200 OK
Uri ng Nilalaman: application/json
Nilalaman-Haba: 144
Petsa: Huwebes, 15 Set 2016 13:20:31 GMT
{“responseCode”:0,”responseMessage”:”Success”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Narito ang parehong JSON na na-format para sa pagiging madaling mabasa:
{
“responseCode“:0,
“tugonMensahe“:”Tagumpay”,
“orasamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Kabiguan
HTTP/1.1 200 OK
Uri ng Nilalaman: application/json
Nilalaman-Haba: 148
Petsa: Huwebes, 15 Set 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Di-wastong pag-login o hindi awtorisadong paggamit ng API”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Mga code ng pagtugon
Ang mga sumusunod na response code ay maaaring ibalik sa send response:
| Code | Text | Paglalarawan |
| 0 | Tagumpay | Matagumpay na naisakatuparan. |
| 1 | Di-wastong pag-login o hindi awtorisadong paggamit ng API | Ang maling username o password o Service Provider ay hinahadlangan ng LINK Mobility. |
| 2 | Ang mamimili ay hinarangan ng Link Mobility | Ang Consumer ay hinarangan ng LINK Mobility. |
| 3 | Ang operasyon ay hindi ibinibigay ng LINK Mobility | Naka-block ang operasyon para sa Service Provider. |
| 4 | Ang mamimili ay hindi kilala sa LINK Mobility | Ang Consumer ay hindi kilala sa LINK Mobility. O kung ginamit ang alyas sa kahilingan; hindi nahanap ang alyas. |
| 5 | Hinarang ng consumer ang serbisyong ito sa LINK Mobility | Hinarang ng Consumer ang serbisyong ito sa LINK Mobility. |
| 6 | Ang pinagmulang address ay hindi suportado | Ang pinagmulang address ay hindi suportado. |
| 7 | Hindi sinusuportahan ng account ang alpha originating address | Ang alpha originating address ay hindi sinusuportahan ng account. |
| 8 | Hindi suportado ang pinanggalingang address ng MSISDN | Hindi suportado ang pinagmulang address ng MSISDN. |
| 9 | Hindi suportado ang GSM extended | Hindi suportado ang GSM extended. |
| 10 | Hindi suportado ang Unicode | Hindi suportado ang Unicode. |
| 11 | Hindi suportado ang ulat sa katayuan | Hindi suportado ang ulat sa katayuan. |
| 12 | Hindi suportado ang kinakailangang kakayahan | Ang kinakailangang kakayahan (maliban sa nasa itaas) para sa pagpapadala ng mensahe ay hindi suportado. |
| 13 | Lumampas ang max throttling rate ng provider ng nilalaman | Masyadong mabilis ang pagpapadala ng Service Provider ng mga mensaheng SMS sa LINK Mobility. |
| 14 | Hindi sinusuportahan ng account ang Protocol ID | Hindi suportado ang Protocol ID. |
| 15 | Lumampas sa limitasyon ng pagsasama-sama ng mensahe | Ang bilang ng mga pinagsama-samang mensahe ay lumampas sa max na numero na hiniling. |
| 16 | Hindi ma-ruta ang mensahe. | Hindi nagawang iruta ng LINK Mobility ang mensahe. |
| 17 | Ipinagbabawal na tagal ng panahon | Hindi pinapayagang magpadala ng mensahe sa tagal ng panahon |
| 18 | Masyadong mababa ang balanse sa service provider account | Naka-block ang service provider dahil sa Masyadong mababang balanse |
| 50 | Bahagyang tagumpay | Bahagyang tagumpay kapag nagpapadala ng mensaheng SMS sa maraming tatanggap. |
| 99 | Error sa panloob na server | Iba pang error sa Link Mobility, makipag-ugnayan sa suporta ng LINK Mobility para sa higit pang impormasyon. |
| 100 | Di-wastong address ng patutunguhan | Ang patutunguhang address (MSISDN, o alias) ay hindi wasto. |
| 102 | Di-wastong reference (naka-link) ID | Ang reference ID ay hindi wasto, marahil ang reference ID ay ginagamit na, masyadong luma o hindi kilala. |
| 103 | Di-wastong pangalan ng account | Ang pangalan ng account ay hindi wasto. |
| 105 | Di-wastong meta data ng serbisyo | Di-wasto ang meta data ng serbisyo. |
| 106 | Di-wastong pinanggalingang address | Ang pinagmulang address ay hindi wasto. |
| 107 | Di-wastong alphanumeric na pinagmulang address | Ang alphanumeric na pinagmulang address ay hindi wasto. |
| 108 | Di-wastong oras ng bisa | Ang oras ng bisa ay di-wasto. |
| 109 | Di-wastong oras ng paghahatid | Ang oras ng paghahatid ay hindi wasto. |
| 110 | Di-wastong nilalaman ng mensahe/data ng user | Ang data ng user, ibig sabihin, ang mensaheng SMS, ay hindi wasto. |
| 111 | Di-wastong haba ng mensahe | Ang haba ng mensahe ng SMS ay hindi wasto. |
| 112 | Di-wastong header ng data ng user | Di-wasto ang header ng data ng user. |
| 113 | Di-wastong data coding scheme | Ang DCS ay hindi wasto. |
| 114 | Di-wastong protocol ID | Ang PID ay hindi wasto. |
| 115 | Di-wastong mga flag ng ulat sa katayuan | Ang mga flag ng ulat ng katayuan ay hindi wasto. |
| 116 | Di-wastong TON | Di-wasto ang originator na TON. |
| 117 | Di-wasto camppangalan ng aign | Ang campdi-wasto ang pangalan ng aign. |
| 120 | Di-wastong limitasyon para sa maximum na bilang ng mga pinagsama-samang mensahe | Ang maximum na bilang ng mga pinagsama-samang mensahe ay hindi wasto. |
| 121 | Di-wastong address ng pinagmulan ng msisdn | Di-wasto ang pinanggalingang address ng MSISDN. |
| 122 | Di-wastong correlation ID | Di-wasto ang correlation ID. |
8. Opsyonal na mga tampok
8.1 Pagwawasto ng MSISDN
Ang pagwawasto ng MSISDN ay isang opsyonal na feature na maaaring paganahin ng LINK Mobility support kung hihilingin.
Itatama ng feature na ito ang mga patutunguhan na address at ihanay ang mga ito sa kinakailangang E.164 na format. Bilang karagdagan sa pagwawasto ng format, ang system ay maaari ring magsagawa ng partikular na paggana sa merkado tulad ng pagsasalin ng mga internasyonal na numerong Pranses upang itama ang mga numero ng DOM-TOM (départements et territoires d'outre-mer) kapag naaangkop.
Nasa ibaba ang ilang exampmga pagwawasto:
| Naisumite ang Destination Address | Nawastong Address ng Patutunguhan |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Isinalin ang numerong Pranses sa isang numero ng DOM-TOM) |
Bukod pa rito, posibleng payagan ang mga pambansang numero ng telepono para sa isang napiling merkado. Kapag ang tampok na ito ay pinagana ang anumang mga internasyonal na numero para sa iba pang mga merkado ay dapat ipadala na may paunang `+' na senyales upang makilala ang mga ito mula sa napiling merkado.
Nasa ibaba ang ilang exampkaunting pagwawasto na ginawa kapag ginagamit ang Sweden (country code 46) bilang default na market para sa mga pambansang numero.
| Naisumite ang Destination Address | Nawastong Address ng Patutunguhan |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Di-wasto dahil nawawala ang sign na '+' |
Tandaan na ang itinamang MSISDN ay gagamitin ng LINK Mobility at ito ay ibabalik sa mga ulat ng paghahatid.
Mangyaring makipag-ugnayan sa LINK Mobility support para sa higit pang impormasyon.
8.2 Pagpapalit ng Character
Ang pagpapalit ng character ay isang opsyonal na feature na maaaring paganahin ng LINK Mobility support kung hihilingin.
Ita-translate ng feature na ito ang mga hindi GSM alphabet character sa data ng user (SMS text) sa katumbas na GSM alphabet character kapag ang DCS ay nakatakda sa “GSM” (17). Para kay exampAng "Seqüência de teste em Português" ay isasalin sa "Seqüencia de teste em Portugues".
9. Mga ulat sa paghahatid
Ang Service Provider ay maaaring, kung nakalaan, humiling ng mga ulat sa paghahatid ng mensahe ng SMS o mga abiso sa paghahatid para sa mga mensaheng MT na ipinadala. Ang mga ulat na ito ay na-trigger sa Operator SMSC kapag ang MT na mensahe ay naihatid sa target na Consumer o tinanggal, hal., nag-expire o, sa ilang kadahilanan, hindi na-routable.
Tanging ang huling katayuan ng mensaheng SMS ang iniuulat sa Service Provider, ibig sabihin, inihatid o tinanggal. Isang ulat lamang sa bawat mensahe ng MT ang nabuo. Sa na-delete na status, maaaring mag-apply ang isang reason code. Ang code ng dahilan na ito ay tumutukoy sa dahilan ng hindi naihatid na mensaheng SMS.
Ang mga ulat ay niruruta sa pamamagitan ng LINK Mobility at ipinadala sa Service Provider gamit ang HTTP protocol.
Upang makatanggap ng mga ulat, kailangang ipatupad ng Service Provider para sa halampisang Java Servlet o isang pahina ng ASP.NET. Parehong tumatanggap ng HTTP GET o POST na mga kahilingan.
Mga Parameter
Kasama sa kahilingan ang mga sumusunod na parameter:
| Parameter | Uri | M/O/I* | Default na Halaga | Max haba | Paglalarawan |
| MessageId | string | M | – | 22 | Ang message ID ng MT message kung saan nauugnay ang ulat na ito. |
| DestinationAddress | string | M | – | 40 | Ang MSISDN ng Consumer, ibig sabihin, ang patutunguhang address ng orihinal na mensahe ng MT. |
| StatusCode | integer | M | 1 | Ang status code ay nagpapahiwatig ng katayuan ng MT na mensahe. Ang mga naaangkop na code ng katayuan ay: 0 – Naihatid 2 – Tinanggal (nalalapat ang reason code) |
|
| Ang TimeStamp | string | M | – | 20 | Oras na nagsasaad kung kailan natanggap ng LINK Mobility ang ulat ng paghahatid. Ang time zone ng timesamp ay CET o CEST (na may oras ng tag-init gaya ng tinukoy para sa EU). Format: yyyyMMdd HH:mm:ss. |
| Operator | string | M | – | 100 | Ang pangalan ng Operator na ginamit kapag nagpapadala ng mensaheng SMS o ang pangalan ng account na ginamit kapag nagpapadala ng mensaheng SMS. Ang isang listahan ng mga available na Operator ay ibinibigay ng LINK Mobility support. |
| ReasonCode | integer | O | – | 3 | Isinasaad ng reason code kung bakit napunta ang mensahe sa status na tinanggal. Ang mga naaangkop na code ng dahilan ay: 100 – Nag-expire na 101 – Tinanggihan 102 – Error sa format 103 – Iba pang error 110 – Hindi kilala ang subscriber 111 – Pinagbawalan ang subscriber 112 – Hindi nakalaan ang subscriber 113 – Hindi available ang subscriber 120 – Nabigo ang SMSC 121 – Pagsisikip ng SMSC 122 – SMSC roaming 130 – Error sa handset 131 – Lumampas ang memorya ng handset Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| OperatorTimeStamp | string | O | – | 20 | Oras na nagsasaad kung kailan na-trigger ang ulat sa SMSC ng Operator (kung ibinigay ng Operator). Ang time zone ng timesamp ay CET o CEST (na may oras ng tag-init gaya ng tinukoy para sa EU). Format: yyyyMMdd HH:mm:ss. |
| StatusText | string | O | – | 255 | Placeholder para sa karagdagang impormasyon mula sa Operator, hal. malinaw na tekstong paglalarawan ng katayuan/dahilan. Maaaring mag-iba ang pag-uugali sa mga pagsasama ng Operator. |
| CorrelationId | string | O | – | 100 | Ang correlation ID na ibinigay sa SendRequest o SendTextRequest. |
| OperatorNetworkCode | integer | O | – | 6 | Ang Mobile Network Code (MCC + MNC) ng Operator. |
* M = Mandatory, O = Opsyonal, I = Hindi pinansin.
Ang Service Provider ay kailangang magbigay ng LINK Mobility sa target URL para sa mga ulat sa paghahatid (opsyonal kasama ang mga kredensyal para sa pangunahing pagpapatunay ng HTTP). Maaaring piliin ng Service Provider kung aling paraan ng HTTP ang gagamitin:
HTTP POST (inirerekomenda)
HTTP GET.
Exampgamit ang HTTP GET (matagumpay na naihatid):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Exampgamit ang HTTP GET (hindi naihatid, ang Operator ay nagbigay ng timestamp para sa kaganapan):
Ang mga parameter ay URL encodedi.
Encoding ng character:
Maaaring piliin ng Service Provider kung aling pag-encode ng character ang gustong gamitin:
UTF-8 (inirerekomenda)
ISO-8859-1.
9.1 Pagkilala ng Tagabigay ng Serbisyo
Dapat kilalanin ng Service Provider ang bawat ulat ng paghahatid. Ang pagkilala ay maaaring positibo, ibig sabihin, matagumpay na natanggap ang ulat ng paghahatid, o negatibo, ibig sabihin, pagkabigo.
Pakitandaan: Ang LINK Mobility ay may read timeout para sa mga pagkilala na 30 segundo para sa mga ulat sa paghahatid. Ang isang timeout ay magti-trigger ng isang muling pagsubok sa paghahatid (kung muling subukang pinagana) o isang pagkansela ng paghahatid (kung muling subukang hindi pinagana). Nangangahulugan ito na dapat tiyakin ng application ng Service Provider ang mabilis na mga oras ng pagtugon, lalo na sa panahon ng mataas na pagkarga.
Lubos na inirerekomendang kilalanin ang ulat ng paghahatid patungo sa LINK Mobility bago ito iproseso.
Ang panuntunan para sa positibo at negatibong pagkilala ay inilarawan bilang mga sumusunod:
Positibong pagkilala, ACK, naihatid na ulat sa paghahatid:
HTTP 200 range response code kasama ang sumusunod na XML formatted content:
Negatibong pagkilala, NAK, hindi naihatid ang ulat ng paghahatid:
Anumang tugon maliban sa positibong pagkilala, halampSa gayon, ang isang negatibong pagkilala ay na-trigger ng anumang HTTP error code o ng sumusunod na XML na nilalaman:
Ang XML na nilalaman ay maaaring gamitin para sa pagkontrol sa LINK Mobility retry mechanism. Ang NAK ay magdudulot ng muling pagsubok, kung pinagana. Para sa Mga Service Provider na hindi na-configure para sa mekanismong muling subukan, ang XML na nilalaman ay opsyonal.
Nasa ibaba ang HTTP POST na kahilingan at tugon halample ng isang ulat sa paghahatid na inihatid sa isang Service Provider:
Kahilingan sa HTTP:
POST /context/app HTTP/1.1
Uri ng Nilalaman: application / x-www-form-urlnaka-encode;charset=utf-8
Host: server:port
Nilalaman-Haba: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
HTTP Response:
HTTP/1.1 200 OK
Uri ng Nilalaman: text/plain
9.2 Subukang muli
Ang sistema ng LINK Mobility ay maaaring magsagawa ng mga pagsubok na muling subukan para sa mga nabigo, ibig sabihin, hindi kinikilala, mga paghahatid ng ulat sa paghahatid. Maaaring piliin ng Service Provider ang gustong muling subukang gawi:
Walang subukang muli (default) – ang mensahe ay itatapon kung mabigo ang pagtatangkang koneksyon, magbasa ng time-out o para sa anumang HTTP error code.
Subukan muli – ang mensahe ay ipapadala para sa bawat uri ng problema sa koneksyon, read timeout, o negatibong pagkilala.
Kapag pinagana ang muling pagsubok para sa NAK, mahalagang maunawaan kung aling mga senaryo ang bubuo ng muling pagsubok mula sa LINK Mobility at kung paano gumagana ang muling pagsubok. Ang bawat Service Provider ay may sarili nitong retry queue, kung saan ang mga mensahe ay inoorder ayon sa timest ng mensaheamp. Palaging sinusubukan ng Link Mobility na maghatid muna ng mga mas lumang mensahe, kahit na ang indibidwal na pagkakasunud-sunod ng mga mensahe na inihatid sa Service Provider ay hindi ginagarantiyahan. Ang pangunahing dahilan ng pag-discard ng mga mensahe mula sa retry queue ay isa sa dalawang dahilan: mag-e-expire ang mensaheng TTL o (theoretically) ang retry queue ay magiging puno. Ang TTL ay Operator at umaasa sa account, ibig sabihin, ay maaaring mag-iba depende sa Operator at o uri ng mensahe, hal, premium na SMS o karaniwang rate ng SMS na mensahe.
Ang isang Service Provider na may retry enabled ay dapat suriin ang natatanging ID ng MT na mensahe upang matiyak na ang mensahe ay hindi pa natatanggap.
Mahalaga para sa Service Provider na sumunod sa mga simpleng panuntunang ito kapag may naganap na error sa pagpoproseso ng isang ulat sa paghahatid kung ang dahilan ng error ay: Pansamantala, hal. database ay hindi magagamit, isang NAK ay dapat ibalik. Ipapadalang muli ng LINK Mobility ang mensahe.
Ang permanenteng at isang muling pagsubok ay malamang na magdulot ng parehong uri ng problema, isang ACK ang dapat ibalik. Para kay example, kapag ang mensahe ay hindi ma-parse ng tama o nagdulot ng hindi inaasahang runtime error.
Ang pagkilos nang naaayon ay titiyakin na walang pagharang o throughput degradation ang dulot dahil sa paulit-ulit na pagpapadala ng ulat.
10. Mga tip sa pagpapatupad
1. Posibleng gamitin ang iyong web browser upang magsumite ng mga kahilingan sa API. Ginagawa nitong napakadaling galugarin at suriin ang mga serbisyo nang walang anumang mga tool sa pag-unlad.
2. Inirerekomenda ang Chrome o Firefox kasama ng extension gaya ng JSONView upang ipakita ang medyo naka-format na JSON.
3. Gumamit kami ng SoapUI para sa pagsubok ng POST, Basic Authentication at para sa pag-inspeksyon ng hilaw na HTTP request at mga mensahe ng pagtugon.
4. Ang cURL Ang tool ay kapaki-pakinabang para sa pagsusumite ng mga kahilingan sa POST na may Basic Authentication. Tingnan ang exampsa ibaba.
curl POST \
-H "Uri ng Nilalaman: application/x-www-form-urlnaka-encode” \
-H "Awtorisasyon: Basic am9objpjaGFuZ2VtZSA=" \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
Pagbabago ng Mga Personalized na Komunikasyon
Mga Dokumento / Mga Mapagkukunan
 |
LINK Gabay sa Pagpapatupad ng Mobility REST API SMS [pdf] Gabay sa Gumagamit Gabay sa Pagpapatupad ng Mobility REST API SMS, Mobility, Gabay sa Pagpapatupad REST API SMS, REST API SMS, API SMS, SMS |
