未来无线短信网关平台HTTP接口协议

未来无线HTTP接口文档

一、工作方式

双方通过HTTP方式交互数据，第三方可以简单的“name=value”方式发送提交内容或响应请求内容。即通过HTTP的 POST 方式交换。

另外双方需要保证数据传输的完整性和安全性，每次发送请求都有响应(响应返回格式为纯文本)，安全验证目前采用客户代码和数据签名的方式，数据签名根据用户密码和短信内容生成。

二、字符编码

服务器请求和返回都采用UTF8编码

三、响应格式

所为响应即每次向服务器提交请求后返回值

响应值格式为纯文本

失败格式为：

ERROR:失败原因说明的URLEncode

包提交成功格式为：

SUCCESS:提交成功的URLEncode\r\n

手机号吗:MSGID:状态码\r\n

手机号吗:MSGID:状态码\r\n

手机号吗:MSGID:状态码\r\n

手机号吗:MSGID:状态码\r\n

……

如发送成功后返回：

SUCCESS:%e6%8f%90%e4%ba%a4%e6%88%90%e5%8a%9f

137********:0904d51230664e000001:0

137********:0904d51230664e000002:13

137********:0904d51230664e000003:0

四、短信发送

URL:

http://网关IP地址:8860

POST内容格式：

cust_code=***&sp_code=***&content=****&destMobiles=***,****,***&sign =****&task_id=*****

接口参数说明:

参数名参数字段参数说明

cust_code 用户账号必填。

sp_code 长号码必填，扩展的长号码，只能在平台为客户分配的子号码上扩展，

content 短信内容必填，发送内容需要进行URL字符标准化转码。

{URL字符编码说明:返回字符串，此字符串中除了-_.之外的所有非字母数字字符都将被替换成百分号（%）后跟两位十六进制数，空格则编码为加号（+）}

ASP：server.URLEncode("短信内容")

PHP：urlencode("短信内容")

JAVA：https://www.wendangku.net/doc/5e409033.html,.URLEncoder.encode("短信内容")

destMobil

es 接收号码

必填，同时发送给多个号码时,号码之间用英文半角逗号分隔(,)如:13

972827282,130********,021********

POST 方式每次最多可以提交的号码数根据通道开给客户的每秒上

限，超过每秒提交速率会被服务端拒绝。

sign 签名必填，签名内容根据“短信内容URL编码后+客户密码”进行MD5编码后获得。

例:

接收号：手机号码,手机号码,手机号码（测试时请换成自己的号码）

发送内容：

cust_code=570061&sp_code=1234&content=%E5%8F%91%E9%80%81%E7%9F%AD%E 4%BF%A1%E4%B8%8B%E8%A1%8C%E6%B5%8B%E8%AF%&destMobiles=手机号码,手机号码,手机号码&sign=fa246d0262c3925617b0c72bb20eeb1d

发成功时响应值:

SUCCESS:%e6%8f%90%e4%ba%a4%e6%88%90%e5%8a%9f

手机号码:0904d5125d6d44000002:0

手机号码:0904d5125d6d44000004:0

手机号码:0904d5125d6d44000006:0

返回发送的状态码

状态码说明

0 发送成功

13 目标号码在黑名单中

15 通道不支持该目标号码

8 流量超过限制

五、接收状态报告

客户提供接收状态的URL地址如：

http://客户对接IP地址/xxx.jsp

短信服务器主动POST状态报告(可以为多条)，格式如下：

report=msgid,destmobile,report_status,report_recvtime^msgid,destmobile,re port_status,report_recvtime^msgid,destmobile,report_status,report_recvtime……

其中多条状态报告以“^”为分隔符，状态报告字段以“,”（半角逗号）为分隔符。

字段意义如下：

msgid 下行短信的唯一编号

destmobile 下行短信目标手机号码

report_status 下行短信状态报告

report_recvtime 网关接收到行短信状态报告的时间

例如：

report=0904d5125d6d44000002,手机号码,DELIVRD,2014-01-02 15:33:09^09 04d5125d6d44000004,手机号码,DELIVRD,2014-01-02 15:33:09^0904d5125d6d44 000006,手机号码,DELIVRD,2014-01-02 15:33:09

六、接收上行消息

客户提供接收状态的URL地址如：

http://客户对接IP地址/xxxx.jsp

短信服务器主动POST用户上行，格式如下：

msg_id=******&sp_code=*****&src_mobile=*****&msg_content=*****&rec v_time=******

参数意义如下：

msg_id 上行短信的唯一编号

sp_code 上行短信的目标地址

src_mobile 发送上行短信的手机号

msg_content 上行短信内容的URLEncode编码

recv_time 网关接收到上行短信的时间

例如：

msg_id=0904d5125d6d44000002&sp_code=10659078123456&src_mobile=手机号码&msg_content=%E5%8F%91%E9%80%81%E7%9F%AD%E4%BF%A1%E4%B8%8B%E8%A1% 8C%E6%B5%8B%E8%AF%&recv_time=2014-01-02 15:33:10

七、查询帐户余额

1、客户先要调用服务器接口获取Token，Token值有效期间30秒，每次查询余额都需要重新获取。

URL:

http://网关IP地址:8860/?action=GetToken&cust_code=客户代码

服务器返回：

TOKEN:20位的token值

例如：

TOKEN:qs6vbgwrlingrutu47ii

2、客户把“Token+客户的密码”，用MD5加密成为签名字符串，然后向服务器发起查询余额请求

URL：

http:// 网关IP地址:8860/?action=QueryAccount&cust_code=客户代码&sign=生成的签名

例如：

http:// 网关IP地址:8860/?action=QueryAccount&cust_code=570063&sign=9b a54933d138e2ed942683246abb5f0a

服务器返回：

cust_code:客户代码,status:客户状态,sms_balance:短信余额条数

例如：

cust_code:570063,status:1,sms_balance:20

status表示：

0 账号已停用

1 账号在用

2 账号处在测试状态

八、通道返回错误代码列表

-1 未知错误

0 成功

1 消息结构错

2 非法源IP地址

3 认证错误

4 协议版本错误

6 短信内容超过规定的长度

8 流量控制错，超出最高流量

12 用户账号未登录

13 目标号码在黑名单中

15 通道不支持

22 客户账号已经被关闭

23 客户账号状态错误

24 客户账号余额不足

25 内容包含敏感词

26 模版过滤失败

27 长短信拆分条数过多

28 模版过滤失败

部分过滤规则用系统生成状态报告返回，生成的状态报告如下（所有协议统一错误码）： * MX:0001 签名匹配规则不成功

* MX:0002 向上级通道提交短信失败

* MX:0003 单个手机号码当天下行条数超过上限(长短信算1条)

其他协议返回状态报告错误值：

* MX:0004 短信内容中包含敏感词 (HTTP对应错误码：25)

* MX:0005 模版过滤失败(签名未报备) (HTTP对应错误码：26)