创瑞---平台接口说明.doc

短信平台接口
说明

Version 1.1

目录
1 普通短信发送 4
1.1 短信提交地址 4
1.2 参数定义 4
1.3 短信提交响应 4
1.3.1 格式说明 5
1.3.2 示例 5
1.3.3 响应状态值说明 5
1.4 短信发送例子 6
2 个性短信发送 6
2.1 短信提交地址 6
2.2 参数定义 6
2.3 短信提交响应 7
2.3.1 格式说明 7
2.3.2 示例 7
3 状态报告推送 7
3.1 参数定义 8
3.2 状态报告值 8
3.3 示例 8
4 短信接收 9
4.1 参数定义 9

4.2 示例 9
5 余额查询接口 9
5.1 接口地址 9
5.2 参数定义 9
5.3 提交响应 10
5.4 提交响应值 10
5.5 示例 10

版本修订历史
项目
日期
修订内容
备注
1
2012-10-21

技术支持： 邴立运 qq：613953603 手机：[phone]
本文档主要定了短信平台对用户开放的主要接口和定义。
1 普通短信发送
用户通过HTTP的POST方式提交短信发送请求。编码采用UTF-8编码。
1.1 短信提交地址
URL地址为：

1.2 参数定义

序号
参数
说明
1
name
必填参数。用户账号
2
pwd
必填参数。（web平台：基本资料中的接口密码）
3
content
必填参数。发送内容（1-500 个汉字）UTF-8编码
4
mobile
必填参数。手机号码。多个以英文逗号隔开
5
stime
可选参数。发送时间，填写时已填写的时间发送，不填时为当前时间发送
6
sign
可选参数。用户签名。
7
type
必填参数。固定值 pt
8
extno
可选参数，扩展码，用户定义扩展码，只能为数字
1.3 短信提交响应
用户短信通过http请求提交到服务器后，服务器返回响应码，响应码的格式如下：
code,sendid,invalidcount,successcount,blackcount,msg

1.3.1 格式说明
短信提交响应为英文逗号隔开的一行数据，状态,发送编号,无效号码数,成功提交数,黑名单数和消息，无论发送的号码是多少，一个发送请求只返回一个sendid，如果响应的状态不是“0”，则只有状态和消息（提交失败的原因），并将提交的参数及值原样返回。
1.3.2 示例
Ø 提交成功
0, 20130821110353234137876543,0,500,0,提交成功

20130821110353234137876543为返回的sendid，这个工状态报告匹配时使用
1,含有敏感词汇,?name=*****&pwd=****** 等参数和值
Ø 提交失败
Ø

本示例表明用户提交失败，返回错误码为1，服务器端并未返回sendid等。
提交失败时是英文逗号隔开的三个参数。但是最后一个参数可能也会有英文逗号，比如发送的内容中有。这样就会有多于3个英文逗号，请做好相应处理。
1.3.3 响应状态值说明
代码
说明
0
提交成功
1
含有敏感词汇
2
余额不足
3
没有号码
4
包含sql语句
10
账号不存在
11
账号注销
12
账号停用
13
IP鉴权失败
14
格式错误
-1
系统异常

1.4 短信发送例子
8:20:23&sign=testsign&type=pt&extno=

2 个性短信发送
2.1 短信提交地址
URL地址为：
2.2 参数定义

序号
参数
说明
1
name
必填参数。用户账号
2
pwd
必填参数。（web平台：基本资料中的接口密码）
3
content
必填参数。发送内容UTF-8编码，建议每次1000个
格式：内容#@#号码#@@#内容#@#号码
例：你好张三#@#13566666666#@@#你好李四#@#13999999999
4
stime
可选参数。发送时间，填写时已填写的时间发送，不填时为当前时间发送
5
sign
可选参数。用户签名。
6
type
必填参数。固定值 gx
7
extno
可选参数，扩展码，用户定义扩展码，只能为数字
2.3 短信提交响应
用户短信通过http请求提交到服务器后，服务器返回响应码，响应码的格式如下：
code,sendid,invalidcount,successcount,blackcount,msg

2.3.1 格式说明
短信提交响应为英文逗号隔开的一行数据，状态,发送编号,无效号码数,成功提交数,黑名单数和消息，无论发送的号码是多少，一个发送请求只返回一个sendid，如果响应的状态不是“0”则只有状态和消息。Code值与普通短信含义相同
2.3.2 示例
Ø 提交成功
0, 20130821110353234137876543,0,500,0,提交成功

20130821110353234137876543为返回的sendid，这个工状态报告匹配时使用。

3 状态报告推送（post方式推送）
如果管理员设置用户账户需要状态报告，并且也配置了账户的状态报告接收地址，则用户可以接收到其发送短信的状态报告。用户侧启动一个HTTP服务用于接收状态报告。POST方式推送
3.1 参数定义
序号
参数
说明
1
name
接收状态报告验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空
2
pwd
接收状态报告验证的密码，可以为空
3
sendid
提交短信时平台返回的sendid，参见1.2
4
time
报告时间（多个号码时，是第一个号码的时间）
5
mobile
当多个号码状态相同时 手机号以英文逗号隔开；
不同时 为单个手机号码
6
state
状态报告数值

3.2 状态报告值
状态报告的值即，state后面的数据，如下
状态值(字符串)
说明
DELIVRD
短消息转发成功
EXPIRED
短消息超过有效期
UNDELIV
短消息是不可达的
UNKNOWN
未知短消息状态
REJECTD
短消息被短信中心拒绝
DTBLACK
目的号码是黑名单号码
ERR:104
系统忙
REJECT
审核驳回
其他
网关内部状态

3.3 示例
http://pushUrl?name=admin&pwd=12345&sendid=12345&time=2013-08-20 20:11:34&mobile=13900210021&state=DELIVRD

其中，pushUrl为用户启动的服务地址。
4 短信接收（与报告雷同 post方式推送）
4.1 参数定义
序号
参数
说明
1
name
接收信息验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空
2
pwd
接收信息服务需验证的密码，可以为空
3
args
手机号、内容、时间、系统扩展码+自定义扩展码；以 #@# 分割。(扩展码可能为空)

多个上行以#@@# 分割
4.2 示例
http://pushMoUrl?name=admin&pwd=12345&args=13800210021#@#content1#@#2013-08-21 21:20:11#@#008123#@@#13978767656#@#content2#@#2013-08-21 21:20:30#@#008456

本例中 008为系统为该用户设置的扩展码，123和另外一个456是提交短信时用户自己加的自定义扩展码；即发送时extno=123

系统扩展码可能变化，如果变化一般长度不变，建议通过长度来截取得到自定义扩展码
其中，pushUrl为用户启动的服务地址。
5 余额查询接口
5.1 接口地址

5.2 参数定义

序号
参数
说明
1
name
必填参数。用户账号
2
pwd
必填参数。用户密码
3
type
必填参数。固定值 balance
5.3 提交响应
code,balance

code为获取状态，balance是用户余额。
5.4 提交响应值
代码
说明
0
成功
10
账号不存在
11
账号注销
12
账号停用
13
IP鉴权失败

5.5 示例

10