红树服务器5接口文档.doc

北京红树科技 HTTP接口文档
北京红树科技有限公司
文档编号
产品版本
密级

2．0

共6页

HTTP 接口文档

更新日期：2011年3月25日

目录

1 短信发送接口设计 2
1.1发送短信 2
1.2 短信发送参数 2
1.3发送返回参数说明 3
2 账户余额查询 4
2.1接口地址 4
2.2接口参数 4
3 状态报告 4
4 上行信息 7
5 附录(java开发的接收demo) 8

1 短信发送接口设计
1.1 发送短信
为了降低客户的开发技术难度，根据客户需求，提供 HTTP接口。采用HTTP的GET(支持post)方式进行消息的下发。在使用接口时，以如下形式进行调用。
http://211.103.155.246:8080/sms_send2.do?corp_id= 账户id&corp_pwd=密码&corp_service=业务代码&…………………………………….
服务器接口地址：http://211.103.155.246:8080/sms_send2.do
账号简单页面测试地址：http://211.103.155.246:8080/smsSubmitTest2.jsp
注意事项：
1.下发短信时，不要提交错了服务器的接口地址，如果你的账户是开在服务器2上的，
提交的时候提交到服务器1的接口地址会返回（106错误：用户名不存在）。
2.参数提交后的返回结果为文本格式和xml格式，即，发送完毕后，我方会推送相关数字信息或xml格式的字符串信息。
3.服务器支持http方式，为安全性考虑，建议以http方式调用。
1.2 短信发送参数
参数说明：
参数名称
参数说明
备注
corp_id
企业接口访问id
由系统管理员开通
corp_pwd
系统访问接口密码
由系统管理员设定
corp_service
业务代码
由系统管理员分配
Mobile
要发送的手机号码
多个号码用英文的逗号隔开，且群发总号码数不超过50个
msg_content
短信内容
短信内容长度不超过500个汉字
每个英文或阿拉伯字符也算1个汉字
corp_msg_id
用户发送短信自己定义的短信id用于处理群发状态报告 可以为空
英文和数字的组合总长度不超过50个字节
Ext
用户自己分配的小号（即显示在接收手机上的主叫尾号，可用于上行信息匹配）例：我们给合作方开的特服号是10657532521924，然后合作方在发送信息的时候可以随意填写扩展号ext=8888，那么用户收到信息时显示的下发号码就是106575325219248888
从00000到99999的范围

说明：
1）发送速度：接口的访问间隔是0.1秒，最快访问速度是每秒十次。
2）IP：如果用户开账户时指定IP，则接口只接收该IP发送请求。
接口编码格式：根据不同开发语言可选用gbk或ISO-8859-1编码（提交信息时，汉字应转成gbk或iso-8859-1提交，否则手机用户收到会显示乱码）
1.3 发送返回参数说明
返回代码
代码说明
0#数字
提交成功#提交成功的手机数量
100
余额不足
101
账号关闭
102
短信内容超过500字或为空或内容编码格式不正确
103
手机号码超过50个或合法的手机号码为空
104
用户访问时间间隔低于50毫秒
105
用户访问方式不是post方式
106
用户名不存在
107
密码错误
108
指定访问ip错误
109
业务不存在
110
小号不合法
111
短信内容内有敏感词

常见问题说明：
1) 长短信：对于长短信，返回的是用户提交的条数，而不是实际扣费的条数，例如用户发送了190字的短信三条，返回的是0#3,后台根据拆分后的结果，计费为9条。
2) 102错误：确认接口编码格式是否正确，测试标准是发送带有“%”的短信看是否能成功发送。
2 账户余额查询
2.1 接口地址
接口地址：http://211.103.155.246:8888/get_balance.do
2.2 接口参数
参数名称
参数说明
备注
corp_id
企业接口访问id
由系统管理员开通
user_id
用户id

Pwd
系统访问接口密码
由系统管理员设定
说明：支持非一级账户余额查询
返回结果为：ok:余额。
3 状态报告
用于客户查询每条短信发送的状态是否成功。
在收取状态报告之后，请立即调用该接口告知服务端已经成功收取的状态报告编号，否则会重复收取到状态报告
接口地址：由合作方提供相应的接收的url，我方主动推送数据。
推送的数据样例(为一整条xml格式的字符串，注：是一整条字符串，不是xml文档)
<?xml version="1.0" encoding="GBK" ?>
<reports>
<report>
<corp_id>test</corp_id>
  <mobile>13810000001</mobile>
<seq>0</seq> (这个参数表示拆分长短信的条数：0无长短信，1表示被拆分为(1/2),(2/2)两条，以此类推..)
< msg_id>12345asd</ msg_id>
  <result>0</result>(这个参数表示短信发送状态：0表示成功，其他数字均是失败，113表示审核拦截，200表示无状态报告返回，112黑名单用户)
  </report>

<report>
<corp_id>test</corp_id>
  <mobile>13810000002</mobile>
<seq>0</seq>
< msg_id>12345asd</ msg_id>
  <result>200</result>
  </report>
  </reports>
说明：当成功接收我方推送过去的信息时必须给个返回参数：0: 接收成功 9:接收失败 ,这个参数不给的话，我方会认为对方接收信息失败，导致接收数据重复推送。
状态报告的推送，有时可能会推一条过去，有时可能会推多条过去，最多可一次推200条，并且，你方接收到我方推送串后，应立即回响应，同时存起这些状态报告，然后，你方再完成插表工作，否则，边接收边插表，插完后再给响应，因时差原因，会导致我方接收响应错乱，从而严重影响状态报告的推送。
状态报告是根据mobile和msg_id一起来匹配的

返回结果
值
含义
0
成功
-1
失败
2
失败
112
黑名单用户
113
信审拦截
115
系统自动拦截
200
无返回状态
1000
返回状态未知
4 上行信息
上行信息：手机用户给发送方回复的信息。
接口地址：有合作方提供相应的url(上行推送和状态报告推送原理一样，区别：xml字符串的节点不同，解析的时候需要注意)
推送数据样例
<?xml version="1.0" encoding="GBK" ?>
<delivers>
  <deliver>
<corp_id>test</corp_id>
  <mobile>13810000000</mobile>
  <ext>8888</ext> (对应下发时的ext参数根据手机用户回复短信时（即上行信息）的ext的值， <ext>8888</ext> 可知道用户上行的是客户下发的哪一批的信息的回复)
<time>2010-07-02 00:00:00</time>
  <content>收到</content>
  </deliver>
  </delivers>
返回参数(注意给我方返回接收后的结果参数同上)
0：成功
9：失败

说明：
上行信息是一条一条的推送过去，为了更好的接收上行，需要你方接收完字符串后立即返回响应，不要等到插入成功后再响应，这样才不会影响上行信息的接收。
上行信息是根据mobile和ext来匹配的。

5 附录(java开发的接收demo)
介绍：我方推送过去的xml格式的上行字符串，参照如下
String str="<?xml version='1.0' encoding='GBK'?>" +
"<delivers>" + "<deliver><corp_id>test</corp_id><mobile>13860497631</mobile><ext>2010</ext><time>2010-07-02 00:00:00</time><content>您好 tuisong测试222</content></deliver>" +
"</delivers>";
1.通过访问合作方给提供url地址，调用到合作方的接收类，然后我方推送上行信息的xml字符串过去，合作方接收
2.此条xml字符串，是存在requset的内存里
3.需要接收方先取得request对象(注意这里request对象无参数，是直接存在request内存里，需要先从request里获取输入流，然后进行读流操作，读出推送内容)参考如下：
InputStream in = request.getInputStream();
BufferedInputStream buf = new BufferedInputStream(in);
byte[] buffer = new byte[1024];
StringBuffer data =new StringBuffer();
int a ;
while((a = buf.read(buffer))!= -1){
data.append(new String(buffer,0,a,"gbk"));
}
System.out.println(data.toString());
打印出的字符串即为我方推送的xml格式的字符串。
4.解析取到的xml格式的字符串，取得推送上行内容的各个节点的值，DOM4j解析参考如下：
Document doc = DocumentHelper.parseText(字符串);
Element root = doc.getRootElement();
List<Element> deliverElements = root.elements("deliver");
for(Element deliver:deliverElements){

String corp_id = deliver.elementText("corp_id");
String mobile = deliver.elementText("mobile");
String ext = deliver.elementText("ext");
String time = deliver.elementText("time");
String content = deliver.elementText("content");

System.out.println(corp_id+":"+mobile+":"+ext+":"+time+":"+content);
}

第 9 页 共 9 页