Hướng dẫn triển khai LINK Mobility REST API SMS
LINK Mobility cung cấp dịch vụ chuyển phát tin nhắn, thanh toán vi mô và dịch vụ dựa trên vị trí. Nền tảng này hoạt động như một đơn vị thu thập nội dung nhãn trắng minh bạch và là bộ định tuyến giao dịch giữa Nhà cung cấp dịch vụ và Nhà điều hành.
LINK Mobility cung cấp API RESTful có thể được sử dụng để truy cập các dịch vụ LINK Mobility như gửi SMS. API này được thiết kế để dễ sử dụng và tương thích với tất cả các ngôn ngữ và khuôn khổ hiện đại. Sử dụng ngôn ngữ bạn chọn, ứng dụng của bạn có thể sử dụng API REST của Link Mobility để triển khai các khả năng nhắn tin và thanh toán mạnh mẽ
© LINK Mobility, ngày 10 tháng 2021 năm XNUMX
Thông tin pháp lý
Thông tin được cung cấp trong tài liệu này là tài sản và bản quyền duy nhất của Netsize. Tài liệu này được bảo mật và chỉ dùng cho mục đích thông tin. Tài liệu này không mang tính ràng buộc và có thể thay đổi mà không cần thông báo. Bất kỳ việc tiết lộ hoặc sử dụng trái phép nào đều được coi là bất hợp pháp.
Netsize™ và linkmobility™ được bảo vệ bởi luật sở hữu trí tuệ của Pháp, EEC và quốc tế.
Mọi nhãn hiệu khác được trích dẫn đều là tài sản riêng của chủ sở hữu tương ứng.
Không có nội dung nào ở đây được hiểu là cấp bất kỳ giấy phép hoặc quyền nào theo bằng sáng chế, bản quyền hoặc nhãn hiệu của Netsize.
KÍCH THƯỚC MẠNG
Société anonyme au Capital de 5 478 070 euro
Siège social :62, đại lộ Emile Zola92100 Boulogne – Pháp
418 712 477 RCS Nanterre
http://www.LinkMobility.com
http://www.linkmobility.com
Phạm vi tài liệu
Tài liệu này mô tả cách Nhà cung cấp dịch vụ sử dụng LINK Mobility REST API cho SMS. Tài liệu này dành cho các kiến trúc sư và nhà thiết kế kỹ thuật triển khai các dịch vụ của Nhà cung cấp dịch vụ.
1. Cách sử dụng cơ bản
Rất dễ dàng để gửi một tin nhắn SMS. Bạn gửi một yêu cầu HTTP đến LINK Mobility có thể được thực hiện chỉ bằng cách sử dụng web trình duyệt.
2. Hết chức năngview
Hệ thống LINK Mobility cung cấp các chức năng cơ bản sau cho tin nhắn SMS:
Gửi tin nhắn SMS kết thúc qua di động (MT), chẳng hạn như tin nhắn văn bản hoặc nhị phân (ví dụ: WAP Push) với mức phí bảo hiểm và mức phí chuẩn.
Nhận báo cáo phân phối cho các tin nhắn MT đã gửi.
Nhận tin nhắn SMS từ di động (MO), mức phí cao cấp và mức phí tiêu chuẩn.
SMS REST API được dùng để gửi tin nhắn SMS MT với tốc độ chuẩn.
API gửi tất cả tin nhắn SMS theo cách không đồng bộ, cho phép các tính năng như:
“Bắn và quên” – Nhà cung cấp dịch vụ muốn có thời gian phản hồi có thể dự đoán được hơn và không muốn chờ kết quả từ Nhà điều hành.
Chức năng thử lại – LINK Mobility sẽ gửi lại tin nhắn nếu Nhà điều hành gặp sự cố tạm thời.
2.1 Gửi tin nhắn SMS
Nhà cung cấp dịch vụ Netsize Người tiêu dùng
- Gửi tin nhắn MT
- Trả về ID tin nhắn
- Gửi tin nhắn SMS
- Báo cáo giao hàng
- Gửi báo cáo giao hàng
Luồng cơ bản để gửi tin nhắn SMS được mô tả như sau:
Nhà cung cấp dịch vụ gửi yêu cầu gửi tin nhắn SMS đến người nhận thông qua hệ thống LINK Mobility.
Một ID tin nhắn được trả về Nhà cung cấp dịch vụ. ID này có thể được sử dụng để ví dụ như đối chiếu tin nhắn với báo cáo phân phối chính xác.
LINK Mobility xử lý việc định tuyến và gửi tin nhắn SMS đến Người tiêu dùng được chỉ định.
Báo cáo gửi sẽ được kích hoạt, ví dụ khi tin nhắn SMS được gửi đến thiết bị của Người tiêu dùng.
Báo cáo giao hàng được gửi đến Nhà cung cấp dịch vụ. Báo cáo chứa cùng ID tin nhắn như được trả về ở bước 2.
Luồng thay thế: Yêu cầu không hợp lệ
Nếu các tham số hoặc thông tin đăng nhập người dùng được cung cấp trong yêu cầu không hợp lệ, lỗi sẽ được trả về Nhà cung cấp dịch vụ. Lỗi sẽ chỉ ra lý do từ chối và luồng kết thúc. Không có ID tin nhắn nào được trả về.
3. Điểm cuối
Có thể truy cập tài nguyên SMS bằng đường dẫn:
/restapi/v1/tin nhắn
Example URL
https://europe.ipx.com/restapi/v1/sms
Để bảo mật kết nối, LINK Mobility REST API chỉ có thể truy cập qua HTTPS.
Chứng chỉ máy chủ Link Mobility được ký bởi Thawte Server CA.
4. Hoạt động
Dịch vụ SMS cung cấp các hoạt động sau:
| Tên | Con đường |
| Gửi | /restapi/v1/sms/gửi |
4.1 Gửi
Thao tác gửi được sử dụng để gửi tin nhắn SMS đến một người nhận duy nhất.
Hoạt động này dành cho cả người dùng cơ bản và nâng cao. Trong trường hợp đơn giản nhất, chỉ cần địa chỉ đích và văn bản tin nhắn để gửi tin nhắn SMS. LINK Mobility sẽ phát hiện Sơ đồ mã hóa dữ liệu và thực hiện tự động nối một tin nhắn thành nhiều phần tin nhắn nếu cần.
Đối với mục đích sử dụng nâng cao, Nhà cung cấp dịch vụ có thể sử dụng các tham số tùy chọn để kiểm soát hoàn toàn định dạng tin nhắn bao gồm cả tiêu đề dữ liệu người dùng.
Nhà cung cấp dịch vụ có thể gửi các tin nhắn nối tiếp nhau, nhưng việc chuẩn bị dữ liệu người dùng và tiêu đề dữ liệu người dùng phải được thực hiện bởi Nhà cung cấp dịch vụ và tin nhắn phải được gửi bằng nhiều yêu cầu gửi tới LINK Mobility.
5. Xác thực
Tên người dùng và mật khẩu được gửi trong mọi yêu cầu bằng cách sử dụng Giao thức xác thực cơ bản HTTP.
https://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA
Thông tin xác thực được gửi trong tiêu đề Authorization trong yêu cầu HTTP. Máy khách xây dựng trường tiêu đề như mô tả ở đây:
https://en.wikipedia.org/wiki/Basic_access_authentication#Client_side
Ví dụample, nếu tên người dùng là john và changeme là mật khẩu thì tiêu đề Authorization kết quả là:
Quyền hạn: Cơ bản am9objpjaGFuZ2VtZSA=
Để dự phòng, tên người dùng và mật khẩu có thể được gửi dưới dạng tham số yêu cầu. Điều này chỉ được khuyến nghị cho các máy khách không hỗ trợ Xác thực cơ bản.
6. Gửi yêu cầu
6.1 Chuỗi truy vấn
Các tham số yêu cầu được gửi dưới dạng chuỗi truy vấn chứa các cặp tên/giá trị. Chuỗi truy vấn được mã hóa bằng Percent Encoding (URL mã hóa).
http://www.w3schools.com/tags/ref_urlencode.asp
Ví dụample, Hello World! được mã hóa thành Hello+World%21.
6.2 Tham số yêu cầu bắt buộc
| Tên | Chiều dài tối đa | Sự miêu tả |
| Địa chỉ đích | 40 | MSISDN mà tin nhắn SMS sẽ được gửi đến, bắt đầu bằng mã quốc gia. Ví dụample: 46123456789. Đối với một số thị trường (nơi mà Consumer MSISDN phải được ẩn đi), giá trị này cũng có thể là bí danh chữ số, có tiền tố là “#”. |
| tin nhắnVăn bản | 1600 | Nội dung tin nhắn SMS. |
6.3 Các tham số yêu cầu tùy chọn (để sử dụng nâng cao)
| Tên | Chiều dài tối đa | Sự miêu tả |
| Địa chỉ gốc | 16 | Địa chỉ gốc cho tin nhắn SMS gửi đi. Loại địa chỉ gốc được xác định bởi tham số originatorTON. Số ngắn có độ dài tối đa là 16. Bộ gửi số chữ cái bị giới hạn ở bảng chữ cái mặc định của GSM với độ dài tối đa là 11 ký tự. Độ dài tối đa của người gửi MSISDN là 15 (sử dụng cùng định dạng với phần tử destinationAddress). Có thể bỏ qua khi originsAddress và originsTON được hệ thống chọn. Chức năng này phụ thuộc vào thị trường và cấu hình. Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| người khởi tạoTON | 1 | Loại số của địa chỉ gốc (TON): 0 – Số ngắn 1 – Chữ số chữ cái (độ dài tối đa 11) 2 – MSISDN Có thể bỏ qua khi originsAddress và originsTON sẽ được hệ thống chọn. Chức năng này phụ thuộc vào thị trường và cấu hình. Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| người dùngDataHeader | 280 | Tiêu đề dữ liệu người dùng cùng với Dữ liệu người dùng có thể chứa tới 140, tức là 280 khi được mã hóa hex, octet. Tham số này luôn được mã hóa hex. |
| DCS | 3 | Sơ đồ mã hóa dữ liệu. Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| Mã số thuế | 3 | ID giao thức. Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| thời gian hiệu lực tương đối | 6 | Thời gian hiệu lực tương đối tính bằng giây (so với thời gian gửi đến LINK Mobility). Giá trị tối đa là 604800 (7 ngày) và mặc định là 48 giờ. Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| Thời gian giao hàng | 20 | Thời gianamp khi nào tin nhắn SMS sẽ được gửi (thời gian gửi chậm). Xem phần về định dạng ngày giờ. |
| trạng tháiBáo cáoCờ | 1 | Gửi yêu cầu báo cáo: 0 – Không có báo cáo giao hàng (mặc định) 1 – Yêu cầu báo cáo giao hàng 9 – Yêu cầu báo cáo chuyển giao máy chủ (LINK Mobility không chuyển tiếp báo cáo cho Nhà cung cấp dịch vụ nhưng cung cấp báo cáo trong các báo cáo, v.v.) |
| campTên đăng nhập | 50 | Các giao dịch LINK Mobility là tagđược tạo bằng tên này. Nó được sử dụng để nhóm các giao dịch trong báo cáo Liên kết di động. |
| maxConcatenatedMessages | 1 | Giá trị từ 1 đến 10 xác định số lượng tin nhắn được nối tiếp được phép. Mặc định là 3. |
| tương quanId | 100 | ID do Nhà cung cấp dịch vụ cung cấp sẽ được phản ánh trong Báo cáo giao hàng. |
| tên người dùng | 100 | Được cung cấp như một giải pháp thay thế cho Xác thực cơ bản HTTP. |
| mật khẩu | 100 | Được cung cấp như một giải pháp thay thế cho Xác thực cơ bản HTTP. |
6.4 Phương pháp yêu cầu HTTP
Để có khả năng tương tác tối đa, API hỗ trợ cả phương thức yêu cầu HTTP GET và POST. Không cho phép bất kỳ phương thức HTTP nào khác.
6.4.1 NHẬN
Chuỗi truy vấn được mã hóa được thêm vào URL.
LẤY
https://europe.ipx.com/restapi/v1/sms/send?destinationAddress=461234
56789&messageText=Xin+vui+Thế+giới%21
Quyền hạn: Cơ bản am9objpjaGFuZ2VtZSA=
6.4.2 BÀI ĐĂNG
Chuỗi truy vấn được mã hóa được gửi trong nội dung tin nhắn yêu cầu HTTP. Content-Type là application/x-www-form-urlđược mã hóa.
BƯU KIỆN https://europe.ipx.com/restapi/v1/sms/send
Máy chủ: europe.ipx.com
Nội dung-Loại: ứng dụng / x-www-form-urlđược mã hóa
Quyền hạn: Cơ bản am9objpjaGFuZ2VtZSA=
Nội dung-Độ dài: 57
destinationAddress=46123456789&messageText=Xin chào thế giới%21
6.5 Ngày và giờ
Các tham số trong REST API biểu thị ngày và giờ luôn theo múi giờ UTC (Giờ Phối hợp Quốc tế). Timestampđược biểu diễn dưới dạng một chuỗi có định dạng chính xác như sau:
2017-04-25T23:20:50Z
Tức là 20 phút và 50 giây sau giờ thứ 23 của ngày 25 tháng 2017 năm XNUMX theo giờ UTC.
7. Tin nhắn phản hồi
Sau khi nhận và diễn giải tin nhắn yêu cầu, API sẽ phản hồi bằng tin nhắn phản hồi HTTP.
7.1 Mã trạng thái HTTP
REST API luôn trả về mã trạng thái HTTP 200 OK cho các yêu cầu đã xử lý. Nội dung tin nhắn chứa tham số responseCode được sử dụng để xác định kết quả chính xác.
7.2 Nội dung tin nhắn
Nội dung tin nhắn bao gồm JSON mô tả kết quả của yêu cầu.
http://json.org/
Link Mobility JSON tuân thủ theo Hướng dẫn về phong cách JSON của Google.
https://google.github.io/styleguide/jsoncstyleguide.xml
7.3 Tham số phản hồi
| Tên | Chiều dài tối đa | Sự miêu tả |
| Mã phản hồi | 3 | 0 biểu thị giao dịch thành công. |
| phản hồiTin nhắn | 255 | Mô tả văn bản phản hồi, ví dụ văn bản lỗi. |
| thời gianamp | 20 | Ngày và giờ LINK Mobility xử lý yêu cầu. (Tham khảo phần định dạng ngày/giờ). |
| theo dõiId | 36 | Mã định danh nội bộ của Link Mobility. Được sử dụng để hỗ trợ và khắc phục sự cố. |
| tin nhắnId | 10 x36 | Mảng ID tin nhắn duy nhất của LINK Mobility cho mỗi tin nhắn thành công (nhiều ID tin nhắn được trả về nếu tin nhắn được nối lại). Bỏ qua trong trường hợp thất bại. |
7.4 Ví dụampphản hồi
Thành công
HTTP/1.1 200 Đồng ý
Loại nội dung: ứng dụng/json
Nội dung-Độ dài: 144
Ngày: Thứ năm, 15 tháng 2016 năm 13 20:31:XNUMX GMT
{“responseCode”:0,”responseMessage”:”Thành công”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Dưới đây là định dạng JSON tương tự để dễ đọc:
{
“Mã phản hồi“:0,
“phản hồiTin nhắn":"Thành công",
“thời gianamp“:”2016-0915T13:20:31Z”,
“theo dõiId“:”f678d30879fd4adc25f2”,
“tin nhắnId“:[“1-4850879008”] }
Sự thất bại
HTTP/1.1 200 Đồng ý
Loại nội dung: ứng dụng/json
Nội dung-Độ dài: 148
Ngày: Thứ năm, 15 tháng 2016 năm 13 20:31:XNUMX GMT
{“responseCode”:1,”responseMessage”:” Đăng nhập không hợp lệ hoặc sử dụng API không được phép”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
Thành công
HTTP/1.1 200 Đồng ý
Loại nội dung: ứng dụng/json
Nội dung-Độ dài: 144
Ngày: Thứ năm, 15 tháng 2016 năm 13 20:31:XNUMX GMT
{“responseCode”:0,”responseMessage”:”Thành công”,”timestamp”:”2016-09-15T13:20:31Z”, “traceId”:”f678d30879fd4adc25f2″,”messageIds”:[“1-4850879008”]}
Dưới đây là định dạng JSON tương tự để dễ đọc:
{
“Mã phản hồi“:0,
“phản hồiTin nhắn":"Thành công",
“thời gianamp“:”2016-0915T13:20:31Z”,
“theo dõiId“:”f678d30879fd4adc25f2”,
“tin nhắnId“:[“1-4850879008”] }
Sự thất bại
HTTP/1.1 200 Đồng ý
Loại nội dung: ứng dụng/json
Nội dung-Độ dài: 148
Ngày: Thứ năm, 15 tháng 2016 năm 13 20:31:XNUMX GMT
{“responseCode”:1,”responseMessage”:” Đăng nhập không hợp lệ hoặc sử dụng API không được phép”,”timestamp”:”2016-09-15T13:20:31Z”,”traceId”:”f678d30879fd4adc25f2″}
7.5 Mã phản hồi
Các mã phản hồi sau đây có thể được trả về trong phản hồi gửi:
| Mã số | Chữ | Sự miêu tả |
| 0 | Thành công | Thực hiện thành công. |
| 1 | Đăng nhập không hợp lệ hoặc sử dụng API không được phép | Tên người dùng hoặc mật khẩu không đúng hoặc Nhà cung cấp dịch vụ sẽ bị LINK Mobility cấm. |
| 2 | Người tiêu dùng bị chặn bởi Link Mobility | Người tiêu dùng bị LINK Mobility chặn. |
| 3 | Hoạt động không được cung cấp bởi LINK Mobility | Hoạt động bị chặn đối với Nhà cung cấp dịch vụ. |
| 4 | Người tiêu dùng không biết đến LINK Mobility | Người tiêu dùng không biết đến LINK Mobility. Hoặc nếu bí danh được sử dụng trong yêu cầu; không tìm thấy bí danh. |
| 5 | Người tiêu dùng đã chặn dịch vụ này trong LINK Mobility | Người tiêu dùng đã chặn dịch vụ này trong LINK Mobility. |
| 6 | Địa chỉ gốc không được hỗ trợ | Địa chỉ gốc không được hỗ trợ. |
| 7 | Địa chỉ gốc Alpha không được tài khoản hỗ trợ | Tài khoản không hỗ trợ địa chỉ gốc alpha. |
| 8 | Địa chỉ gốc MSISDN không được hỗ trợ | Địa chỉ gốc MSISDN không được hỗ trợ. |
| 9 | GSM mở rộng không được hỗ trợ | Không hỗ trợ mở rộng GSM. |
| 10 | Unicode không được hỗ trợ | Unicode không được hỗ trợ. |
| 11 | Báo cáo trạng thái không được hỗ trợ | Báo cáo trạng thái không được hỗ trợ. |
| 12 | Khả năng yêu cầu không được hỗ trợ | Khả năng cần thiết (ngoài những khả năng trên) để gửi tin nhắn không được hỗ trợ. |
| 13 | Tỷ lệ giới hạn tối đa của nhà cung cấp nội dung đã vượt quá | Nhà cung cấp dịch vụ đang gửi tin nhắn SMS đến LINK Mobility quá nhanh. |
| 14 | ID giao thức không được tài khoản hỗ trợ | ID giao thức không được hỗ trợ. |
| 15 | Đã vượt quá giới hạn nối tin nhắn | Số lượng tin nhắn được nối vượt quá số lượng tối đa được yêu cầu. |
| 16 | Không thể định tuyến tin nhắn. | LINK Mobility không thể định tuyến tin nhắn. |
| 17 | Khoảng thời gian bị cấm | Không được phép gửi tin nhắn trong khoảng thời gian |
| 18 | Số dư quá thấp trên tài khoản nhà cung cấp dịch vụ | Nhà cung cấp dịch vụ bị chặn do số dư quá thấp |
| 50 | Thành công một phần | Thành công một phần khi gửi tin nhắn SMS tới nhiều người nhận. |
| 99 | Lỗi máy chủ nội bộ | Lỗi liên kết di động khác, hãy liên hệ với bộ phận hỗ trợ liên kết di động để biết thêm thông tin. |
| 100 | Địa chỉ đích không hợp lệ | Địa chỉ đích (MSISDN hoặc bí danh) không hợp lệ. |
| 102 | ID tham chiếu (liên kết) không hợp lệ | ID tham chiếu không hợp lệ, có thể ID tham chiếu đã được sử dụng, quá cũ hoặc không xác định. |
| 103 | Tên tài khoản không hợp lệ | Tên tài khoản không hợp lệ. |
| 105 | Siêu dữ liệu dịch vụ không hợp lệ | Siêu dữ liệu dịch vụ không hợp lệ. |
| 106 | Địa chỉ gốc không hợp lệ | Địa chỉ gốc không hợp lệ. |
| 107 | Địa chỉ gốc chữ số không hợp lệ | Địa chỉ gốc gồm chữ và số không hợp lệ. |
| 108 | Thời gian hiệu lực không hợp lệ | Thời hạn hiệu lực không hợp lệ. |
| 109 | Thời gian giao hàng không hợp lệ | Thời gian giao hàng không hợp lệ. |
| 110 | Nội dung tin nhắn/dữ liệu người dùng không hợp lệ | Dữ liệu người dùng, tức là tin nhắn SMS, không hợp lệ. |
| 111 | Độ dài tin nhắn không hợp lệ | Độ dài tin nhắn SMS không hợp lệ. |
| 112 | Tiêu đề dữ liệu người dùng không hợp lệ | Tiêu đề dữ liệu người dùng không hợp lệ. |
| 113 | Sơ đồ mã hóa dữ liệu không hợp lệ | DCS không hợp lệ. |
| 114 | ID giao thức không hợp lệ | PID không hợp lệ. |
| 115 | Cờ báo cáo trạng thái không hợp lệ | Cờ báo cáo trạng thái không hợp lệ. |
| 116 | TON không hợp lệ | Người khởi tạo TON không hợp lệ. |
| 117 | c không hợp lệamptên phù hợp | Cái camptên đăng nhập không hợp lệ. |
| 120 | Giới hạn không hợp lệ cho số lượng tối đa các tin nhắn được nối | Số lượng tin nhắn nối tiếp tối đa không hợp lệ. |
| 121 | Địa chỉ gốc msisdn không hợp lệ | Địa chỉ gốc MSISDN không hợp lệ. |
| 122 | ID tương quan không hợp lệ | ID tương quan không hợp lệ. |
8. Các tính năng tùy chọn
8.1 Sửa lỗi MSISDN
Tính năng chỉnh sửa MSISDN là tính năng tùy chọn có thể được hỗ trợ bởi LINK Mobility nếu được yêu cầu.
Tính năng này sẽ sửa địa chỉ đích và căn chỉnh chúng theo định dạng E.164 bắt buộc. Ngoài việc sửa định dạng, hệ thống cũng có thể thực hiện chức năng cụ thể của thị trường như dịch số tiếng Pháp quốc tế sang số DOM-TOM (départements et territoires d'outre-mer) chính xác khi áp dụng.
Dưới đây là một số ví dụampCác sửa đổi:
| Địa chỉ đích đã gửi | Địa chỉ đích đã sửa |
| +46(0)702233445 | 46702233445 |
| (0046)72233445 | 46702233445 |
| +460702233445 | 46702233445 |
| 46(0)702233445 | 46702233445 |
| 46070-2233445 | 46702233445 |
| 0046702233445 | 46702233445 |
| +46(0)702233445aaa | 46702233445 |
| 336005199999 | 2626005199999 (Số tiếng Pháp được dịch sang số DOM-TOM) |
Ngoài ra, có thể cho phép số điện thoại quốc gia cho một thị trường đã chọn. Khi tính năng này được bật, bất kỳ số điện thoại quốc tế nào cho các thị trường khác phải được gửi kèm dấu `+' ban đầu để phân biệt với thị trường đã chọn.
Dưới đây là một số cựuampCác sửa đổi được thực hiện khi sử dụng Thụy Điển (mã quốc gia 46) làm thị trường mặc định cho số quốc gia.
| Địa chỉ đích đã gửi | Địa chỉ đích đã sửa |
| 0702233445 | 46702233445 |
| 070-2233 445 | 46702233445 |
| 070.2233.4455 | 46702233445 |
| 460702233445 | 46702233445 |
| +460702233445 | 46702233445 |
| +458022334455 | 458022334455 |
| 45802233445 | Không hợp lệ vì dấu '+' bị thiếu |
Lưu ý rằng MSISDN đã hiệu chỉnh sẽ được LINK Mobility sử dụng và sẽ được trả về trong báo cáo giao hàng.
Vui lòng liên hệ với bộ phận hỗ trợ của LINK Mobility để biết thêm thông tin.
8.2 Thay thế ký tự
Thay thế ký tự là tính năng tùy chọn có thể được hỗ trợ bởi LINK Mobility nếu được yêu cầu.
Tính năng này sẽ dịch các ký tự chữ cái không phải GSM trong dữ liệu người dùng (văn bản SMS) sang các ký tự chữ cái GSM tương đương khi DCS được đặt thành “GSM” (17). Ví dụample “Seqüência de teste em Português” sẽ được dịch sang “Seqüencia de teste em Portugues”.
9. Báo cáo giao hàng
Nhà cung cấp dịch vụ có thể, nếu được cung cấp, yêu cầu báo cáo gửi tin nhắn SMS hoặc thông báo gửi tin nhắn MT đã gửi. Các báo cáo này được kích hoạt trong SMSC của Nhà điều hành khi tin nhắn MT được gửi đến Người tiêu dùng mục tiêu hoặc bị xóa, ví dụ, đã hết hạn hoặc vì lý do nào đó, không thể định tuyến được.
Chỉ có trạng thái cuối cùng của tin nhắn SMS được báo cáo cho Nhà cung cấp dịch vụ, tức là đã gửi hoặc đã xóa. Chỉ có một báo cáo cho mỗi tin nhắn MT được tạo. Với trạng thái đã xóa, có thể áp dụng mã lý do. Mã lý do này chỉ định lý do tin nhắn SMS không được gửi.
Các báo cáo được định tuyến qua LINK Mobility và gửi đến Nhà cung cấp dịch vụ bằng giao thức HTTP.
Để nhận được báo cáo, Nhà cung cấp dịch vụ cần triển khai ví dụamplà một Java Servlet hoặc một trang ASP.NET. Cả hai đều nhận được các yêu cầu HTTP GET hoặc POST.
Các tham số
Yêu cầu bao gồm các thông số sau:
| Tham số | Kiểu | Tôi/Tôi/Tôi* | Giá trị mặc định | Chiều dài tối đa | Sự miêu tả |
| ID tin nhắn | sợi dây | M | – | 22 | ID tin nhắn của tin nhắn MT mà báo cáo này tương ứng. |
| Địa chỉ đích | sợi dây | M | – | 40 | MSISDN của Người tiêu dùng, tức là địa chỉ đích của tin nhắn MT gốc. |
| Mã trạng thái | số nguyên | M | 1 | Mã trạng thái cho biết trạng thái của tin nhắn MT. Mã trạng thái áp dụng là: 0 – Đã giao 2 – Đã xóa (áp dụng mã lý do) |
|
| thời gianStamp | sợi dây | M | – | 20 | Thời gian cho biết thời điểm LINK Mobility nhận được báo cáo giao hàng. Múi giờ của thời gianamp là CET hoặc CEST (với giờ mùa hè được định nghĩa cho EU). Định dạng: yyyyMMdd HH:mm:ss. |
| Người điều hành | sợi dây | M | – | 100 | Tên của Nhà điều hành được sử dụng khi gửi tin nhắn SMS hoặc tên tài khoản được sử dụng khi gửi tin nhắn SMS. Danh sách các Nhà cung cấp dịch vụ có sẵn được cung cấp bởi bộ phận hỗ trợ LINK Mobility. |
| Lý doMã | số nguyên | O | – | 3 | Mã lý do cho biết lý do tại sao tin nhắn có trạng thái đã xóa. Mã lý do áp dụng là: 100 – Đã hết hạn 101 – Bị từ chối 102 – Lỗi định dạng 103 – Lỗi khác 110 – Người đăng ký không rõ 111 – Người đăng ký bị cấm 112 – Người đăng ký không được cung cấp 113 – Người đăng ký không có sẵn 120 – Lỗi SMSC 121 – Tắc nghẽn SMSC 122 – Chuyển vùng SMSC 130 – Lỗi điện thoại 131 – Bộ nhớ điện thoại vượt quá Hành vi có thể thay đổi tùy theo tích hợp của Nhà điều hành. |
| Toán tửTimeStamp | sợi dây | O | – | 20 | Thời gian cho biết thời điểm báo cáo được kích hoạt trong SMSC của Nhà điều hành (nếu Nhà điều hành cung cấp). Múi giờ của thời gianamp là CET hoặc CEST (với giờ mùa hè được định nghĩa cho EU). Định dạng: yyyyMMdd HH:mm:ss. |
| Tình trạngVăn bản | sợi dây | O | – | 255 | Chỗ giữ chỗ cho thông tin bổ sung từ Người vận hành, ví dụ: mô tả dạng văn bản rõ ràng về trạng thái/lý do. Hành vi có thể thay đổi tùy theo tích hợp của Người vận hành. |
| Mã tương quan | sợi dây | O | – | 100 | ID tương quan được cung cấp trong SendRequest hoặc SendTextRequest. |
| Toán tửMã mạng | số nguyên | O | – | 6 | Mã mạng di động (MCC + MNC) của nhà cung cấp dịch vụ. |
* M = Bắt buộc, O = Tùy chọn, I = Bỏ qua.
Nhà cung cấp dịch vụ phải cung cấp cho LINK Mobility mục tiêu URL cho các báo cáo phân phối (tùy chọn bao gồm thông tin xác thực cho xác thực cơ bản HTTP). Nhà cung cấp dịch vụ có thể chọn phương thức HTTP ưa thích để sử dụng:
HTTP POST (khuyến nghị)
HTTPLẤY.
Example sử dụng HTTP GET (đã gửi thành công):
https://user:password@www.serviceprovider.com/receivereport?%20MessageId=122&DestinationAddress=46762050312&Operator=Vodafone&TimeStamp=20100401%2007%3A47%3A44&StatusCode=0
Exampsử dụng HTTP GET (không được chuyển giao, Nhà điều hành đã cung cấp thời gianamp cho sự kiện):
Các thông số là URL được mã hóa.
Mã hóa ký tự:
Nhà cung cấp dịch vụ có thể chọn mã hóa ký tự ưa thích để sử dụng:
UTF-8 (khuyến nghị)
Tiêu chuẩn ISO-8859-1.
9.1 Xác nhận của Nhà cung cấp dịch vụ
Nhà cung cấp dịch vụ phải xác nhận mỗi báo cáo giao hàng. Xác nhận có thể là tích cực, tức là báo cáo giao hàng đã nhận thành công hoặc tiêu cực, tức là không thành công.
Xin lưu ý: LINK Mobility có thời gian chờ đọc xác nhận là 30 giây đối với báo cáo phân phối. Thời gian chờ sẽ kích hoạt thử lại phân phối (nếu bật thử lại) hoặc hủy giao hàng (nếu tắt thử lại). Điều này có nghĩa là ứng dụng Nhà cung cấp dịch vụ phải đảm bảo thời gian phản hồi nhanh, đặc biệt là trong thời gian tải cao.
Chúng tôi khuyến nghị bạn nên xác nhận báo cáo giao hàng với LINK Mobility trước khi xử lý.
Quy tắc xác nhận tích cực và tiêu cực được mô tả như sau:
Xác nhận tích cực, ACK, báo cáo giao hàng đã được gửi:
Mã phản hồi phạm vi HTTP 200 kết hợp với nội dung định dạng XML sau:
Xác nhận không thành công, NAK, báo cáo giao hàng không được giao:
Bất kỳ phản hồi nào khác ngoài sự xác nhận tích cực, ví dụample, một xác nhận tiêu cực được kích hoạt bởi bất kỳ mã lỗi HTTP nào hoặc nội dung XML sau đây:
Nội dung XML có thể được sử dụng để kiểm soát cơ chế thử lại LINK Mobility. NAK sẽ gây ra nỗ lực thử lại, nếu được bật. Đối với Nhà cung cấp dịch vụ không được cấu hình cho cơ chế thử lại, nội dung XML là tùy chọn.
Dưới đây là một yêu cầu HTTP POST và phản hồi ví dụampcủa báo cáo giao hàng được gửi đến Nhà cung cấp dịch vụ:
Yêu cầu HTTP:
POST /bối cảnh/ứng dụng HTTP/1.1
Nội dung-Loại: ứng dụng / x-www-form-urlđã mã hóa; charset=utf-8
Máy chủ: máy chủ: cổng
Độ dài nội dung: xx
MessageId=213123213&DestinationAddress=46762050312&Operator=Telia& OperatorTimeStamp=20130607%2010%3A45%3A00&TimeStamp=20130607%2010%3A 45%3A02&StatusCode=0
Phản hồi HTTP:
HTTP/1.1 200 Đồng ý
Loại nội dung: văn bản/thuần túy
9.2 Thử lại
Hệ thống LINK Mobility có thể thực hiện thử lại đối với các lần giao hàng báo cáo giao hàng không thành công, tức là không được xác nhận. Nhà cung cấp dịch vụ có thể chọn hành vi thử lại được ưu tiên:
Không thử lại (mặc định) – tin nhắn sẽ bị hủy nếu kết nối không thành công, hết thời gian đọc hoặc có bất kỳ mã lỗi HTTP nào.
Thử lại – tin nhắn sẽ được gửi lại cho mọi loại sự cố kết nối, thời gian chờ đọc hoặc xác nhận không thành công.
Khi thử lại cho NAK được bật, điều quan trọng là phải hiểu những kịch bản nào sẽ tạo ra một lần thử lại từ LINK Mobility và cách thức hoạt động của lần thử lại. Mỗi Nhà cung cấp dịch vụ có hàng đợi thử lại riêng, trong đó các tin nhắn được sắp xếp theo thời gian tin nhắnamp. Link Mobility luôn cố gắng gửi tin nhắn cũ trước, mặc dù thứ tự tin nhắn riêng lẻ được gửi đến Nhà cung cấp dịch vụ không được đảm bảo. Lý do chính khiến tin nhắn bị loại khỏi hàng đợi thử lại là một trong hai lý do: hoặc TTL tin nhắn hết hạn hoặc (về mặt lý thuyết) hàng đợi thử lại đầy. TTL phụ thuộc vào Nhà cung cấp và tài khoản, tức là có thể thay đổi tùy thuộc vào Nhà cung cấp và/hoặc loại tin nhắn, ví dụ: tin nhắn SMS cao cấp hoặc tin nhắn SMS giá chuẩn.
Nhà cung cấp dịch vụ đã bật tính năng thử lại phải kiểm tra ID duy nhất của tin nhắn MT để đảm bảo rằng tin nhắn chưa được nhận.
Nhà cung cấp dịch vụ cần tuân thủ các quy tắc đơn giản này khi xảy ra lỗi trong quá trình xử lý báo cáo giao hàng nếu lý do gây ra lỗi là: Tạm thời, ví dụ cơ sở dữ liệu không khả dụng, cần trả về NAK. LINK Mobility sẽ gửi lại tin nhắn.
Cố định và thử lại có thể gây ra cùng một loại vấn đề, nên trả về ACK. Ví dụample, khi tin nhắn không thể được phân tích cú pháp chính xác hoặc gây ra lỗi thời gian chạy không mong muốn.
Hành động theo đó sẽ đảm bảo không có tình trạng chặn hoặc giảm thông lượng do báo cáo phân phối được gửi lại nhiều lần.
10. Mẹo thực hiện
1. Có thể sử dụng của bạn web trình duyệt để gửi yêu cầu đến API. Điều này giúp bạn dễ dàng khám phá và đánh giá các dịch vụ mà không cần bất kỳ công cụ phát triển nào.
2. Chrome hoặc Firefox được khuyến nghị sử dụng cùng với tiện ích mở rộng như JSONView để hiển thị JSON được định dạng đẹp.
3. Chúng tôi đã sử dụng SoapUI để thử nghiệm POST, Xác thực cơ bản và để kiểm tra các thông báo yêu cầu và phản hồi HTTP thô.
4. Cái cURL công cụ hữu ích để gửi yêu cầu POST với Xác thực cơ bản. Xem ví dụampbên dưới.
curl BƯU KIỆN \
-H “Content-Type: application/x-www-form-urlđược mã hóa” \
-H “Ủy quyền: Cơ bản am9objpjaGFuZ2VtZSA=" \
https://europe.ipx.com/restapi/v1/sms/send \
–data “destinationAddress=46123456789&messageText=Xin chào thế giới%21”
_______________
Chuyển đổi truyền thông cá nhân
Tài liệu / Tài nguyên
 |
Hướng dẫn triển khai LINK Mobility REST API SMS [tập tin pdf] Hướng dẫn sử dụng Hướng dẫn triển khai tính di động REST API SMS, Tính di động, Hướng dẫn triển khai REST API SMS, REST API SMS, API SMS, SMS |
