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

06:8890行业短信平台接口手册产品名称 行业短信平台发布日期 2011-05河北电信行业短信平台-接口手册中国电信河北分公司 第 2 页 共 26 页目 录1、 引言 31.1. 目的 31.2. 修改历史记录 31.3. 名称解释 32、 短信 42.1. HTTP 接口 .42.1.1. 短信下行 42.1.2. 短信上行 72.1.3. 短信状态报告 82.1.4. 查询余额 92.2. API 接口 .102.3. WEBSERVICE 接口（不推荐） .142.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（新）错误码 .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.1. 目的该接口手册编写目的在于描述短信平台 CTC-EMP（以下简称 CTC-EMP）具体的接口协议，供接口用户进行接口的对接开发。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/6 WebService 接口(支持上下行子号码)5.3.8 王鹏 2011/8/26 细化 HTTP 下行 SUBCODE 参数描述1.3. 名称解释缩略语 英文全名 中文全名SMS Short Messaging Service 短消息服务MMS Multimedia Message Service 多媒体消息API Application Programming Interface 应用程序编程接口MO Message Original 消息上行MT Message Terminal 消息下行SP Service Provider 服务提供商CP Content Provider 内容提供商河北电信行业短信平台-接口手册中国电信河北分公司 第 4 页 共 26 页2、 短信2.1. http 接口2.1.1. 短信下行功能：下发单条或者多条内容相同的短信。地址： 31:8080/emp/http/SendSms。建议采用 post 方法提交请求。请求参数定义如下： 参数名称 描述 字段值Account 帐号 String，不空。Password 密码 String，不空（需 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”用户可以用此例子验证加密方法是否正确） 。SubCode 子号码 String，可以为空。格式为企业帐号+子号码。例如：如果平台号码为“10650300”，企业帐号为 2，子号码为“22”，则 SubCode 设置为“ 222”，短信将以“10650300222”号码下发给手机用户(注：此功能需要通道支持 )。Phone 手机号码 String，不空，支持多号码，号码之间用英文逗号隔开，最多 100 个。如13900000000。Content 短信内容 String，不空 。 GBK 编码Java 例:.URLEncoder.encode(Content, “UTF-8“)。Wappushurl Wappushurl Wappush 地址，如果需要发送Wappush，则 Content 表示 titleSendTime 定时发送时间 String，可以为空，为空就是立即发送。定时发送格式为年月日时分，如：200803201615。返回参数定义如下：河北电信行业短信平台-接口手册中国电信河北分公司 第 5 页 共 26 页参数名称 描述response 0：成功条数；-1：帐号不存在，请检查用户名或者密码是否正确；-2：账户余额不足；-3：帐号已被禁用；-4：ip 鉴权失败（需要 ip 校验的场合） ；-8：缺少请求参数或参数不正确（请检查用户名，密码，下发号码，下发内容是否为空，或者下发号码数量是否大于100 个） ；-9：内容不合法（含有非法内容，请检查下发内容） 。-10：账户当日发送短信量已经超过允许的每日最大发送量（账户被限制每日发送短信数量的情况有用）phone 手机号。smsID 短信 ID（用于匹配状态报告） 。下发实例（java）：import java.io.BufferedReader;import 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 = .URLEncoder.encode(_content, “UTF-8“);/ 密码加密String pass = MD5Encode(“10“);String _url = “1:8080/ctc-emassh/http/SendSms“;String _param = “Account=10URL url = null;HttpURLConnection urlConn = null;url = 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 BufferedReader(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.print(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 final String byte2hexString(byte bytes) StringBuffer bf = new StringBuffer(bytes.length * 2);for (int i = 0; i - -8 成功返回页面示例：- 2 -2c92811a29a0c90c0129a0ca984e0016 -2c92811a29a0c90c0129a0ca984e0015 2.1.2. 短信上行功能：接收若干条手机用户的上行短信（一次最多十条） 。地址： 31:8080/emp/http/GetSms。建议采用 post 方法提交请求。调用短信上行间隔时间不小于 30 秒。请求参数定义如下：参数名称 描述 字段值Account 帐号 String，不空。Password 密码 String，不空（需 MD5 加密） 。返回参数定义如下：参数名称 描述response 大于 0：上行短信的条数，一次最多取 10 条；0：没有上行短信；-1：帐号登陆失败；河北电信行业短信平台-接口手册中国电信河北分公司 第 8 页 共 26 页-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。-9：访问速度太快，每次访问间隔不能小于 30 秒phone 手机号。content 短信内容；已经用 .URLEncoder.encode()编码；需要用 .URLDecoder.decode()解码。sendTime 上行时间。无短信或者参数错误返回页面示例：- 0 成功返回短信页面示例：（一次最多取 10 条）- 3- 1376612345678test2009-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.02.1.3. 短信状态报告功能：根据 SmsID 返回短信是否成功发送到用户手机。地址： 31:8080/emp/http/GetReport。建议采用 post 方法提交请求。调用短信状态报告间隔时间不小于 30 秒。河北电信行业短信平台-接口手册中国电信河北分公司 第 9 页 共 26 页请求参数定义如下：参数名称 描述 字段值Account 帐号 String，不空。Password 密码 String，不空（需 MD5 加密） 。SmsID 消息 ID String，不空。返回参数定义如下：参数名称 描述response 大于 0：此消息 ID 所对应的状态报告条数。最多 100 条；0：没有此消息 ID 的状态报告；-1：帐号登陆失败；-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。-9：访问速度太快，每次访问间隔不能小于 30 秒phone 手机号。smsID 消息 ID。stat 状态报告0：成功；2：发送失败。请求错误返回页面示例：- -8 请求成功返回页面示例：- 1 -2c92812d1ebf8704011ebf939ba80004 0 河北电信行业短信平台-接口手册中国电信河北分公司 第 10 页 共 26 页2.1.4. 查询余额功能：查询剩余短信的条数。地址： 31:8080/emp/http/GetBalance。建议采用 post 方法提交请求。调用查询余额间隔时间不小于 30 秒。请求参数定义如下：参数名称 描述 字段值Account 帐号 String，不空。Password 密码 String，不空（需 MD5 加密） 。返回参数定义如下：参数名称 描述response -1：帐号登陆失败；-3：此帐号被禁用；-4：ip 鉴权失败；-8：缺少请求参数。sms 短信余额。mms 彩信余额。返回页面示例：- 10002000 2.2. 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, 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：手机号码，支持多号码，以英文逗号隔开。建议一次最多100 个；msg：短信内容。输出说明 true：成功；false：失败。名称 onSubmitedSMS功能 接收下行短信响应。sendSms 方法不直接返回下行响应，由此方法返回，此方法为回调方法，不需要手动调用。接口方法 public boolean onSubmitedSMS(ISubmitMsg arg0) 输入说明 arg0：下行数据结构，具体支段见示例。输出说明 true：成功；false：失败。河北电信行业短信平台-接口手册中国电信河北分公司 第 12 页 共 26 页名称 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;河北电信行业短信平台-接口手册中国电信河北分公司 第 13 页 共 26 页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() + “);河北电信行业短信平台-接口手册中国电信河北分公司 第 14 页 共 26 页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.3. WebService 接口地址：31:8080/emp/services/SmsNewOperator河北电信行业短信平台-接口手册中国电信河北分公司 第 15 页 共 26 页2.3.1. 自定义数据结构MtNewMessage参数名称 类型 说明smsId String 消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumber String 手机号码。支持多号码，号码之间用英文逗号隔开,建议最多 100 个。如13900000000。content String 短信内容。scheduleTime Date 下行时间，可以为空。Wappushurl String Wappush 地址，如果需要发送 Wappush，则 Content 表示 title2.3.2. 短信下行（发送一条或者多条内容相同的短信）名称 sendSms功能 发送一条或则多条内容相同的短信。接口方法 sendSms(String account, String password, MtNewMessage message,StringHolder sendResMsg, StringHolder errMsg) 输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；message 对象，详情请参照自定义数据结构：MtNewMessage。输出说明 sendResMsg：发送情况返回 （当 errMsg 不为负值时该值有效）格式（无换行符）北电信行业短信平台-接口手册中国电信河北分公司 第 16 页 共 26 页2c9281e22c1ac7c2012c1adc8bdb0021132-7errMsg：输出参数，小于零时表示下发错误，详情见错误码2.3.3. 短信下行（发送内容不同的短信）名称 batchSendSms功能 发送一条或则多条内容相同的短信。接口方法 batchSendSms(String account, String password, MtNewMessage message,StringHolder sendResMsg, StringHolder errMsg) 输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；message 对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明 sendResMsg：发送情况返回 （当 errMsg 不为负值时该值有效）格式（无换行符）北电信行业短信平台-接口手册中国电信河北分公司 第 17 页 共 26 页2c9281e22c5d9f77012c5da2d0b7001b150007927992c9281e22c5d9f77012c5da2d0c0001cerrMsg：输出参数，小于零时表示下发错误，详情见错误码2.3.4. 获取上行调用短信上行间隔时间不小于 30 秒。名称 getSms功能 获取上行短信，一次最多取 10 条。接口方法 getSms(String account, String password, StringHolder resMsg,StringHolder errMsg)输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） 。输出说明 resMsg：返回上行短信（当 errMsg 不为负值时该值有效）格式（无换行符）北电信行业短信平台-接口手册中国电信河北分公司 第 18 页 共 26 页Test MO! 测试 Deliver 消息est MO! 测试 Deliver 消息!没有上行时返回：errMsg：输出参数，小于零时表示下发错误，详情见错误码2.3.5. 获取状态报告调用短信状态报告间隔时间不小于 30 秒。名称 getReport功能 获取一条或者多条状态报告。接口方法 getReport(String account, String password,MtNewMessage message, StringHolder reportMsg, StringHolder errMsg)输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；MtNewMessage，详情请参照自定义数据结构：MtNewMessage,包含消息序号和手机号码的对象数组。 （只需要填写 smsId 和 phoneNumber 字段） 。输出说明 reportMsg: 返回状态报告（当 errMsg 不为负值时该值有效）格式（无换行符）：河北电信行业短信平台-接口手册中国电信河北分公司 第 19 页 共 26 页138877878782c9281e22bf60182012bf6025949001a0138877878792c9dd1e22aa6018dd12bf60ff59490550无状态报告时返回：errMsg: 输出参数，小于零时表示下发错误，详情见错误码2.3.6. 获取余额调用获取余额报告间隔时间不小于 30 秒。名称 getBalance功能 获取帐号余额。接口方法 getBalance(String account, String password,StringHolder resMsg, StringHolder errMsg)输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） 。输出说明 resMsg：返回账户余额（当 errMsg 不为负值时该值有效）格式（无换行符）：河北电信行业短信平台-接口手册中国电信河北分公司 第 20 页 共 26 页043216errMsg: 输出参数，小于零时表示下发错误，详情见错误码2.3.7. 短信 webservice（新）错误码-1：输入参数不正确，请检查账户，密码，等输入参数是否为空-2：账户不存在，请检查用户名密码是否正确-3：账户已经超过每日发送短信限制数量（当账户被限制每日发送量时有用）-4：客户端 ip 地址不正确（当需要 ip 校验时）-5：smsId 与数据库重复（下发短信时，如果 smsId 由客户端传入，该参数不能重复）-6：内容含有非法关键字，请检查下发内容。-7：对应的号码下发失败，下发号码为空或其他错误，导致该号码发送失败2.4. WebService 接口 (支持上下行子号码)地址： 31:8080/emp/services/SmsNewOperatoraddsubCode前提：下发通道支持子号码2.4.1. 自定义数据结构MtNewMessage参数名称 类型 说明smsId String 消息序号，用来取状态报告时候匹配，可以为空，建议不填写，为空时服务端会返回一个唯一的消息序号。phoneNumber String 手机号码。支持多号码，号码之间用英文逗号隔开,建议最多 100 个。如13900000000。content String 短信内容。scheduleTime Date 下行时间，可以为空。Wappushurl String Wappush 地址，如果需要发送 Wappush，则 Content 表示 title河北电信行业短信平台-接口手册中国电信河北分公司 第 21 页 共 26 页2.4.2. 短信下行（发送一条或者多条内容相同的短信）名称 sendSms功能 发送一条或则多条内容相同的短信。接口方法 sendSms(String account, String password, MtNewMessage message,String subCode,StringHolder sendResMsg, StringHolder errMsg) 输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；subCode :子号码，需要通道支持，手机终端用户收到的信息发送号码将是长号码 + 子号码( account + 自定义子号码)message 对象，详情请参照自定义数据结构：MtNewMessage。输出说明 sendResMsg：发送情况返回 （当 errMsg 不为负值时该值有效）格式（无换行符）：150000000002c9281e22c1ac7c2012c1adc8bdb0021132-7errMsg：输出参数，小于零时表示下发错误，详情见错误码2.4.3. 短信下行（发送内容不同的短信）名称 batchSendSms河北电信行业短信平台-接口手册中国电信河北分公司 第 22 页 共 26 页功能 发送一条或则多条内容相同的短信。接口方法 batchSendSms(String account, String password, MtNewMessage message, String subCode,StringHolder sendResMsg, StringHolder errMsg) 输入说明 account 用户账号；password 用户密码（用 MD5 加密，32 位，加密后字母全部为小写，例如：“123.com“ 加密后应该等于“cbff36039c3d0212b3e34c23dcde1456”可以用此例子验证加密方法是否正确） ；subCode :子号码，需要通道支持，手机终端用户收到的信息发送号码将是长号码 + 子号码message 对象数组，详情请参照自定义数据结构：MtNewMessage。输出说明 sendResMsg：发送情况返回 （当 errMsg 不为负值时该值有效）格式（无换行符）：150007927992c9281e22c5d9f77012c5da2d0b7001b150007927992c9281e22c5d9f77012c5da2d0c0001c河北电信行业短信平台-接口手册中国电信河北分公司 第 23 页 共 26 页errMsg：输出参数，小于零时表示下发错误，详情见错误码2.4.4. 获取上行调用短信上行间隔时间不小于 30 秒。名称 getSms功能 获取上行短信，一次最多取 10 条。接口方法 getSms(String account, String password, StringHolder resMsg,StringHolder errMsg)输入说明 account 用户账号；password 用户密码（用 MD5 加密，