三通运营平台CTCOSS接口手册1

1、大汉三通三通运营平台接口手册产品名称三通运营平台版本编号文档编号发布者上海大汉三通网络通信有限公司发布日期最后修改日期2011/11/9目 录目录1、引言61.1.目的61.2.名称解释62、短信62.1.API接口62.2.WebService接口122.2.1.自定义数据结构122.2.2.短信下行（发送一条或者多条内容相同的短信）122.2.3.短信下行（发送内容不同的短信）132.2.4.获取上行142.2.5.获取状态报告152.2.6.获取余额162.2.7.短信webservice错误码172.3.WebService接口（xml方式传输数据）172.3.1.短信下行182.3.

2、2.短信上行192.3.3.短信状态报告212.3.4.查询余额232.4.http接口（xml方式传输数据）242.4.1.短信下行252.4.2.短信上行262.4.3.短信状态报告282.4.4.查询余额29保密本文件及其内容为上海大汉三通网络通信有限公司保密资料。本文件及其内容永远属于上海大汉三通网络通信有限公司拥有财产，在无上海大汉三通网络通信有限公司采用书面形式表示同意外，本文件a. 不可以用于其他非原指定用途；b. 不可以向第三方披露；c. 不可采用任何形式进行复制和传播，包括但不限于传真、纸张邮件和电子邮件。文档修改历史版 本修改人日 期描 述1.0.0汤喜金2011/6/1创

3、建文档。短信部分接口。周艳2011/7/7文档格式修改，符合公司内部文档规范要求。汤喜金2011/11/14增加xml方式传输数据的WebService接口1、 引言1.1. 目的该接口手册编写目的在于描述三通运营平台CTC-OSS（以下简称CTC-OSS）具体的接口协议，供接口用户进行接口的对接开发。1.2. 名称解释缩略语英文全名中文全名CTC-OSSOperational Support System三通运营平台SMSShort Messaging Service短消息服务MMSMultimedia Message Service多媒体消息APIApplication Programmi

4、ng Interface应用程序编程接口MOMessage Original消息上行MTMessage Terminal消息下行SPService Provider服务提供商CPContent Provider内容提供商2、 短信2.1. API接口相关jar包包括：ctc-smsclient.jar，ctc-message.jar，ctc-slidewindow.jar，ctc-sync.jar，ctc-util.jar。注意：终端客户的接入方式设置为API接入时才能使用此接口名称initConn功能连接初始化。接口方法public int initConn(String host, int

5、 port, String user, String password) 输入说明host：CTC-OSS的ip；port：CTC-OSS的端口；user：接口用户名；password：接口密码。输出说明0成功1已经登陆2用户名错误3密码错误4客户端ip错误（需要校验ip的时候需要）5 其他名称sendSms功能发送短信。接口方法public boolean sendSms(String from, String to, String msg) 输入说明from：子号码，一般不填写；to：手机号码，支持多号码，以英文逗号隔开。建议一次最多100个；msg：短信内容。输出说明true：成功；fa

6、lse：失败。名称onSubmitedSMS功能接收下行短信响应。sendSms方法不直接返回下行响应，由此方法返回，此方法为回调方法，不需要手动调用。接口方法public boolean onSubmitedSMS(ISubmitMsg arg0) 输入说明arg0：下行数据结构，具体支段见示例。输出说明true：成功；false：失败。名称onDeliverSMS功能接收上行短信。此方法为回调方法，不需要手动调用。接口方法public boolean onDeliverSMS(IDeliverMsg arg0) 输入说明arg0：上行数据结构，具体支段见示例。输出说明true：成功；fal

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

8、ck;import com.chinatricom.smsclient.ctcpp.CtcppChannel;import com.chinatricom.smsclient.message.DeliverMsg;import com.chinatricom.smsclient.message.ReportMsg;import com.chinatricom.smsclient.message.SubmitMsg;/* * title: 调用CTC-SMS API客户端接口 SMSUtil.java create on 2010-10-26 copyright (c) * 2010-10-26

9、 * * author * version 1.0 */public class SMSUtil implements SMSCallback public static CtcppChannel _chan = null;static / 相关参数定义SMSUtil _client = new SMSUtil();String host = "" / 调用IP地址int port = 28013; / 调用IP地址的端口String user = "8888" / 用户名String passwd = "8888"

10、/ 密码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, _client, 0, 0, 1, 1);_chan.start();/* * 这个函数接收上行短信，短信的各个字段都放在DeliverMsg */public bool

11、ean onDeliverSMS(IDeliverMsg arg0) DeliverMsg msg = (DeliverMsg) arg0;if (msg != null) System.out.println("收到deliverMsg:phone=" + msg.getFrom() + ",内容="+ msg.getMsg() + ",to=" + msg.getTo();return true;/* * 这个函数接收下发短信的状态报告，它通过msgid关联到下行短信 result : 0成功 1等待发送 2失败 */public

12、 boolean onMTReportSMS(IReportMsg arg0) ReportMsg msg = (ReportMsg) arg0;if (msg != null) System.out.println("收到repot: result=" + msg.getResult() + "");return true;/* * 这个函数接收下行短信的response，SubmitMsg里面有了result和msgId,这里的msg就是_chan.submit(_msg) * 里面的_msg。 result = 0 表示成功， 其他均为失败。 */

13、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(String phoneNumber, St

14、ring 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");2.2. WebSe

15、rvice接口注意：终端客户的接入方式设置为WebService接入时才能使用此接口访问地址：:8090/services/SendSms2.2.1. 自定义数据结构MtNewMessage参数名称类型说明smsIdString消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumberString手机号码。支持多号码，号码之间用英文逗号隔开,建议最多100个。如：contentString短信内容。scheduleTimeDate下行时间，可以为空。WappushurlStringWappush 地址，如果需要发送Wappush，则 C

16、ontent表示 title2.2.2. 短信下行（发送一条或者多条内容相同的短信）名称sendSms功能发送一条或则多条内容相同的短信。接口方法sendSms(String account, String password, MtNewMessage message) 输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；message对象，详情请参照自定义数据结构：MtNewMessage。输出说明String 字符

17、串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：<sendResp><sms><phone>lt;/phone><smsID>2c9281e22c1ac7c2012c1adc8bdb0021</smsID></sms><sms><phone>132</phone><smsID>-7</smsID></sms></s

18、endResp>2.2.3. 短信下行（发送内容不同的短信）名称batchSendSms功能发送一条或则多条内容相同的短信。接口方法batchSendSms(String account, String password, MtNewMessage message) 输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；message对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明String

19、 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：<batchSendResp><sendResp><sms><smsID>2c9281e22c5d9f77012c5da2d0b7001b</smsID></sms></sendResp><sendResp><sms><smsID>2c9281e22c5d9f77012c5da2d0c0001c</smsID>

20、;</sms></sendResp></batchSendResp> 2.2.4. 获取上行调用短信上行间隔时间不小于30秒。名称getSms功能获取上行短信，一次最多取10条。接口方法getSms(String account, String password)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）。输出说明String 字符串数组String0：输出参数，小于零时表示

21、下发错误，详情见错误码String1：返回上行短信（当errMsg 不为负值时该值有效）格式（无换行符）：<mosms><sms><content>Test MO! 测试Deliver消息!</content></sms><sms><content>Test MO! 测试Deliver消息!</content></sms></mosms>没有上行时返回：<mosms></mosms>2.2.5. 获取状态报告调用短信状态报告间隔时间不小于30秒。名称g

22、etReport功能获取一条或者多条状态报告。接口方法getReport(String account, String password,MtNewMessage message)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；MtNewMessage，详情请参照自定义数据结构：MtNewMessage,包含消息序号和手机号码的对象数组。（只需要填写smsId和phoneNumber字段）。输出说明String 字

23、符串数组String0: 输出参数，小于零时表示下发错误，详情见错误码String1: 返回状态报告（当errMsg 不为负值时该值有效）格式（无换行符）：<smsReport><sms><pho<smsID>2c9281e22bf60182012bf6025949001a</smsID><stat>0</stat></sms><sms><smsID>2c9dd1e22aa6018dd12bf60ff5949055</smsID><stat>0</st

24、at></sms></smsReport>无状态报告时返回：<smsReport></smsReport>2.2.6. 获取余额调用获取余额报告间隔时间不小于30秒。名称getBalance功能获取帐号余额。接口方法getBalance(String account, String password)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）。输出说明Str

25、ing 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：返回账户余额（当errMsg 不为负值时该值有效）格式（无换行符）：<userBalance><sms>0</sms><mms>43216</mms></userBalance>2.2.7. 短信webservice错误码-1：输入参数不正确，请检查账户，密码，等输入参数是否为空-2：账户不存在，请检查用户名密码是否正确-3：账户已经超过每日发送短信限制数量（当账户被限制每日发送量时有用）-4：客户端ip地址不正确（当需要ip校验

26、时）-5：smsId与数据库重复（下发短信时，如果smsId 由客户端传入，该参数不能重复）-6：内容含有非法关键字，请检查下发内容。-7：对应的号码下发失败，下发号码为空或其他错误，导致该号码发送失败-8：账户余额不足2.3. WebService接口（xml方式传输数据）注意：终端客户的接入方式设置为WebService接入时才能使用此接口。该接口数据输入输出均采用xml格式封装的字符串，编码统一为UTF-8。访问地址：:8090/services/sms2.3.1. 短信下行名称submit功能发送一条或则多条内容相同的短信接口方法String submit (String messag

27、e)输入说明message参数xml格式如下：<?xml version="1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password><msgid>2c92825934837c4d0134837dcba00150</msgid><phones></phones><conte

28、nt>短信内容</content><subcode>5555</subcode><sendtime>201101011230</sendtime></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：加密后为bb43a2c4081bec02fca7b72f38e63021msgid：该批短信编号(32位UUID)，需保证唯一，可空，建议为空phones：接收手机号码，多个手机号码用英文逗号分隔，最多500，不能为空content：短信内容，最多500个汉字，

29、不能为空subcode：扩展子号码，可空（验证格式和长度，不能超过20位）sendtime：发送时间,格式yyyyMMddHHmm,可空(12位数字，年月日时分，比如201111180929)输出说明返回的结果xml格式如下：<?xml version="1.0" encoding="UTF-8"?><response><msgid>2c92825934837c4d0134837dcba00150</msgid><result>0</result> <desc>提交成功&

30、lt;/desc></response>字段说明：msgid：该批短信编号result：该批短信提交结果0提交成功1账号无效2密码错误3msgid不唯一4存在无效手机号码5手机号码个数超过最大限制6短信内容超过最大限制7扩展子号码无效8发送时间格式无效9请求来源地址无效10内容包含敏感词11余额不足97接入方式错误98系统繁忙99消息格式错误2.3.2. 短信上行名称deliver功能获取上行短信。每次调用间隔需大于30秒接口方法String deliver(String message)输入说明message 参数xml格式如下：<?xml version="

31、;1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：<?xml version="1.0

32、" encoding="UTF-8"?><response><result>0</result> <desc>成功</desc><sms><phone></phone><content>短信内容</content> <subcode>5555</subcode><delivertime>2011-11-11 11:11:11</delivertime></sms></resp

33、onse>字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快9请求来源地址无效97接入方式错误98系统繁忙99消息格式错误如果result为0时sms标签对将出现0到多次，否则sms标签不出现。phone：上行手机号码content：上行短信内容delivertime：上行接收时间，格式yyyy-MM-dd HH:mm:ss2.3.3. 短信状态报告名称report功能获取下行短信状态报告，每次调用间隔需大于30秒。接口方法String report(String message)输入说明message参数xml格式如下：<?xml version="

34、;1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password><msgid>2c92825934837c4d0134837dcba00150</msgid><phone></phone></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密

35、(小写)，如：加密后为bb43a2c4081bec02fca7b72f38e63021msgid：下行短信编号，可空phone：接收下行手机号码，可空输出说明返回的结果xml格式如下：<?xml version="1.0" encoding="UTF-8"?><response><result>0</result> <desc>成功</desc><report><msgid>2c92825934837c4d0134837dcba00150</msgid&

36、gt;<phone></phone><status>0</status> <desc>成功</desc></report></response>字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快4手机号码无效9请求来源地址无效97接入方式错误98系统繁忙99消息格式错误当result为0时report标签对将出现0到多次，否则report标签不出现msgid：短信编号phone：下行手机号码content：上行短信内容status：短信发送结果0成功1失败2发送中2.3.4.

37、查询余额名称balance功能获取余额，每次调用间隔需大于60秒。接口方法String balance(String message)输入说明message参数xml格式如下：<?xml version="1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password></message>字段说明：account ：用户

38、账号password：账号密码，需采用MD5加密，如：加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：<?xml version="1.0" encoding="UTF-8"?><response><result>0</result><desc>成功</desc><sms><amount>100.000</amount><number>500</number><

39、freeze>0.000</freeze></sms><mms><amount>200.000</amount><number>500</number><freeze>0.000</freeze></mms></response>字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快9请求来源地址无效97接入方式错误98系统繁忙99消息格式错误当result为0时sms标签对出现1次，否则sms标签对不出现。amount：剩余金额，保留3位

40、小数，单位元number：剩余短信数freeze：冻结金额，保留3位小数，单位元当result为0时mms标签对出现1次，否则mms标签对不出现。amount：剩余金额，保留3位小数，单位元number：剩余彩信数freeze：冻结金额，保留3位小数，单位元2.4. http接口（xml方式传输数据）注意：终端客户的接入方式设置为http接入时才能使用此接口。该接口数据输入输出均采用xml格式封装的字符串，编码统一为UTF-8。建议采用post方式提交请求2.4.1. 短信下行访问地址：:8090/http/sms/Submit名称submit功能发送一条或则多条内容相同的短信输入说明mess

41、age参数xml格式如下：<?xml version="1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password><msgid>2c92825934837c4d0134837dcba00150</msgid><phones></phones><content>短信内容

42、</content><subcode>5555</subcode><sendtime>201101011230</sendtime></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：加密后为bb43a2c4081bec02fca7b72f38e63021msgid：该批短信编号，需保证唯一，可空，建议为空phones：接收手机号码，多个手机号码用英文逗号分隔，最多500，不能为空content：短信内容，最多500汉字，不能为空subcode：扩展子号码，可空

43、sendtime：发送时间,格式yyyyMMddHHmm,可空输出说明返回的结果xml格式如下：<?xml version="1.0" encoding="UTF-8"?><response><msgid>2c92825934837c4d0134837dcba00150</msgid><result>0</result> <desc>提交成功</desc></response>字段说明：msgid：该批短信编号result：该批短信提交结果0提交成

44、功1账号无效2密码错误3msgid不唯一4存在无效手机号码5手机号码个数超过最大限制6短信内容超过最大限制7扩展子号码无效（验证格式和长度，不能超过20位）8发送时间格式无效9请求来源地址无效10内容包含敏感词11余额不足97接入方式错误98系统繁忙99消息格式错误2.4.2. 短信上行访问地址：:8090/http/sms/Deliver名称deliver功能获取上行短信。每次调用间隔需大于30秒输入说明message 参数xml格式如下：<?xml version="1.0" encoding="UTF-8"?><message&g

45、t;<account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：<?xml version="1.0" encoding="UTF-8"?><response>&

46、lt;result>0</result> <desc>成功</desc><sms><phone></phone><content>短信内容</content> <subcode>5555</subcode><delivertime>2011-11-11 11:11:11</delivertime></sms></response>字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快9请求来源地址无效97

47、接入方式错误98系统繁忙99消息格式错误如果result为0时sms标签对将出现0到多次，否则sms标签不出现。phone：上行手机号码content：上行短信内容delivertime：上行接收时间，格式yyyy-MM-dd HH:mm:ss2.4.3. 短信状态报告访问地址：:8090/http/sms/Report名称report功能获取下行短信状态报告，每次调用间隔需大于30秒。输入说明message参数xml格式如下：<?xml version="1.0" encoding="UTF-8"?><message><account>admin</account><password>bb43a2c4081bec02fca7b72f38e63021</password><msgid>2c92825934837c4d0134837dcba00150</msgid><phone></phone></message>字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：加密后为bb43a2c4081bec0