通讯协议
双方通过HTTP方式交互数据,第三方可以简单的“name=value”方式发送提交内容或响应请求内容。即通过HTTP的GET/POST方式交换。
接口编码
消息内容(参数名msg)默认GBK编码.使用其他编码,需在请求url中增加参数,encode=编码.服务端将获取encode参数的值进行解码。
应答格式
服务器的应答格式为纯文本,如返回:
失败返回 -1,描述信息 -1表示错误代码,描述信息是对错误的描述.描述信息部分可为空。
如包含屏蔽词,使用提交的编码解码,返回结果示例如下:
-21,包含屏蔽词:啊啊
成功返回 0,4213 0表示成功提交,4213返回消息的MSGID(对应报告中的RPTID)
消息发送
URL: http://ip:port/
即时发送调用示例:
http://ip:port/hy/?uid=1234&auth=faea920f7412b5da7be0cf42b8c93759&mobile=13612345678&msg=hello&expid=0
定时发送调用示例:
http://ip:port/hy/?uid=1234&auth=faea920f7412b5da7be0cf42b8c93759&mobile=13612345678&msg=hello&expid=0
&time=2011-06-20+11:20:30
&time=2011-06-20+11:20:30
时间格式如: 2011-06-20 11:20:30
时间中包含空格及冒号,在提交时,使用和内容相同的编码格式编辑或 直接替换:空格替换为”+”号,冒号替换为”%3A”,实际上”+”即为编码后的空格,”%3A”为编码后的冒号
Post方式提交:
Time参数无需替换或编码,可直接赋值参数提交,形如:2011-06-20 11:20:30
发送方式:GET/POST
请求参数:
参数名 | 说明 | 必须 | 说明 |
uid | 用户编号 | 是 | 登录用户ID |
auth | 签权验证 | 是 | MD5(企业代码+用户密码),32位加密小写 |
mobile | 被叫号码 | 是 | 被叫用户,同时发送给多个用户,号码间用逗号分隔 Get: 最大支持300, Post: 最大支持2000 (建议尽量用大包提交) |
msg | 下行消息 | 是 | 消息内容,默认GBK编码,使用其他编码,设encode=编码,服务器在收到消息时,取参数encode进行解码,内容长度不能超过603,
(单个中文字符或英文字符或符号计算为1个长度) |
expid | 拓展码 | 是 | 允许用户自行拓展3位,1-999.expid=0表示不拓展. |
encode | 编码 | 否 | 若使用非默认编码,需设置此参数.如encode=utf-8 |
time | 定时时间 | 否 | 定时发送时间,格式为 yyyy-MM-dd HH:mm:ss,此参数的值必须是有效时间,即时短信可略去此参数 |
附录
响应代码的定义如下:
状态码 | 描述 |
0 | 操作成功 |
-1 | 签权失败 |
-2 | 未检索到被叫号码 |
-3 | 被叫号码过多 |
-4 | 内容未签名 |
-5 | 内容过长 |
-6 | 余额不足 |
-7 | 暂停发送 |
-8 | 保留 |
-9 | 定时发送时间格式错误 |
-10 | 下发内容为空 |
-11 | 账户无效 |
-12 | Ip地址非法 |
-13 | 操作频率快 |
-14 | 操作失败 |
-15 | 拓展码无效 |
-16 | 取消定时,seqid错误 |
-17 | 未开通报告 |
-18 | 暂留 |
-19 | 未开通上行 |
-20 | 暂留 |
-21 | 包含屏蔽词 |
GET方式发送示例:
public static void main(String[] args) {
SendTest_Get t=new SendTest_Get();
String mobile="13612345678";
String content="http接口测试";
String urlstr="http://ip:port/hy?uid=1234
&auth=faea920f7412b5da7be0cf42b8c93759&mobile=13612345678&msg="
+java.net.URLEncode.encode(content,"gbk")+"&expid=0";
String str=t.doGetRequest(urlstr);
System.out.println("响应:"+str);
}
public String doGetRequest(String urlstr) {
String res = null;
HttpClient client = new HttpClient(
new MultiThreadedHttpConnectionManager());
client.getParams().setIntParameter("http.socket.timeout", 10000);
client.getParams().setIntParameter("http.connection.timeout", 5000);
HttpMethod httpmethod = new GetMethod(urlstr);
try {
int statusCode = client.executeMethod(httpmethod);
if (statusCode == HttpStatus.SC_OK) {
res = httpmethod.getResponseBodyAsString();
}
} catch (HttpException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} finally {
httpmethod.releaseConnection();
}
return res;
}
POST方式发送示例:
public static void main(String[] args) throws IOException {
HttpClient httpClient = new HttpClient();
String url = "http://ip:port/hy/";
String uid = "1234";
String auth = new MD5().getMD5ofStr("企业代码密码");
String mobile = "136123456787";
String content=java.net.URLEncoder.encode("测试消息", "gbk");
PostMethod postMethod = new PostMethod(url);
postMethod.setRequestHeader("Content-Type","application/x-www-form-urlencoded;charset=gbk");
NameValuePair[] data = {
new NameValuePair("uid", uid),
new NameValuePair("auth", auth),
new NameValuePair("mobile", mobile),
new NameValuePair("expid", "0"),
new NameValuePair("msg",content )
};
postMethod.setRequestBody(data);
int statusCode = httpClient.executeMethod(postMethod);
if (statusCode == HttpStatus.SC_OK) {
String sms = postMethod.getResponseBodyAsString();
System.out.println("result:" + sms);
}
System.out.println("statusCode="+statusCode);
}