Gởi tin nhắn chủ động
Tổng quan
API SMS FPT cho phép bạn triển khai ứng dụng client có thể gửi tin nhắn chủ động đến khách hàng của bạn thông qua tổng đài tin nhắn của FPT.
Mô tả
- Chuẩn webservice: RESTFull
- Mô hình cấp phát API: Oauth 2.0
-
Địa chỉ Webservices:
Live: http://app.sms.fpt.net Sandbox: http://sandbox.sms.fpt.net
Sơ đồ hệ thống
Chuẩn bị
Bên đối tác:
- Tên ứng dụng không quá 200 kí tự
- IP Server gọi API RESTFull
- Sau khi được FPT cung cấp account truy cập vào trang quản lý ứng dụng. Bên đối tác tiến hành đăng ký ứng dụng với các thông tin trên để lấy CLIENT_ID và CLIENT_SECRET ở môi trường sandbox
- Bên đối tác sử dụng tài liệu của FPT cung cấp để kết nối đến sandbox
- Sau khi kết nối đến sandbox thành công. Đối tác chuyển sang sử dụng các thông tin ở môi trường live để chạy ứng dụng.
Bên FPT:
- Khi tiến hành kết nối, FPT sẽ cung cấp cho đối tác thông tin tài khoản để đăng ký các thông tin như:
- CLIENT_ID
- CLIENT_SECRET
- Tài liệu:
- Gửi tin nhắn chủ động
-
Code ví dụ
- PHP
- JSP
- ASP.NET
-
SDK
- PHP
- JSP
- ASP.NET
Thiết lập thư viện
Một số thư viện client được cung cấp trong các ngôn ngữ khác nhau. Các thư viện này sẽ giúp bạn có thể dễ dàng hơn trong việc tương tác với API SMS FPT.
Để sử dụng được API bạn cần phải đăng ký thông tin ứng dụng để nhận CLIENT_ID và CLIENT_SECRET. Để xem hướng dẫn đăng ký, vui lòng click vào đây.
- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/php-tech-sdk-lastest.zip sau đó giải nén ra vào project của bạn.
- Thiết lập cấu hình của bạn trong file path/to/TechAPI/bootstrap.php.
- Thêm đoạn code sau trong project của bạn:
- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/jsp-tech-sdk-lastest.zip sau đó giải nén và include vào project của bạn.
- Tạo file YourProject/src/java/techsdk.properties với nội dung như sau:
- Trong Servlet hoặc Controller của bạn thiết lập như bên dưới:
- Trước tiên bạn tải thư viện mới nhất tại http://developer.sms.fpt.net/downloads/dot-net-tech-sdk-lastest.zip sau đó giải nén và add reference hai file TechSDK.dll, Newtonsoft.dll vào project của bạn.
- Tạo file Config.cs trong thư mục App_Code của bạn với nội dung như sau:
Gọi API gửi tin nhắn
API SMS FPT phát triển dựa trên mô hình cấp phát API bảo mật OAuth 2.0. Để có thể đơn giản trong việc tích hợp ứng dụng, bạn nên sử dụng thư viện do chúng tôi cung cấp.
- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/php_client_demo.zip
- Trong bộ API SMS FPT có sử dụng thư viện JSON, nên bạn cần phải import thư viện JSON vào project của bạn. Nếu như chưa có, bạn có thể tải thư viện JSON về tại đây
- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/jsp_client_demo.zip
- Lưu ý: Source tham khảo sử dụng mô hình Spring Web MVC Framework, và kết nối cơ sở dữ liệu MySQL bằng thư viện JDBC MySQL
- Trong WebForm bạn xử lý như sau:
- Bạn có thể tham khảo source mẫu tại: http://developer.sms.fpt.net/downloads/dot-net-client-demo.zip
Tham số đầu vào
Tên tham số | Kiểu dữ liệu | Bắc buộc | Mô tả |
---|---|---|---|
ServiceNum | String | Đầu số gửi tin nhắn đã đăng ký với FPT. | |
MOId | Int | ID của tin nhắn MO. | |
Syntax | Int | Cú pháp tin nhắn dịch vụ. | |
Phone | String | Số điện thoại của người nhận tin nhắn, chỉ được gửi 01 lần 01 số điện thoại. VD: 0943533xxx, 01234010xxx, 84943533xxx hoặc 841234010xxx |
|
Message | String | Nội dung của tin nhắn. Phải được mã hóa base64, nếu sử dụng thư viện của FPT cung cấp thì nội dung sẽ được tự động mã hóa. |
Dữ liệu trả về
Tên tham số | Kiểu dữ liệu | Mô tả |
---|---|---|
MTActiveId | Int | Id của tin chủ động gửi đi. |
MOId | Int | Id tin nhắn MO. |
ServiceNum | String | Đầu số tin nhắn gửi đi. |
ServiceNumGroup | String | Nhóm đầu số dịch vụ. |
Telco | String | Nhà mạng. |
Phone | String | Số điện thoại nhận tin nhắn. |
Syntax | String | Cú pháp dịch vụ. |
Message | String | Nội dung tin nhắn. |
PartnerId | String | Mã đối tác. |
Bảng mã lỗi
Mã lỗi | Mô tả |
---|---|
Lỗi phản hồi từ server | |
1001 | Request không hợp lệ. |
1002 | Client không được cấp phép truy cập. |
1003 | Truy cập bị từ chối. |
1004 | Loại response yêu cầu không được hỗ trợ. |
1005 | Các scope không hợp lệ |
1006 | Lỗi server. |
1007 | Server tạm thời không thể xử lý request từ client. |
1008 | Thông tin client không đúng. |
1009 | Loại hình cấp quyền không hợp lệ. |
1010 | Scope không đủ để truy cập API |
1011 | Access token không hợp lệ |
1012 | Access token đã bị thay đổi |
1013 | Access token hết hạn |
1014 | Các tham số truyền vào bị lỗi |
1015 | Không hỗ trợ kiêu loại hình cấp quyền này |
Lỗi xảy ra ở client | |
2001 | CLIENT_ID bắt buộc và không được trống. |
2002 | CLIENT_SECRET bắt buộc và không được trống. |
2003 | Access token hết hạn. |
2004 | Thời gian kết nối bị quá hạn. |
Nhận tin nhắn từ MO
Tổng quan
Webservice Soap giúp cho FPT lấy được tin nhắn MO từ đối tác.
Mô tả
- Chuẩn webservice: Soap.
Sơ đồ hệ thống
Chuẩn bị
Bên đối tác:
- Server hoặc Hosting để chứa ứng dụng
- URL của Webservice SOAP để bên FPT đẩy tin nhắn sang
- Nội dung tin nhắn trả về cho khách hàng theo tin nhắn của FPT đẩy sang.
Bên FPT:
- Cung cấp tài liệu cho đối tác:
- Gửi tin nhắn MT theo MO
-
Code ví dụ
- PHP
- JSP
- ASP.NET
- Tiến hành cấp cú pháp cho đối tác.
- Sau khi đối tác xây dựng xong Webservice SOAP và cung cấp URL gọi Webservice SOAP cho FPT. FPT tiến hành kiểm tra hoạt động của Webservice bên đối tác. Khi kết nối thành công. FPT sẽ cấu hình kết nối dịch vụ đến cú pháp mà đối tác đã đăng ký.
Thiết lập Webservice
Một số thư viện client được cung cấp trong các ngôn ngữ khác nhau. Các thư viện này sẽ giúp bạn có thể dễ dàng hơn trong việc tương tác với API SMS FPT.
- Đối với PHP bạn sử dụng thư viện nusoap. Download tại đây
- Hoặc tải code mẫu tại đây
- Bước 1: Tạo file functions.php (Chưa hàm thực thi) có nội dung như sau
- Bước 2: Tạo file server.php
- Bước 3: Tạo file client.php trả về kết quả
- Xem link hướng dẫn tạo WebService JSP bằng NetBeans tại đây
- Xem code mẫu tại đây
- Trong project Web tạo file WebService có phương thức ReceiveResponse có nội dung như sau:
- Đối với ASP.Net trong project bạn thêm một Item Web Service(ASMX) có tên Webservice.asmx
- Sau đó mở file Webservice.cs trong thư mục App_Code và thay đổi như file dưới đây
- Hoặc tải code mẫu tại đây
Tham số đầu vào
Tên tham số | Kiểu dữ liệu | Bắc buộc | Mô tả |
---|---|---|---|
MOId | Int | ID của tin nhắn MO. | |
Telco | String | Nhà mạng: viettel, vina, mobi... | |
ServiceNum | String | Đầu số tin nhắn gửi đi. | |
Phone | String | Số điện thoại của người nhận tin nhắn, chỉ được gửi 01 lần 01 số điện thoại. VD: 0943533xxx, 01234010xxx, 84943533xxx hoặc 841234010xxx |
|
Syntax | String | Cú pháp tin nhắn dịch vụ. | |
EncryptedMessage | String | Nội dung của tin nhắn ở dạng mã hóa base64. | |
Signature | String |
Signature = SHA1(MOId + ServiceNum + Phone + MessageRequest + PrivateKey). Trong đó: MessageRequest = TOLOWER(Base64Decode(EncryptedMessage)) |
Dữ liệu trả về
- Xử lý và trả về kết quả theo định dạng MessageCode|MessageResponse
Tham số | Kiểu dữ liệu | Bắt buộc | Mô tả |
---|---|---|---|
MessageCode | String |
Trạng thái xử lý, có 2 giá trị: - 01: Quá trình xử lý không thành công, có lỗi. - 00: Quá trình xử lý thành công, trả về nội dung tin nhắn. |
|
MessageResponse | String |
Nội dung trả về: - Thông báo lỗi. - Nội dung tin nhắn. |
- Thành công: 00|Bạn đã đăng ký thành công dịch vụ sms của FPT
- Có lỗi: 01|Tham số truyền vào không chính xác