河北电信行业短信平台--接口手册

1、06:889006:8890行业短信平台行业短信平台接口手册接口手册产品名称产品名称行业短信平台行业短信平台发布日期发布日期2011-052011-05河北电信行业短信平台-接口手册 中国电信河北分公司 第 2 页 共 26 页目目 录录1 1、引言引言.3 31.1.目的.31.2.修改历史记录.31.3.名称解释.32 2、短信短信.4 42.1.HTTP接口.42.1.1. 短信下行.42.1.2. 短信上行.72.1.3. 短信状态报告.82.1.4. 查询余额.92.2.API接口 .102.3.WEBSERVICE接口（不推荐）.14

2、2.3.1. 自定义数据结构.142.3.2. 短信下行（发送多条内容相同的短信）.162.3.3. 短信下行（发送多条内容不同的短信）.172.3.4.获取上行.172.3.5.获取状态报告（单条）.182.3.6.获取状态报告（多条）.182.3.7. 获取余额.192.4.WEBSERVICE接口(新，推荐使用).192.4.1. 自定义数据结构.192.4.2. 短信下行（发送一条或者多条内容相同的短信）.192.4.3. 短信下行（发送内容不同的短信）.202.4.4.获取上行.212.4.5.获取状态报告.222.4.6. 获取余额.232.4.7.短信 webservice（新）

3、错误码.242.5.WEBSERVICE接口(支持上下行子号码).242.5.1. 自定义数据结构.242.5.2. 短信下行（发送一条或者多条内容相同的短信）.252.5.3. 短信下行（发送内容不同的短信）.262.5.4.获取上行.272.5.5.获取状态报告.282.5.6. 获取余额.292.5.7.短信 webservice 错误码.30河北电信行业短信平台-接口手册 中国电信河北分公司 第 3 页 共 26 页1 1、 引言引言. 目的目的该接口手册编写目的在于描述短信平台 CTC-EMP（以下简称 CTC-EMP）具体的接口协议，供接口用户进行接口的对接开发。1.

4、2.1.2. 修改历史记录修改历史记录版版 本本修改人修改人日日 期期描描 述述5.0.1顾黎杰2006/8/10创建文档。5.0.2顾黎杰2008/6/20增加短信 api 接口。5.0.3顾黎杰2010/5/5细化接口返回参数。5.0.3赵鸿2011/5/6WebService 接口(支持上下行子号码)5.3.8王鹏2011/8/26细化 HTTP 下行 SUBCODE 参数描述. 名称名称解释解释缩略语缩略语英文全名英文全名中文全名中文全名SMSShort Messaging Service短消息服务MMSMultimedia Message Service多媒体消息API

5、Application Programming Interface应用程序编程接口MOMessage Original消息上行MTMessage Terminal消息下行SPService Provider服务提供商CPContent Provider内容提供商河北电信行业短信平台-接口手册 中国电信河北分公司 第 4 页 共 26 页2 2、 短信短信. http 接口接口.1.1. 短信下行短信下行功能：下发单条或者多条内容相同的短信。地址： 31:8080/emp/http/SendSms。建议采用 post 方法提交请求。

6、请求参数定义如下： 参数名称描述字段值Account帐号String，不空。Password密码String，不空（需 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”用户可以用此例子验证加密方法是否正确） 。SubCode子号码String，可以为空。格式为企业帐号+子号码。例如：如果平台号码为“10650300” ，企业帐号为 2，子号码为“22” ，则 SubCode 设置为“222” ，短信将以“10650300222”号码下发给手机用户(注：此功能需要通道支持)。Phone手机号码String，

7、不空，支持多号码，号码之间用英文逗号隔开，最多 100 个。如13900000000。Content短信内容String，不空 。GBK 编码Java 例:.URLEncoder.encode(Content, UTF-8)。WappushurlWappushurlWappush 地址，如果需要发送Wappush，则 Content 表示 titleSendTime定时发送时间String，可以为空，为空就是立即发送。定时发送格式为年月日时分，如：200803201615。返回参数定义如下：河北电信行业短信平台-接口手册 中国电信河北分公司 第 5 页 共 26 页参

8、数名称描述response0：成功条数；-1：帐号不存在，请检查用户名或者密码是否正确；-2：账户余额不足；-3：帐号已被禁用；-4：ip 鉴权失败（需要 ip 校验的场合） ；-8：缺少请求参数或参数不正确（请检查用户名，密码，下发号码，下发内容是否为空，或者下发号码数量是否大于100 个） ；-9：内容不合法（含有非法内容，请检查下发内容） 。-10：账户当日发送短信量已经超过允许的每日最大发送量（账户被限制每日发送短信数量的情况有用）phone手机号。smsID短信 ID（用于匹配状态报告） 。下发实例（java）：import java.io.BufferedReader;import

9、 java.io.InputStreamReader;import java.io.OutputStream;import .HttpURLConnection;import .URL;import java.security.MessageDigest;public class HttpSend public static void main(String args) try Long startt = System.currentTimeMillis(); / 短信内容String _content = 测试,见谅;/ 用UTF-8编码执行URLEncode_content = .URLE

10、ncoder.encode(_content, UTF-8);/ 密码加密String pass = MD5Encode(10);String _url = 1:8080/ctc-emassh/http/SendSms;String _param = Account=10&Password= + pass+ &Phoneamp;Content= + _content+ &SubCode=&SendTime=;URL url = null;HttpURLConnection urlConn = null;u

11、rl = new URL(_url);urlConn = (HttpURLConnection) url.openConnection();河北电信行业短信平台-接口手册 中国电信河北分公司 第 6 页 共 26 页urlConn.setRequestMethod(POST);urlConn.setDoOutput(true);OutputStream out = urlConn.getOutputStream();out.write(_param.getBytes(GBK);out.flush();out.close();BufferedReader rd = new BufferedRea

12、der(new InputStreamReader(urlConn.getInputStream(), GBK);StringBuffer sb = new StringBuffer();int ch;while (ch = rd.read() -1) sb.append(char) ch);System.out.println(sb);rd.close();Long end = System.currentTimeMillis();System.out.println(发送 短信 耗时： + (end - startt); catch (Exception ex) System.out.pr

13、int(ex);public static String MD5Encode(String sourceString) String resultString = null;try resultString = new String(sourceString);MessageDigest md = MessageDigest.getInstance(MD5);resultString = byte2hexString(md.digest(resultString.getBytes(); catch (Exception ex) return resultString;public static

14、 final String byte2hexString(byte bytes) StringBuffer bf = new StringBuffer(bytes.length * 2);for (int i = 0; i bytes.length; i+) if (bytesi & 0 xff) 0 x10) bf.append(0);bf.append(Long.toString(bytesi & 0 xff, 16);河北电信行业短信平台-接口手册 中国电信河北分公司 第 7 页 共 26 页return bf.toString();失败返回页面示例： - -8 成功返回

15、页面示例： - 2 -2c92811a29a0c90c0129a0ca984e0016 -2c92811a29a0c90c0129a0ca984e0015 .1.2. 短信上行短信上行功能：接收若干条手机用户的上行短信（一次最多十条） 。地址： 31:8080/emp/http/GetSms。建议采用 post 方法提交请求。调用短信上行间隔时间不小于 30 秒。请求参数定义如下：参数名称描述字段值Account帐号String，不空。Password密码String，不空（需 MD5 加密）

16、 。返回参数定义如下：参数名称描述response大于 0：上行短信的条数，一次最多取 10 条；0：没有上行短信；-1：帐号登陆失败；河北电信行业短信平台-接口手册 中国电信河北分公司 第 8 页 共 26 页-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。-9：访问速度太快，每次访问间隔不能小于 30 秒phone手机号。content短信内容；已经用 .URLEncoder.encode()编码；需要用 .URLDecoder.decode()解码。sendTime上行时间。无短信或者参数错误返回页面示例： - 0 成功返回短信页面示例：（一次最多取 10 条）- 3- 1

17、376612345678test2009-02-06 09:01:33.0- 1386612345678%E6%B5%8B%E8%AF%952009-02-06 09:01:33.0- 1396612345678abc2009-02-06 09:01:33.0.1.3. 短信状态报告短信状态报告功能：根据 SmsID 返回短信是否成功发送到用户手机。地址： 31:8080/emp/http/GetReport。建议采用 post 方法提交请求。调用短信状态报告间隔时间不小于 30 秒。河北电信行业短信平台-接口手册 中国电信河北分公司 第 9

18、页 共 26 页请求参数定义如下：参数名称描述字段值Account帐号String，不空。Password密码String，不空（需 MD5 加密） 。SmsID消息 IDString，不空。返回参数定义如下：参数名称描述response大于 0：此消息 ID 所对应的状态报告条数。最多 100 条；0：没有此消息 ID 的状态报告；-1：帐号登陆失败；-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。-9：访问速度太快，每次访问间隔不能小于 30 秒phone手机号。smsID消息 ID。stat状态报告0：成功；2：发送失败。请求错误返回页面示例： - -8 请求成功返回页面示

19、例： - 1 -2c92812d1ebf8704011ebf939ba80004 0 河北电信行业短信平台-接口手册 中国电信河北分公司 第 10 页 共 26 页.1.4. 查询余额查询余额功能：查询剩余短信的条数。地址： 31:8080/emp/http/GetBalance。建议采用 post 方法提交请求。调用查询余额间隔时间不小于 30 秒。请求参数定义如下：参数名称描述字段值Account帐号String，不空。Password密码String，不空（需 MD5 加密） 。返回参数定义如下：参数名称描述re

20、sponse-1：帐号登陆失败；-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。sms短信余额。mms彩信余额。返回页面示例： - 10002000 . api 接口接口相关 jar 包包括：ctc-smsclient.jar，ctc-message.jar，ctc-slidewindow.jar，ctc-sync.jar，ctc-util.jar。注意：只有外部企业才能使用此接口注意：只有外部企业才能使用此接口名称initConn功能连接初始化。接口方法public int initConn(String host, int port, String user,

21、String password) 河北电信行业短信平台-接口手册 中国电信河北分公司 第 11 页 共 26 页输入说明host：CTC-EMP 的 ip；port：CTC-EMP 的端口；user：接口用户名；password：接口密码。输出说明0成功1已经登陆2用户名错误3密码错误4客户端 ip 错误（需要校验 ip 的时候需要）5 其他名称sendSms功能发送短信。接口方法public boolean sendSms(String from, String to, String msg) 输入说明from：子号码，一般不填写；to：手机号码，支持多号码，以英文逗号隔开。建议一次最多10

22、0 个；msg：短信内容。输出说明true：成功；false：失败。名称onSubmitedSMS功能接收下行短信响应。sendSms 方法不直接返回下行响应，由此方法返回，此方法为回调方法，不需要手动调用。接口方法public boolean onSubmitedSMS(ISubmitMsg arg0) 输入说明arg0：下行数据结构，具体支段见示例。输出说明true：成功；false：失败。河北电信行业短信平台-接口手册 中国电信河北分公司 第 12 页 共 26 页名称onDeliverSMS功能接收上行短信。此方法为回调方法，不需要手动调用。接口方法public boolean onD

23、eliverSMS(IDeliverMsg arg0) 输入说明arg0：上行数据结构，具体支段见示例。输出说明true：成功；false：失败。名称onMTReportSMS功能接收状态报告。此方法为回调方法，不需要手动调用。接口方法public boolean onMTReportSMS(IReportMsg arg0)输入说明arg0：状态报告数据结构，具体支段见示例。输出说明true：成功；false：失败。示例程序：import com.chinatricom.message.IDeliverMsg;import com.chinatricom.message.IReportMsg;

24、import com.chinatricom.message.ISubmitMsg;import com.chinatricom.slidewindow.SMSCallback;import com.chinatricom.smsclient.ctcpp.CtcppChannel;import com.chinatricom.smsclient.message.DeliverMsg;import com.chinatricom.smsclient.message.ReportMsg;import com.chinatricom.smsclient.message.SubmitMsg;/* *

25、title: 调用CTC-SMS API客户端接口 SMSUtil.java create on 2010-10-26 copyright (c) * 2010-10-26 * * author * version 1.0 */public class SMSUtil implements SMSCallback public static CtcppChannel _chan = null;河北电信行业短信平台-接口手册 中国电信河北分公司 第 13 页 共 26 页static / 相关参数定义SMSUtil _client = new SMSUtil();String host = 12

26、; / 调用IP地址int port = 28013; / 调用IP地址的端口String user = 8888; / 用户名String passwd = 8888;/ 密码int wndSize = 16;int timeout = 60 * 1000; / 连接超时时间int trys = 3;int speed = 0;/ 记录日志System.out.println(start);/ 开启通道_chan = new CtcppChannel(host, port, user, passwd, 1, wndSize, timeout,trys, speed, _clie

27、nt, 0, 0, 1, 1);_chan.start();/* * 这个函数接收上行短信，短信的各个字段都放在DeliverMsg */public boolean onDeliverSMS(IDeliverMsg arg0) DeliverMsg msg = (DeliverMsg) arg0;if (msg != null) System.out.println(收到deliverMsg:phone= + msg.getFrom() + ,内容=+ msg.getMsg() + ,to= + msg.getTo();return true;/* * 这个函数接收下发短信的状态报告，它通过

28、msgid关联到下行短信 result : 0成功 1等待发送 2失败 */public boolean onMTReportSMS(IReportMsg arg0) ReportMsg msg = (ReportMsg) arg0;if (msg != null) System.out.println(收到repot: result= + msg.getResult() + );河北电信行业短信平台-接口手册 中国电信河北分公司 第 14 页 共 26 页return true;/* * 这个函数接收下行短信的response，SubmitMsg里面有了result和msgId,这里的msg

29、就是_chan.submit(_msg) * 里面的_msg。 result = 0 表示成功， 其他均为失败。 */public boolean onSubmitedSMS(ISubmitMsg arg0) SubmitMsg msg = (SubmitMsg) arg0;if (msg != null) System.out.println(收到submit response:result + =+ msg.getResult() + , msgid= + msg.getMsgId();return true;/* * 下发方法入口 */public static void sendSMS

30、(String phoneNumber, String smsContext) try SubmitMsg _msg = new SubmitMsg();_msg.setChanId(1);_msg.setFrom(1);_msg.setTo(phoneNumber);_msg.setMsg(smsContext);_chan.submit(_msg); catch (Exception e) e.printStackTrace(); finally public static void main(String args) SMSUtil.sendSMS test);

31、. WebService 接口接口地址：31:8080/emp/services/SmsNewOperator河北电信行业短信平台-接口手册 中国电信河北分公司 第 15 页 共 26 页.3.1. 自定义数据结构自定义数据结构MtNewMessage参数名称类型说明smsIdString消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumberString手机号码。支持多号码，号码之间用英文逗号隔开,建议最多 100 个。如13900000000

32、。contentString短信内容。scheduleTimeDate下行时间，可以为空。WappushurlStringWappush 地址，如果需要发送 Wappush，则 Content 表示 title.3.2. 短信下行（发送一条或者多条内容相同的短信）短信下行（发送一条或者多条内容相同的短信）名称sendSms功能发送一条或则多条内容相同的短信。接口方法sendSms(String account, String password, MtNewMessage message,StringHolder sendResMsg, StringHolder errMsg) 输

33、入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；message对象，详情请参照自定义数据结构：MtNewMessage。输出说明sendResMsg：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）北电信行业短信平台-接口手册 中国电信河北分公司 第 16 页 共 26 页2c9281e22c1ac7c2012c1adc8bdb0021132-7errMsg：

34、输出参数，小于零时表示下发错误，详情见错误码.3.3. 短信下行（发送内容不同的短信）短信下行（发送内容不同的短信）名称batchSendSms功能发送一条或则多条内容相同的短信。接口方法batchSendSms(String account, String password, MtNewMessage message,StringHolder sendResMsg, StringHolder errMsg) 输入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b

35、3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；message对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明sendResMsg：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）北电信行业短信平台-接口手册 中国电信河北分公司 第 17 页 共 26 页2c9281e22c5d9f77012c5da2d0b7001b150007927992c9281e22c5d9f77012c5da2d0c0001c errMsg：输出参数，小于零时表示下发错误，详情见错误码.3.4. 获取上行获取上行调

36、用短信上行间隔时间不小于 30 秒。名称getSms功能获取上行短信，一次最多取 10 条。接口方法getSms(String account, String password, StringHolder resMsg,StringHolder errMsg)输入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） 。输出说明resMsg：返回上行短信（当errMsg 不为负值时该值有效）格式（无换行符）：1500

37、0792799河北电信行业短信平台-接口手册 中国电信河北分公司 第 18 页 共 26 页Test MO! 测试 Deliver 消息est MO! 测试 Deliver 消息!没有上行时返回：errMsg：输出参数，小于零时表示下发错误，详情见错误码.3.5. 获取状态报告获取状态报告调用短信状态报告间隔时间不小于 30 秒。名称getReport功能获取一条或者多条状态报告。接口方法getReport(String account, String password,MtNewMessage message, StringHolder reportM

38、sg, StringHolder errMsg)输入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；MtNewMessage，详情请参照自定义数据结构：MtNewMessage,包含消息序号和手机号码的对象数组。 （只需要填写smsId 和 phoneNumber 字段） 。输出说明reportMsg: 返回状态报告（当 errMsg 不为负值时该值有效）格式（无换行符）：河北电信行业短信平台-接口手册 中

39、国电信河北分公司 第 19 页 共 26 页138877878782c9281e22bf60182012bf6025949001a0138877878792c9dd1e22aa6018dd12bf60ff59490550无状态报告时返回：errMsg: 输出参数，小于零时表示下发错误，详情见错误码.3.6. 获取余额获取余额调用获取余额报告间隔时间不小于 30 秒。名称getBalance功能获取帐号余额。接口方法getBalance(String account, String password,StringHolder resMsg, StringHolder errMsg)

40、输入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） 。输出说明resMsg：返回账户余额（当 errMsg 不为负值时该值有效）格式（无换行符）：河北电信行业短信平台-接口手册 中国电信河北分公司 第 20 页 共 26 页043216errMsg: 输出参数，小于零时表示下发错误，详情见错误码.3.7. 短信短信 webservicewebservice（新）错误码（新）错误码-1：输入参数不

41、正确，请检查账户，密码，等输入参数是否为空-2：账户不存在，请检查用户名密码是否正确-3：账户已经超过每日发送短信限制数量（当账户被限制每日发送量时有用）-4：客户端 ip 地址不正确（当需要 ip 校验时）-5：smsId 与数据库重复（下发短信时，如果smsId 由客户端传入，该参数不能重复）-6：内容含有非法关键字，请检查下发内容。-7：对应的号码下发失败，下发号码为空或其他错误，导致该号码发送失败. WebService 接口接口(支持上下行子号码支持上下行子号码)地址： 31:8080/emp/services/SmsNewOpera

42、toraddsubCode前提：下发通道支持子号码.4.1. 自定义数据结构自定义数据结构MtNewMessage参数名称类型说明smsIdString消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumberString手机号码。支持多号码，号码之间用英文逗号隔开,建议最多 100 个。如13900000000。contentString短信内容。scheduleTimeDate下行时间，可以为空。WappushurlStringWappush 地址，如果需要发送 Wappush，则 Conte

43、nt 表示 title河北电信行业短信平台-接口手册 中国电信河北分公司 第 21 页 共 26 页.4.2. 短信下行（发送一条或者多条内容相同的短信）短信下行（发送一条或者多条内容相同的短信）名称sendSms功能发送一条或则多条内容相同的短信。接口方法sendSms(String account, String password, MtNewMessage message,String subCode,StringHolder sendResMsg, StringHolder errMsg) 输入说明account 用户账号；password 用户密码（用 MD5 加密，3

44、2 位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；subCode :子号码，需要通道支持，手机终端用户收到的信息发送号码将是长号码 + 子号码( account + 自定义子号码)message对象，详情请参照自定义数据结构：MtNewMessage。输出说明sendResMsg：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：150000000002c9281e22c1ac7c2012c1adc8bdb0021132-7errMsg：输出参数，小于零时表示下发错

45、误，详情见错误码.4.3. 短信下行（发送内容不同的短信）短信下行（发送内容不同的短信）名称batchSendSms河北电信行业短信平台-接口手册 中国电信河北分公司 第 22 页 共 26 页功能发送一条或则多条内容相同的短信。接口方法batchSendSms(String account, String password, MtNewMessage message, String subCode,StringHolder sendResMsg, StringHolder errMsg) 输入说明account 用户账号；password 用户密码（用 MD5 加密，32 位，

46、加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；subCode :子号码，需要通道支持，手机终端用户收到的信息发送号码将是长号码 + 子号码message对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明sendResMsg：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：150007927992c9281e22c5d9f77012c5da2d0b7001b150007927992c9281e22c5d9f77012c5da2d0c0001c 河北电信行业短信平台-接口手册 中国电信河北分公司 第 23 页 共 26 页errMsg：输出参数，小于零时表示下发错误，详情见错误码.4.4. 获取上行获取上行调用短信上行间隔时间不小于 30 秒。名称getSms功能获取上行短信，一次最多取 10 条。接口方法getSms(String account, String password, StringHolder resMsg,StringHolder errMsg)输入说明account 用户