三通运营平台CTCOSS接口手册.doc

大汉三通三通运营平台接口手册产品名称三通运营平台版本编号7570文档编号1.0.2发布者上海大汉三通网络通信有限公司发布日期最后修改日期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.短信上行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创建文档。短信部分接口。1.0.0周艳2011/7/7文档格式修改，符合公司内部文档规范要求。1.0.2汤喜金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 Programming 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 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：成功；false：失败。名称onSubmitedSMS功能接收下行短信响应。sendSms方法不直接返回下行响应，由此方法返回，此方法为回调方法，不需要手动调用。接口方法public boolean onSubmitedSMS(ISubmitMsg arg0) 输入说明arg0：下行数据结构，具体支段见示例。输出说明true：成功；false：失败。名称onDeliverSMS功能接收上行短信。此方法为回调方法，不需要手动调用。接口方法public boolean onDeliverSMS(IDeliverMsg arg0) 输入说明arg0：上行数据结构，具体支段见示例。输出说明true：成功；false：失败。名称onMTReportSMS功能接收状态报告。此方法为回调方法，不需要手动调用。接口方法public boolean onMTReportSMS(IReportMsg arg0)输入说明arg0：状态报告数据结构，具体支段见示例。输出说明true：成功；false：失败。示例程序：import com.chinatricom.message.IDeliverMsg;import com.chinatricom.message.IReportMsg;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;/* * 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;static / 相关参数定义SMSUtil _client = new SMSUtil();String host = ; / 调用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, _client, 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;/* * 这个函数接收下发短信的状态报告，它通过msgid关联到下行短信 result : 0成功 1等待发送 2失败 */public 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 表示成功， 其他均为失败。 */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, 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);2.2. WebService接口注意：终端客户的接入方式设置为WebService接入时才能使用此接口访问地址：http:/3:8090/services/SendSms2.2.1. 自定义数据结构MtNewMessage参数名称类型说明smsIdString消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumberString手机号码。支持多号码，号码之间用英文逗号隔开,建议最多100个。如13900000000。contentString短信内容。scheduleTimeDate下行时间，可以为空。WappushurlStringWappush 地址，如果需要发送Wappush，则 Content表示 title2.2.2. 短信下行（发送一条或者多条内容相同的短信）名称sendSms功能发送一条或则多条内容相同的短信。接口方法sendSms(String account, String password, MtNewMessage message) 输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；message对象，详情请参照自定义数据结构：MtNewMessage。输出说明String 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：150000000002c9281e22c1ac7c2012c1adc8bdb0021132-72.2.3. 短信下行（发送内容不同的短信）名称batchSendSms功能发送一条或则多条内容相同的短信。接口方法batchSendSms(String account, String password, MtNewMessage message) 输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；message对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明String 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：发送情况返回 （当errMsg 不为负值时该值有效）格式（无换行符）：150007927992c9281e22c5d9f77012c5da2d0b7001b150007927992c9281e22c5d9f77012c5da2d0c0001c 2.2.4. 获取上行调用短信上行间隔时间不小于30秒。名称getSms功能获取上行短信，一次最多取10条。接口方法getSms(String account, String password)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）。输出说明String 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：返回上行短信（当errMsg 不为负值时该值有效）格式（无换行符）est MO! 测试Deliver消息est MO! 测试Deliver消息!没有上行时返回：2.2.5. 获取状态报告调用短信状态报告间隔时间不小于30秒。名称getReport功能获取一条或者多条状态报告。接口方法getReport(String account, String password,MtNewMessage message)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）；MtNewMessage，详情请参照自定义数据结构：MtNewMessage,包含消息序号和手机号码的对象数组。（只需要填写smsId和phoneNumber字段）。输出说明String 字符串数组String0: 输出参数，小于零时表示下发错误，详情见错误码String1: 返回状态报告（当errMsg 不为负值时该值有效）格式（无换行符）：138877878782c9281e22bf60182012bf6025949001a0138877878792c9dd1e22aa6018dd12bf60ff59490550无状态报告时返回：2.2.6. 获取余额调用获取余额报告间隔时间不小于30秒。名称getBalance功能获取帐号余额。接口方法getBalance(String account, String password)输入说明account用户账号；password用户密码（用MD5加密，32位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确）。输出说明String 字符串数组String0：输出参数，小于零时表示下发错误，详情见错误码String1：返回账户余额（当errMsg 不为负值时该值有效）格式（无换行符）：0432162.2.7. 短信webservice错误码-1：输入参数不正确，请检查账户，密码，等输入参数是否为空-2：账户不存在，请检查用户名密码是否正确-3：账户已经超过每日发送短信限制数量（当账户被限制每日发送量时有用）-4：客户端ip地址不正确（当需要ip校验时）-5：smsId与数据库重复（下发短信时，如果smsId 由客户端传入，该参数不能重复）-6：内容含有非法关键字，请检查下发内容。-7：对应的号码下发失败，下发号码为空或其他错误，导致该号码发送失败-8：账户余额不足2.3. WebService接口（xml方式传输数据）注意：终端客户的接入方式设置为WebService接入时才能使用此接口。该接口数据输入输出均采用xml格式封装的字符串，编码统一为UTF-8。访问地址：http:/3:8090/services/sms2.3.1. 短信下行名称submit功能发送一条或则多条内容相同的短信接口方法String submit (String message)输入说明message参数xml格式如下：adminbb43a2c4081bec02fca7b72f38e630212c92825934837c4d0134837dcba001501311111111113333333333短信内容5555201101011230字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021msgid：该批短信编号(32位UUID)，需保证唯一，可空，建议为空phones：接收手机号码，多个手机号码用英文逗号分隔，最多500，不能为空content：短信内容，最多500个汉字，不能为空subcode：扩展子号码，可空（验证格式和长度，不能超过20位）sendtime：发送时间,格式yyyyMMddHHmm,可空(12位数字，年月日时分，比如201111180929)输出说明返回的结果xml格式如下：2c92825934837c4d0134837dcba001500 提交成功字段说明：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格式如下：adminbb43a2c4081bec02fca7b72f38e63021字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：0 成信内容 55552011-11-11 11:11:11字段说明：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格式如下：adminbb43a2c4081bec02fca7b72f38e630212c92825934837c4d0134837dcba0015013622223333字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021msgid：下行短信编号，可空phone：接收下行手机号码，可空输出说明返回的结果xml格式如下：0 成功2c92825934837c4d0134837dcba00150136222233330 成功字段说明：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. 查询余额名称balance功能获取余额，每次调用间隔需大于60秒。接口方法String balance(String message)输入说明message参数xml格式如下：adminbb43a2c4081bec02fca7b72f38e63021字段说明：account ：用户账号password：账号密码，需采用MD5加密，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：0成功100.0005000.000200.0005000.000字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快9请求来源地址无效97接入方式错误98系统繁忙99消息格式错误当result为0时sms标签对出现1次，否则sms标签对不出现。amount：剩余金额，保留3位小数，单位元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. 短信下行访问地址：http:/3:8090/http/sms/Submit名称submit功能发送一条或则多条内容相同的短信输入说明message参数xml格式如下：adminbb43a2c4081bec02fca7b72f38e630212c92825934837c4d0134837dcba001501311111111113333333333短信内容5555201101011230字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021msgid：该批短信编号，需保证唯一，可空，建议为空phones：接收手机号码，多个手机号码用英文逗号分隔，最多500，不能为空content：短信内容，最多500汉字，不能为空subcode：扩展子号码，可空sendtime：发送时间,格式yyyyMMddHHmm,可空输出说明返回的结果xml格式如下：2c92825934837c4d0134837dcba001500 提交成功字段说明：msgid：该批短信编号result：该批短信提交结果0提交成功1账号无效2密码错误3msgid不唯一4存在无效手机号码5手机号码个数超过最大限制6短信内容超过最大限制7扩展子号码无效（验证格式和长度，不能超过20位）8发送时间格式无效9请求来源地址无效10内容包含敏感词11余额不足97接入方式错误98系统繁忙99消息格式错误2.4.2. 短信上行访问地址：http:/3:8090/http/sms/Deliver名称deliver功能获取上行短信。每次调用间隔需大于30秒输入说明message 参数xml格式如下：adminbb43a2c4081bec02fca7b72f38e63021字段说明：account ：用户账号password：账号密码，需采用MD5加密(小写)，如：456.com加密后为bb43a2c4081bec02fca7b72f38e63021输出说明返回的结果xml格式如下：0 成信内容 55552011-11-11 11:11:11字段说明：result：接口调用结果0成功1账号无效2密码错误3请求太快9请求来源地址无效97接入方式错误98系统繁忙99消息格式错误如果result为0时sms标签对将出现0到多次，否则sms标签