Panduan Pelaksanaan Mobiliti LINK REST API SMS
LINK Mobility menyediakan perkhidmatan untuk penghantaran mesej, pembayaran mikro dan perkhidmatan berasaskan lokasi. Platform ini bertindak sebagai pemeroleh kandungan label putih yang telus dan penghala transaksi antara Pembekal Perkhidmatan dan Pengendali.
LINK Mobility menyediakan API RESTful yang boleh digunakan untuk mengakses perkhidmatan LINK Mobility seperti menghantar SMS. API ini direka bentuk agar mudah digunakan dan serasi dengan semua bahasa dan rangka kerja moden. Menggunakan bahasa pilihan anda, aplikasi anda boleh menggunakan Link Mobility REST API untuk melaksanakan pemesejan yang berkuasa dan keupayaan pembayaran
© LINK Mobiliti, 10 Mac 2021
Maklumat Undang-undang
Maklumat yang dibekalkan dalam dokumen ini adalah hak milik tunggal dan hak cipta Netsize. Ia adalah sulit dan bertujuan untuk kegunaan maklumat yang ketat. Ia tidak mengikat dan mungkin tertakluk kepada perubahan tanpa notis. Sebarang pendedahan atau penggunaan yang tidak dibenarkan akan dianggap sebagai menyalahi undang-undang.
Netsize™ dan linkmobility™ dilindungi oleh undang-undang harta intelek Perancis, EEC dan antarabangsa.
Semua tanda dagangan lain yang disebut adalah hak milik tunggal pemilik masing-masing.
Tiada apa-apa yang terkandung di sini boleh ditafsirkan sebagai memberikan sebarang lesen atau hak di bawah paten Netsize, hak cipta atau tanda dagangan.
BERSIZE
Société anonyme au capital de 5 478 070 euros
Siège social :62, avenue Emile Zola92100 Boulogne – Perancis
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Skop Dokumen
Dokumen ini menerangkan cara Pembekal Perkhidmatan menggunakan LINK Mobility REST API untuk SMS. Ia bertujuan untuk arkitek teknikal dan pereka bentuk yang melaksanakan perkhidmatan Pembekal Perkhidmatan.
1. Penggunaan Asas
Sangat mudah untuk menghantar SMS. Anda menghantar permintaan HTTP ke LINK Mobility yang boleh dicapai menggunakan hanya a web pelayar.
2. Berfungsi Lebihview
Sistem Mobiliti LINK menyediakan fungsi asas berikut untuk mesej SMS:
Menghantar mesej SMS Mobile Ditamatkan (MT), seperti teks atau perduaan (cth WAP Push) premium dan mesej kadar standard.
Menerima laporan penghantaran untuk mesej MT yang diserahkan.
Menerima mesej SMS Asal Mudah Alih (MO), kadar premium dan standard.
SMS REST API dikhususkan untuk menghantar mesej SMS MT kadar standard.
API menghantar semua mesej SMS secara tidak segerak, membolehkan ciri seperti:
“Fire-and-forget” – Pembekal Perkhidmatan mahu mempunyai masa tindak balas yang lebih boleh diramal dan tidak mahu menunggu keputusan daripada Operator.
Cuba semula fungsi – LINK Mobility akan menghantar semula mesej jika Operator mempunyai masalah sementara.
2.1 Menghantar mesej SMS
Pembekal Perkhidmatan Netsize Consumer
- Hantar mesej MT
- Kembalikan ID mesej
- Hantar mesej SMS
- Menyampaikan laporan penghantaran
- Hantar laporan penghantaran
Aliran asas untuk menghantar mesej SMS diterangkan seperti berikut:
Pembekal Perkhidmatan membuat permintaan untuk menghantar mesej SMS kepada penerima melalui sistem Mobiliti LINK.
ID mesej dikembalikan kepada Pembekal Perkhidmatan. ID ini boleh digunakan untuk cth mengaitkan mesej dengan laporan penghantaran yang betul.
LINK Mobility mengendalikan penghalaan dan menghantar mesej SMS kepada Pengguna yang dialamatkan.
Laporan penghantaran dicetuskan, contohnya apabila mesej SMS dihantar ke peranti Pengguna.
Laporan penghantaran dihantar kepada Pembekal Perkhidmatan. Laporan mengandungi ID mesej yang sama seperti yang dikembalikan dalam langkah 2.
Aliran alternatif: Permintaan tidak sah
Jika parameter yang dibekalkan atau bukti kelayakan pengguna dalam permintaan adalah tidak sah, ralat dikembalikan kepada Pembekal Perkhidmatan. Ralat menunjukkan sebab penolakan dan aliran tamat. Tiada ID mesej dikembalikan.
3. Titik akhir
Sumber SMS diakses menggunakan laluan:
/restapi/v1/sms
Example URL
https://europe.ipx.com/restapi/v1/sms
Untuk keselamatan sambungan, LINK Mobility REST API hanya boleh diakses melalui HTTPS.
Sijil pelayan Mobility Pautan ditandatangani oleh Thawte Server CA.
4. operasi
Perkhidmatan SMS menyediakan operasi berikut:
| Nama | Laluan |
| Hantar | /restapi/v1/sms/hantar |
4.1 Hantar
Operasi hantar digunakan untuk menghantar SMS kepada satu penerima.
Operasi ini bertujuan untuk pengguna asas dan lanjutan. Dalam kes paling mudah, hanya alamat destinasi dan teks mesej diperlukan untuk menghantar SMS. LINK Mobility akan mengesan Skim Pengekodan Data dan melakukan penggabungan automatik mesej ke dalam berbilang bahagian mesej jika perlu.
Untuk penggunaan lanjutan, Pembekal Perkhidmatan boleh menggunakan parameter pilihan untuk kawalan penuh pemformatan mesej termasuk pengepala data pengguna.
Pembekal Perkhidmatan boleh menghantar mesej bercantum, tetapi penyediaan data pengguna dan pengepala data pengguna mesti dibuat oleh Pembekal Perkhidmatan dan mesej mesti dihantar melalui beberapa permintaan penghantaran ke LINK Mobility.
5. Pengesahan
Nama pengguna dan kata laluan diserahkan dalam setiap permintaan menggunakan Skim Pengesahan Asas HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Bukti kelayakan dihantar dalam pengepala Kebenaran dalam permintaan HTTP. Pelanggan membina medan pengepala seperti yang diterangkan di sini:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Untuk example, jika nama pengguna ialah john dan changeme ialah kata laluan maka pengepala Kebenaran yang terhasil ialah:
Keizinan: Asas am9objpjaGFuZ2VtZSA=
Sebagai sandaran nama pengguna dan kata laluan boleh diserahkan sebagai parameter permintaan. Ini hanya disyorkan untuk pelanggan yang tidak menyokong Pengesahan Asas.
6. Mengemukakan permintaan
6.1 Rentetan pertanyaan
Parameter permintaan diserahkan sebagai rentetan pertanyaan yang mengandungi pasangan nama/nilai. Rentetan pertanyaan dikodkan menggunakan Pengekodan Peratus (URL pengekodan).
http://www.w3schools.com/tags/ref_urlencode.asp
Untuk example, Hello World! dikodkan sebagai Hello+World%21.
6.2 Parameter permintaan mandatori
| Nama | Panjang maksimum | Penerangan |
| Alamat destinasi | 40 | MSISDN tempat mesej SMS harus dihantar, bermula dengan kod negara. Cthample: 46123456789. Untuk sesetengah pasaran (di mana MSISDN Pengguna mesti dikelirukan) nilai ini juga boleh menjadi alias alfanumerik, diawali dengan “#”. |
| mesejTeks | 1600 | Kandungan mesej SMS. |
6.3 Parameter permintaan pilihan (untuk penggunaan lanjutan)
| Nama | Panjang maksimum | Penerangan |
| originatingAddress | 16 | Alamat asal untuk mesej SMS keluar. Jenis alamat asal ditentukan oleh parameter originatorTON. Panjang maksimum nombor pendek ialah 16. Pengirim angka alfa terhad kepada Abjad lalai GSM dengan panjang maksimum 11 aksara. Panjang maksimum pengirim MSISDN ialah 15 (menggunakan format yang sama seperti elemen destinationAddress). Boleh diabaikan apabila originatingAddress dan originatingTON dipilih oleh sistem. Fungsi ini bergantung kepada pasaran dan konfigurasi. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| pemulaTON | 1 | Jenis nombor alamat asal (TON): 0 – Nombor pendek 1 – Angka alfa (panjang maksimum 11) 2 – MSISDN Boleh diabaikan apabila originatingAddress dan originatingTON akan dipilih oleh sistem. Fungsi ini bergantung kepada pasaran dan konfigurasi. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| userDataHeader | 280 | Pengepala Data Pengguna bersama-sama dengan Data Pengguna boleh mengandungi sehingga 140, iaitu 280 apabila dikodkan heks, oktet. Parameter ini sentiasa dikodkan heks. |
| DCS | 3 | Skim pengekodan data. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| PID | 3 | ID Protokol. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| relativeValidityTime | 6 | Masa kesahan relatif dalam beberapa saat (berbanding dengan masa untuk penyerahan kepada LINK Mobility). Nilai maksimum ialah 604800 (7 hari) dan lalai ialah 48 jam. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| masa penghantaran | 20 | Masa Terkiniamp bila mesej SMS harus dihantar (masa penghantaran tertunda). Lihat bahagian pada format masa tarikh. |
| statusReportFlags | 1 | Hantar permintaan laporan: 0 – Tiada laporan penghantaran (lalai) 1 – Laporan penghantaran diminta 9 – Laporan penghantaran pelayan diminta (LINK Mobility tidak memajukan laporan kepada Pembekal Perkhidmatan tetapi menyediakannya dalam laporan dll.) |
| campaignName | 50 | Urus niaga Mobiliti LINK ialah tagged dengan nama ini. Ia digunakan untuk mengumpulkan transaksi dalam laporan Mobiliti Pautan. |
| maxConcatenatedMessages | 1 | Nilai antara 1 dan 10 yang mentakrifkan bilangan mesej bercantum yang dibenarkan. Lalai ialah 3. |
| korelasiId | 100 | ID yang diberikan oleh Pembekal Perkhidmatan yang akan digemakan dalam Laporan Penghantaran. |
| nama pengguna | 100 | Disediakan sebagai alternatif kepada Pengesahan Asas HTTP. |
| kata laluan | 100 | Disediakan sebagai alternatif kepada Pengesahan Asas HTTP. |
6.4 Kaedah Permintaan HTTP
Untuk kebolehoperasian maksimum, API menyokong kaedah permintaan HTTP GET dan POST. Tiada kaedah HTTP lain dibenarkan.
6.4.1 DAPATKAN
Rentetan pertanyaan yang dikodkan dilampirkan pada URL.
DAPATKAN
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Hello+World%21
Keizinan: Asas am9objpjaGFuZ2VtZSA=
6.4.2 JAWATAN
Rentetan pertanyaan yang dikodkan diserahkan dalam badan mesej permintaan HTTP. Jenis Kandungan ialah aplikasi/x-www-form-urldikodkan.
POS https://europe.ipx.com/restapi/v1/sms/send
Hos: europe.ipx.com
Jenis Kandungan: aplikasi / x-www-form-urldikodkan
Keizinan: Asas am9objpjaGFuZ2VtZSA=
Panjang Kandungan: 57
destinationAddress=46123456789&messageText=Hello+World%21
6.5 Tarikh dan masa
Parameter dalam REST API yang mewakili tarikh dan masa sentiasa berada dalam zon waktu UTC (Waktu Sejagat Selaras). Masaamps diwakili sebagai rentetan dengan format tepat ini:
2017-04-25T23:20:50Z
Ini mewakili 20 minit dan 50 saat selepas jam ke-23 pada 25 April 2017 di UTC.
7. Mesej respons
Selepas menerima dan mentafsir mesej permintaan, API bertindak balas dengan mesej respons HTTP.
7.1 Kod status HTTP
API REST sentiasa mengembalikan kod status HTTP 200 OK untuk permintaan yang diproses. Badan mesej mengandungi Kod respons parameter yang digunakan untuk menentukan hasil yang tepat.
7.2 Isi mesej
Badan mesej terdiri daripada JSON yang menerangkan hasil permintaan.
http://json.org/
Pautan Mobiliti JSON mematuhi Panduan Gaya JSON Google.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Parameter tindak balas
| Nama | Panjang maksimum | Penerangan |
| kod respons | 3 | 0 menunjukkan transaksi yang berjaya. |
| responsMesej | 255 | Penerangan teks respons, cth teks ralat. |
| masaamp | 20 | Tarikh & masa apabila LINK Mobility memproses permintaan. (Rujuk bahagian format tarikh/masa). |
| traceId | 36 | Pengecam dalaman Mobiliti Pautan. Digunakan untuk sokongan dan penyelesaian masalah. |
| messageIds | 10 x 36 | Tatasusunan ID mesej unik Mobiliti LINK untuk setiap mesej yang berjaya (berbilang ID mesej dikembalikan jika mesej itu digabungkan). Diabaikan sekiranya berlaku kegagalan. |
7.4 Cthampjawapan le
Kejayaan
HTTP/1.1 200 OK
Jenis Kandungan: application/json
Panjang Kandungan: 144
Tarikh: Kha, 15 Sep 2016 13:20:31 GMT
{“Kod tindak balas”:0,”responseMessage”:”Kejayaan”,”masaamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Berikut ialah JSON yang sama diformatkan untuk kebolehbacaan:
{
“kod respons“:0,
“responsMesej“:”Kejayaan”,
“masaamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Kegagalan
HTTP/1.1 200 OK
Jenis Kandungan: application/json
Panjang Kandungan: 148
Tarikh: Kha, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Log masuk tidak sah atau penggunaan API yang tidak dibenarkan”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Kejayaan
HTTP/1.1 200 OK
Jenis Kandungan: application/json
Panjang Kandungan: 144
Tarikh: Kha, 15 Sep 2016 13:20:31 GMT
{“Kod tindak balas”:0,”responseMessage”:”Kejayaan”,”masaamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Berikut ialah JSON yang sama diformatkan untuk kebolehbacaan:
{
“kod respons“:0,
“responsMesej“:”Kejayaan”,
“masaamp“:”2016-0915T13:20:31Z”,
“traceId“:”f678d30879fd4adc25f2”,
“messageIds“:[“1-4850879008”] }
Kegagalan
HTTP/1.1 200 OK
Jenis Kandungan: application/json
Panjang Kandungan: 148
Tarikh: Kha, 15 Sep 2016 13:20:31 GMT
{“responseCode”:1,”responseMessage”:” Log masuk tidak sah atau penggunaan API yang tidak dibenarkan”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Kod tindak balas
Kod respons berikut boleh dikembalikan dalam respons hantar:
| Kod | Teks | Penerangan |
| 0 | Kejayaan | Berjaya dilaksanakan. |
| 1 | Log masuk tidak sah atau penggunaan API yang tidak dibenarkan | Nama pengguna atau kata laluan atau Pembekal Perkhidmatan yang salah dihalang oleh LINK Mobility. |
| 2 | Pengguna disekat oleh Link Mobility | Pengguna disekat oleh LINK Mobility. |
| 3 | Operasi tidak disediakan oleh LINK Mobility | Operasi disekat untuk Pembekal Perkhidmatan. |
| 4 | Pengguna tidak diketahui oleh LINK Mobility | Pengguna tidak diketahui oleh LINK Mobility. Atau jika alias digunakan dalam permintaan; alias tidak ditemui. |
| 5 | Pengguna telah menyekat perkhidmatan ini dalam LINK Mobility | Pengguna telah menyekat perkhidmatan ini dalam LINK Mobility. |
| 6 | Alamat asal tidak disokong | Alamat asal tidak disokong. |
| 7 | Alamat asal alfa tidak disokong oleh akaun | Alamat asal alfa tidak disokong oleh akaun. |
| 8 | Alamat asal MSISDN tidak disokong | Alamat asal MSISDN tidak disokong. |
| 9 | GSM dilanjutkan tidak disokong | GSM dilanjutkan tidak disokong. |
| 10 | Unicode tidak disokong | Unicode tidak disokong. |
| 11 | Laporan status tidak disokong | Laporan status tidak disokong. |
| 12 | Keupayaan yang diperlukan tidak disokong | Keupayaan yang diperlukan (selain daripada di atas) untuk menghantar mesej tidak disokong. |
| 13 | Kadar pendikit maks pembekal kandungan telah melebihi | Pembekal Perkhidmatan menghantar mesej SMS ke LINK Mobility terlalu pantas. |
| 14 | ID Protokol tidak disokong oleh akaun | ID Protokol tidak disokong. |
| 15 | Had penggabungan mesej melebihi had | Bilangan mesej bercantum melebihi bilangan maksimum yang diminta. |
| 16 | Tidak dapat menghalakan mesej. | LINK Mobility tidak dapat menghalakan mesej. |
| 17 | Tempoh masa yang dilarang | Tidak dibenarkan menghantar mesej dalam tempoh masa |
| 18 | Baki terlalu rendah pada akaun pembekal perkhidmatan | Pembekal perkhidmatan disekat kerana baki Terlalu rendah |
| 50 | Kejayaan separa | Kejayaan separa apabila menghantar mesej SMS kepada berbilang penerima. |
| 99 | Ralat pelayan dalaman | Ralat Mobiliti Pautan lain, hubungi sokongan Mobiliti LINK untuk mendapatkan maklumat lanjut. |
| 100 | Alamat destinasi tidak sah | Alamat destinasi (MSISDN, atau alias) tidak sah. |
| 102 | ID yang dirujuk (dipautkan) tidak sah | ID rujukan tidak sah, mungkin ID rujukan sudah digunakan, terlalu lama atau tidak diketahui. |
| 103 | Nama akaun tidak sah | Nama akaun tidak sah. |
| 105 | Data meta perkhidmatan tidak sah | Data meta perkhidmatan tidak sah. |
| 106 | Alamat asal tidak sah | Alamat asal tidak sah. |
| 107 | Alamat asal abjad angka tidak sah | Alamat asal alfanumerik tidak sah. |
| 108 | Masa sah tidak sah | Masa sah tidak sah. |
| 109 | Masa penghantaran tidak sah | Masa penghantaran tidak sah. |
| 110 | Kandungan mesej/data pengguna tidak sah | Data pengguna, iaitu mesej SMS, adalah tidak sah. |
| 111 | Panjang mesej tidak sah | Panjang mesej SMS tidak sah. |
| 112 | Pengepala data pengguna tidak sah | Pengepala data pengguna tidak sah. |
| 113 | Skim pengekodan data tidak sah | DCS tidak sah. |
| 114 | ID protokol tidak sah | PID tidak sah. |
| 115 | Bendera laporan status tidak sah | Bendera laporan status tidak sah. |
| 116 | TON tidak sah | TON pemula tidak sah. |
| 117 | Tidak sah campnama aign | campnama aign tidak sah. |
| 120 | Had tidak sah untuk bilangan maksimum mesej yang digabungkan | Bilangan maksimum mesej yang digabungkan adalah tidak sah. |
| 121 | Alamat asal msisdn tidak sah | Alamat asal MSISDN adalah tidak sah. |
| 122 | ID korelasi tidak sah | ID korelasi tidak sah. |
8. Ciri pilihan
8.1 Pembetulan MSISDN
Pembetulan MSISDN ialah ciri pilihan yang boleh didayakan oleh sokongan Mobiliti LINK jika diminta.
Ciri ini akan membetulkan alamat destinasi dan menjajarkannya dengan format E.164 yang diperlukan. Selain pembetulan format, sistem juga boleh melaksanakan fungsi khusus pasaran seperti menterjemah nombor Perancis antarabangsa untuk membetulkan nombor DOM-TOM (départements et territoires d'outre-mer) apabila berkenaan.
Di bawah adalah beberapa bekasampsedikit pembetulan:
| Alamat Destinasi yang Diserahkan | Alamat Destinasi yang Dibetulkan |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Nombor Perancis diterjemahkan kepada nombor DOM-TOM) |
Selain itu, adalah mungkin untuk membenarkan nombor telefon nasional untuk pasaran terpilih. Apabila ciri ini didayakan, sebarang nombor antarabangsa untuk pasaran lain mesti dihantar dengan tanda awal `+' untuk membezakannya daripada pasaran yang dipilih.
Di bawah adalah beberapa bekasampsedikit pembetulan dilakukan apabila menggunakan Sweden (kod negara 46) sebagai pasaran lalai untuk nombor negara.
| Alamat Destinasi yang Diserahkan | Alamat Destinasi yang Dibetulkan |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Tidak sah kerana tanda '+' tiada |
Ambil perhatian bahawa MSISDN yang diperbetulkan akan digunakan oleh LINK Mobility dan ia akan dikembalikan dalam laporan penghantaran.
Sila hubungi sokongan Mobiliti LINK untuk mendapatkan maklumat lanjut.
8.2 Penggantian Aksara
Penggantian aksara ialah ciri pilihan yang boleh didayakan oleh sokongan Mobiliti LINK jika diminta.
Ciri ini akan menterjemah aksara abjad bukan GSM dalam data pengguna (teks SMS) kepada aksara abjad GSM yang setara apabila DCS ditetapkan kepada "GSM" (17). Untuk example “Seqüência de teste em Português” akan diterjemahkan kepada “Seqüencia de teste em Portugues”.
9. Laporan penghantaran
Pembekal Perkhidmatan boleh, jika diperuntukkan, meminta laporan penghantaran mesej SMS atau pemberitahuan penghantaran untuk mesej MT yang dihantar. Laporan ini dicetuskan dalam SMSC Operator apabila mesej MT sama ada dihantar kepada Pengguna yang disasarkan atau dipadamkan, contohnya, tamat tempoh atau, atas sebab tertentu, tidak boleh dialihkan.
Hanya status akhir mesej SMS dilaporkan kepada Pembekal Perkhidmatan, iaitu, dihantar atau dipadamkan. Hanya satu laporan bagi setiap mesej MT dijana. Dengan status yang dipadamkan, kod sebab mungkin dikenakan. Kod sebab ini menentukan sebab mesej SMS tidak dihantar.
Laporan dihalakan melalui LINK Mobility dan dihantar kepada Pembekal Perkhidmatan menggunakan protokol HTTP.
Untuk menerima laporan, Pembekal Perkhidmatan perlu melaksanakan untuk exampdengan Java Servlet atau halaman ASP.NET. Kedua-duanya menerima permintaan HTTP GET atau POST.
Parameter
Permintaan termasuk parameter berikut:
| Parameter | taip | M/O/I* | Nilai Lalai | Panjang maksimum | Penerangan |
| MessageId | rentetan | M | – | 22 | ID mesej mesej MT yang sepadan dengan laporan ini. |
| Alamat Destinasi | rentetan | M | – | 40 | MSISDN Pengguna, iaitu alamat destinasi mesej MT asal. |
| Kod Status | integer | M | 1 | Kod status menunjukkan status mesej MT. Kod status yang berkenaan ialah: 0 – Dihantar 2 – Dipadamkan (kod sebab dikenakan) |
|
| MasaStamp | rentetan | M | – | 20 | Masa menunjukkan bila laporan penghantaran diterima oleh LINK Mobility. Zon waktu paling kerapamp ialah CET atau CEST (dengan masa musim panas seperti yang ditakrifkan untuk EU). Format: yyyyMMdd HH:mm:ss. |
| Operator | rentetan | M | – | 100 | Nama Operator yang digunakan semasa menghantar mesej SMS atau nama akaun yang digunakan semasa menghantar mesej SMS. Senarai Operator yang tersedia disediakan oleh sokongan Mobility LINK. |
| Kod Sebab | integer | O | – | 3 | Kod sebab menunjukkan mengapa mesej itu berakhir dalam status yang dipadamkan. Kod sebab yang boleh digunakan ialah: 100 – Tamat tempoh 101 – Ditolak 102 – Ralat format 103 – Ralat lain 110 – Pelanggan tidak diketahui 111 – Pelanggan dihalang 112 – Pelanggan tidak diperuntukkan 113 – Pelanggan tidak tersedia 120 – Kegagalan SMSC 121 – Kesesakan SMSC 122 – Perayauan SMSC 130 – Ralat telefon bimbit 131 – Memori telefon bimbit melebihi Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| OperatorTimeStamp | rentetan | O | – | 20 | Masa yang menunjukkan bila laporan dicetuskan dalam SMSC Operator (jika disediakan oleh Operator). Zon waktu paling kerapamp ialah CET atau CEST (dengan masa musim panas seperti yang ditakrifkan untuk EU). Format: yyyyMMdd HH:mm:ss. |
| Teks Status | rentetan | O | – | 255 | Pemegang tempat untuk mendapatkan maklumat tambahan daripada Operator, cth penerangan teks yang jelas tentang status/sebab. Tingkah laku mungkin berbeza dengan penyepaduan Operator. |
| CorrelationId | rentetan | O | – | 100 | ID korelasi yang disediakan dalam SendRequest atau SendTextRequest. |
| Kod Rangkaian Operator | integer | O | – | 6 | Kod Rangkaian Mudah Alih (MCC + MNC) Operator. |
* M = Wajib, O = Pilihan, I = Diabaikan.
Pembekal Perkhidmatan perlu menyediakan LINK Mobility dengan sasaran URL untuk laporan penghantaran (sebagai pilihan termasuk bukti kelayakan untuk pengesahan asas HTTP). Pembekal Perkhidmatan boleh memilih kaedah HTTP pilihan untuk digunakan:
HTTP POST (disyorkan)
HTTP GET.
Exampmenggunakan HTTP GET (berjaya dihantar):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Exampmenggunakan HTTP GET (tidak dihantar, Operator telah membekalkan masaamp untuk acara tersebut):
Parameternya ialah URL encodedi.
Pengekodan aksara:
Pembekal Perkhidmatan boleh memilih pengekodan aksara pilihan untuk digunakan:
UTF-8 (disyorkan)
ISO-8859-1.
9.1 Pengakuan Pembekal Perkhidmatan
Pembekal Perkhidmatan harus mengakui setiap laporan penghantaran. Pengakuan boleh positif, iaitu laporan penghantaran berjaya diterima, atau negatif, iaitu kegagalan.
Sila ambil perhatian: LINK Mobility mempunyai tamat masa baca untuk pengakuan 30 saat untuk laporan penghantaran. Tamat masa akan mencetuskan percubaan semula penghantaran (jika cuba semula didayakan) atau pembatalan penghantaran (jika cuba semula dilumpuhkan). Ini bermakna aplikasi Pembekal Perkhidmatan mesti memastikan masa tindak balas yang cepat, terutamanya semasa beban tinggi.
Adalah amat disyorkan untuk mengakui laporan penghantaran ke arah LINK Mobility sebelum memprosesnya.
Peraturan untuk pengakuan positif dan negatif diterangkan seperti berikut:
Pengakuan positif, ACK, laporan penghantaran dihantar:
Kod tindak balas julat HTTP 200 dalam kombinasi dengan kandungan berformat XML berikut:
Pengakuan negatif, NAK, laporan penghantaran tidak dihantar:
Sebarang balasan selain daripada pengakuan positif, contohnyaampOleh itu, pengakuan negatif dicetuskan oleh sebarang kod ralat HTTP atau kandungan XML berikut:
Kandungan XML boleh digunakan untuk mengawal mekanisme percubaan semula Mobiliti LINK. NAK akan menyebabkan percubaan cuba semula, jika didayakan. Bagi Pembekal Perkhidmatan yang tidak dikonfigurasikan untuk mekanisme cuba semula, kandungan XML adalah pilihan.
Di bawah ialah permintaan HTTP POST dan respons cthampsatu laporan penghantaran yang dihantar kepada Pembekal Perkhidmatan:
Permintaan HTTP:
POST /context/app HTTP/1.1
Jenis Kandungan: aplikasi / x-www-form-urldikodkan;charset=utf-8
Hos: pelayan:port
Panjang Kandungan: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
Respons HTTP:
HTTP/1.1 200 OK
Jenis Kandungan: teks/biasa
9.2 Cuba semula
Sistem Mobiliti LINK boleh melakukan percubaan cuba semula untuk penghantaran laporan penghantaran yang gagal, iaitu tidak diakui. Pembekal Perkhidmatan boleh memilih tingkah laku cuba semula pilihan:
Jangan cuba semula (lalai) – mesej akan dibuang jika percubaan sambungan gagal, tamat masa baca atau untuk sebarang kod ralat HTTP.
Cuba semula – mesej akan dihantar semula untuk setiap jenis masalah sambungan, tamat masa baca atau pengakuan negatif.
Apabila cuba semula untuk NAK didayakan, adalah penting untuk memahami senario yang akan menjana percubaan cuba semula daripada LINK Mobility dan cara percubaan semula berfungsi. Setiap Pembekal Perkhidmatan mempunyai baris gilir cuba semula sendiri, di mana mesej dipesan mengikut masa mesejamp. Mobility Pautan sentiasa cuba menghantar mesej lama dahulu, walaupun pesanan individu mesej yang dihantar kepada Pembekal Perkhidmatan tidak dijamin. Sebab utama mesej dibuang daripada baris gilir cuba semula ialah salah satu daripada dua sebab: sama ada mesej TTL tamat tempoh atau (secara teorinya) baris gilir cuba semula menjadi penuh. TTL adalah Operator dan bergantung kepada akaun, iaitu, boleh berbeza-beza bergantung pada Operator dan atau jenis mesej, contohnya, SMS premium atau mesej SMS kadar standard.
Pembekal Perkhidmatan dengan cuba semula didayakan mesti menyemak ID unik mesej MT untuk memastikan bahawa mesej itu belum diterima.
Pembekal Perkhidmatan adalah penting untuk mematuhi peraturan mudah ini apabila ralat berlaku semasa pemprosesan laporan penghantaran jika sebab ralat adalah: Sementara, cth pangkalan data tidak tersedia, NAK harus dikembalikan. LINK Mobility akan menghantar semula mesej.
Percubaan kekal dan percubaan semula mungkin menyebabkan masalah yang sama, ACK harus dikembalikan. Untuk example, apabila mesej tidak dapat dihuraikan dengan betul atau menyebabkan ralat masa jalan yang tidak dijangka.
Bertindak sewajarnya akan memastikan tiada sekatan atau kemerosotan daya pemprosesan disebabkan oleh laporan penghantaran dihantar berulang kali.
10. Petua pelaksanaan
1. Ia adalah mungkin untuk menggunakan anda web penyemak imbas untuk menyerahkan permintaan kepada API. Ini menjadikannya sangat mudah untuk meneroka dan menilai perkhidmatan tanpa sebarang alat pembangunan.
2. Chrome atau Firefox disyorkan bersama-sama dengan sambungan seperti JSONView untuk memaparkan JSON berformat cantik.
3. Kami telah menggunakan SoapUI untuk menguji POST, Pengesahan Asas dan untuk memeriksa permintaan HTTP mentah dan mesej respons.
4. cURL alat berguna untuk menghantar permintaan POST dengan Pengesahan Asas. Lihat bekasample di bawah.
curl SIARAN \
-H "Jenis-Kandungan: permohonan/x-www-borang-urldikodkan” \
-H “Kebenaran: Asas am9objpjaGFuZ2VtZSA=” \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Hello+World%21”
_______________
Mengubah Komunikasi Peribadi
Dokumen / Sumber
 |
Panduan Pelaksanaan Mobiliti LINK REST API SMS [pdf] Panduan Pengguna Panduan Pelaksanaan Mobiliti REST API SMS, Mobiliti, Panduan Pelaksanaan REST API SMS, REST API SMS, API SMS, SMS |
