平台接口说明.doc

短信平台接口
说明

目录
1 普通短信发送 3
1.1 短信提交地址 3
1.2 参数定义 3
1.3 短信提交响应 4
1.3.1 格式说明 4
1.3.2 示例 4
1.3.3 响应状态值说明 5
1.4 注意事项 6
1.5 短信发送例子 6
2 变量短信发送 6
2.1 系统提交URL地址 7
2.2 参数定义 7
2.3 提交响应 7
2.3.1 提交成功 7
2.3.2 提交失败 8
2.3.3 响应状态值说明 8
2.4 示例 8
3 短信包发送 9
3.1 系统提交URL地址 9
3.2 参数定义 9
3.3 提交响应 9
3.3.1 提交成功 9
3.3.2 提交失败 10
3.3.3 响应状态值说明 10
3.4 示例 10
4 状态报告推送 10
4.1 参数定义 11
4.2 状态报告值 11
4.3 示例 11
5 短信接收 12
5.1 参数定义 12
5.2 示例 12
6 额度查询接口 13
6.1 接口地址 13
6.2 参数定义 13
6.3 提交响应 13
6.4 提交响应值 13
6.5 示例 14
7 附录 14

本文档主要定了短信平台对用户开放的主要接口和定义。
1 普通短信发送
用户通过HTTP的POST方式提交短信发送请求。短信发送接口，区分为短信单发和短信群发两个接口。
1.1 短信提交地址
短信提交分为单发和群发（账户是否具有单发和群发的功能需要管理员进行功能的开通）。单发只能提交单个手机号码，群发可以提交不超过50000个手机号码，每个号码用英文逗号间隔。
区别单发和群发主要在于发送的接口URL地址入口不同。
单发的URL地址为：http://IP:PORT/msg/HttpSendSM，
群发的URL地址为：http://IP:PORT/msg/HttpBatchSendSM。
注：其中IP:PORT为服务部署的地址和端口。
1.2 参数定义

序号
参数
说明
1
account
必填参数。用户账号
2
pswd
必填参数。用户密码
3
mobile
必填参数。合法的手机号码，号码间用英文逗号分隔
4
msg
必填参数。短信内容，短信内容长度不能超过585个字符。使用URL方式编码为UTF-8格式。短信内容超过70个字符（企信通是60个字符）时，会被拆分成多条，然后以长短信的格式发送。
5
needstatus
必填参数。是否需要状态报告，取值true或false，true，表明需要状态报告；false不需要状态报告
6
product
可选参数。用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品，用户订购多个产品时必填，否则会发生计费错误。
7
extno
可选参数，扩展码，用户定义扩展码，3位
1.3 短信提交响应
用户短信通过http请求提交到服务器后，服务器返回响应码，响应码的格式如下：
resptime,respstatus
msgid

1.3.1 格式说明
短信提交响应分为两行，第一行为响应时间和状态，第二行为服务器给出提交msgid。无论发送的号码是多少，一个发送请求只返回一个msgid，如果响应的状态不是“0”，则没有msgid即第二行数据。（每行以换行符(0x0a,即\n)分割）
1.3.2 示例
Ø 提交成功
20110725160412,0
1234567890100

响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器；1234567890100为返回的msgid，这个工状态报告匹配时使用。
20110725160412,101
Ø 提交失败
Ø

本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。
1.3.3 响应状态值说明
代码
说明
0
提交成功
101
无此用户
102
密码错
103
提交过快（提交速度超过流速限制）
104
系统忙（因平台侧原因，暂时无法处理提交的短信）
105
敏感短信（短信内容包含敏感词）
106
消息长度错（>536或<=0）
107
包含错误的手机号码
108
手机号码个数错（群发>50000或<=0;单发>200或<=0）
109
无发送额度（该用户可用短信数已使用完）
110
不在发送时间内
111
超出该账户当月发送额度限制
112
无此产品，用户没有订购该产品
113
extno格式错（非数字或者长度不对）
115
自动审核驳回
116
签名不合法，未带签名（用户必须带签名的前提下）
117
IP地址认证错,请求调用的IP地址不是系统登记的IP地址
118
用户没有相应的发送权限
119
用户已过期
1.4 注意事项
用户群发短信如果有审核的限制，则客户的短信必须经过管理人员的审核，审核通过后才能被提交到行业网关进行短信实际发送。
用户群发短信必须满足手机号码最低个数的限制，低于系统设定的群发最小手机号码数，则该提交请求会被拒绝，响应码为108。
1.5 短信发送例子
Ø 短信单发
http://117.135.134.240/msg/HttpSendSM?account=111111&pswd=123456&mobile=18900000000,13800138000&msg=test&needstatus=true&product=99999

Ø 短信群发
http://117.135.134.240/msg/HttpBatchSendSM?account=test01&pswd=123456&mobile=18900000000,13800138000&msg=test&needstatus=true&product=274463133

短信单发和群发的url入口地址有区别，并且其中的IP地址192.l68.168.168需要根据系统部署的实际地址填写。
2 变量短信发送
用户通过HTTP的POST方式提交短信发送请求。
2.1 系统提交URL地址
http://IP:PORT/msg/HttpVarSM
2.2 参数定义
序号
参数
说明
1
account
用户账号
2
pswd
用户密码
3
msg
短信模板。其中的变量用“{$var}”来替代。例如：
“{$var},你好！，请你于{$var}日参加活动”，该短信中具有两个变量参数。编码为UTF-8格式。
4
params
变量短信的参数组。单次提交参数组的数目不能超过1000个。编码为UTF-8格式
每一组参数之间用英文“；”间隔
每一组参数内部用英文“，”间隔，其中第一个参数为手机号码，第二个参数为模板中第一个变量，第三个参数为模板中第二个变量，以此类推。
例如：
13800210000,李先生,2013-01-01;13500210000,王先生，2013-01-15
表明提交了两个变量组，其中手机号码分别为：13800210000和13500210000。模板变量分别为：李先生，2013-01-01和王先生，2013-01-15

格式不符的参数，系统自动过滤掉。
5
needstatus
是否需要状态报告，取值true或false，true，表明需要状态报告；false不需要状态报告
6
product
用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品。
7
extno
可选参数，扩展码，用户定义扩展码，3位

2.3 提交响应
2.3.1 提交成功
20110725160412,0,10,1
1234567890100

响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器，参数组个数为10表明提交参数params中格式正确的条数为10条, 发送包失败个数为1表明提交参数msg中格式错误的条数为1条；1234567890100为返回的msgid，这个供状态报告匹配时使用。

2.3.2 提交失败
20110725160412,101

本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。
2.3.3 响应状态值说明
响应的值在1.2.3的基础上增加：
代码
说明
114
可用参数组个数错误（小于最小设定值或者大于1000）

2.4 示例
http://192.168.168.168/msg/HttpVarSM?account=111111&pswd=123456&msg={$var},你好！，请你于{$var}日参加活动&params=13800210000,李先生,2013-01-01;13500210000,王先生，2013-01-15&needstatus=true&product=99999
3 短信包发送
用户通过HTTP的POST方式提交短信发送请求。
3.1 系统提交URL地址
http://IP:PORT/msg/HttpPkgSM
3.2 参数定义
序号
参数
说明
1
account
用户账号
2
pswd
用户密码
3
msg
发送包内容，格式为：mobile|content ,内容编码为utf-8格式。
4
……
……
5
msg
第n个短信号码及内容，n<=1000
6
needstatus
是否需要状态报告，取值true或false，true，表明需要状态报告；false不需要状态报告
7
product
用户订购的产品id，不填写（针对老用户）系统采用用户的默认产品。
8
extno
可选参数，扩展码，用户定义扩展码，3位

3.3 提交响应
3.3.1 提交成功
20110725160412,0,10,1
1234567890100

响应时间为20110725160412，响应状态为0 表明那个成功提交到服务器，发送包成功个数为10表明提交参数msg中格式正确的条数为10条, 发送包失败个数为1表明提交参数msg中格式错误的条数为1条；1234567890100为返回的msgid，这个供状态报告匹配时使用。

3.3.2 提交失败
20110725160412,101

本示例表明用户提交失败，返回错误码为101，服务器端并未返回msgid。
3.3.3 响应状态值说明
响应的值在1.2.3的基础上增加：
代码
说明
114
可用参数组个数错误（小于最小该用户群发设定值或者大于1000）

3.4 示例
http://192.168.168.168/msg/HttpPkgSM?account=111111&pswd=123456&msg=13800000001|测试短信1&msg=13800000002|测试短信2&msg=13800000003|测试短信3&needstatus=true&product=99999&extno=123

4 状态报告推送
如果管理员设置用户账户需要状态报告，并且也配置了账户的状态报告接收地址，则用户可以接收到其发送短信的状态报告。用户侧启动一个HTTP服务用于接收状态报告。
4.1 参数定义
序号
参数
说明
1
receiver
接收状态报告验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空
2
pswd
接收状态报告验证的密码，可以为空
3
msgid
提交短信时平台返回的msgid，参见1.2
4
reportTime
格式YYMMDDhhmm，其中YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59）
5
mobile
单一的手机号码
6
status
状态报告数值

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

4.3 示例
http://pushUrl?receiver=admin&pswd=12345&msgid=12345&reportTime=1012241002&mobile=13900210021&status=DELIVRD

其中，pushUrl为用户启动的服务地址。
5 短信接收
5.1 参数定义
序号
参数
说明
1
receiver
接收信息验证的用户名（不是账户名），是按照用户要求配置的名称，可以为空
2
pswd
接收信息服务需验证的密码，可以为空
3
moTime
格式YYMMDDhhmm，其中YY=年份的最后两位（00-99），MM=月份（01-12），DD=日（01-31），hh=小时（00-23），mm=分钟（00-59）
4
mobile
单一的手机号码
5
msg
MO短信内容，文字内容使用UTF-8编码
6
destcode
用户上行的目的号码
7
isems
是否为长短信的一部分，1:是，0，不是。
不带该参数，默认为普通短信
8
emshead
Isems为1时，本参数以ASCII码形式显示长短信的头信息。用“,”隔开，分为三个部分，第一部分标识该条长短信的ID（该ID为短信中心生成）；第二部分，表明该长短信的总条数（pk_total）；第三部分，该条短信为该长短信的第几条(pk_number)。
例如：234,4,1，该短信的ID为234,该长短信的总长度为4条，1，当前为第一条。
5.2 示例
普通短信：
http://pushMoUrl?receiver=admin&pswd=12345&moTime=1208212205&mobile=13800210021&destcode=1065751600001&msg=hello&destcode=10657109012345
EMS短信：
http://pushMoUrl?receiver=admin&pswd=12345&moTime=1208212205&mobile=13800210021&destcode=1065751600001&msg=hello&destcode=10657109012345&isems=1&emshead=255,5,5
其中，pushUrl为用户启动的服务地址。
6 额度查询接口
6.1 接口地址
http://IP:PORT/msg/QueryBalance
6.2 参数定义

序号
参数
说明
1
account
必填参数。用户账号
2
pswd
必填参数。用户密码
6.3 提交响应
20130303180000,0
1234567,1000
1234531,2000

第一行显示返回额度时的时间，提交响应值。
第二行开始，每一行显示一个产品ID及其额度，有多少个产品显示多少行。
6.4 提交响应值
代码
说明
0
成功
101
无此用户
102
密码错
103
查询过快（建议每10秒查询一次）

6.5 示例
http://192.168.168.168/msg/QueryBalance?account=111111&pswd=123456
7 附录

14