1、广州市玄武无线科技有限公司玄武集团短信平台WebService2.1 开发手册2013-5-14地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 1目录1. 前言 .31.1. 编写目的 31.2. 内容概述 31.3. 读者对象 31.4. 适用产品 31.5. 相关术语与缩略语解释 32. 接口描述 .52.1. 短信接口 52.1.1. 接口说明 52.1.2. 接口流程 62.2. 彩信接口 72.2.1. 接口说明 72.2.2.
2、接口流程 82.3. 其他接口 92.3.1. 接口说明 92.3.2. 接口流程 92.4. 上下行匹配 92.4.1. 内容匹配 92.4.2. 扩展码匹配 .102.5. 状态报告匹配 .112.5.1. 批次 ID+手机号码进行匹配 112.5.2. 短信 customMsgID 进行匹配 .113. 开发步骤 .114.1. 在玄武 MOS/UMP 服务器新建一个企业应用 .114.2. 访问并获取 WebService 服务地址 .124.3. 客户端代码生成 .124.4. 接口开发及使用举例 134.4.1. Post 操作 .134.4.2. PostSingle 操作 .1
3、84.4.3. PostMass 操作 .184.4.4. PostGroup 操作 .194.4.5. GetResponse 操作 .204.4.6. GetReport 操作 234.4.7. FindResponse 操作 .264.4.8. FindReport 操作 .294.4.9. GetMOMessage 操作 324.4.10. GetAccountInfo 操作 344.4.11. GetBusinessType 操作 364.4.12. ModifyPassword 操作 384.5. 状态码定义 394.5.1. MT 提交状态码 .39地址/Address：广州市天
4、河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 24.5.2. Response 转义状态码 404.5.3. Report 转义状态码 .404. 与我们联系 40地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 31. 前言1.1. 编写目的在本手册里，将向您介绍玄武集团短信产品 WebService2.1 通信接
5、口的使用方法。1.2. 内容概述Web Service 也叫 XML Web Service WebService 是一种可以接收从 Internet 或者Intranet 上的其它系统中传递过来的请求，轻量级的独立的通讯技术。Web Service 完全基于 XML（可扩展标记语言） 、XSD（XML Schema）等独立于平台、独立于软件供应商的标准，是创建可互操作的、分布式应用程序的新平台。Web Service 的主要目标是跨平台的可互操作性。玄武科技集团短信产品 WebService通信接口提供了对各种通信能力的统一封装，供对接玄武科技集团短信产品的业务系统进行调用。通过提供统一 W
6、ebService 方式封装也降低了业务系统的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对业务系统呈现简单的标准接口。1.3. 读者对象本手册适用于对接玄武集团短信产品的业务系统开发人员。本文档的读者需要有一定的 WebService 相关知识。1.4. 适用产品本接口适用于玄武 MOS2.1 和 UMP2.0 产品。1.5. 相关术语与缩略语解释缩写词 英文解析 中文解析 备注MOS Message Operating System 集团短信运营平台由玄武科技自主研发的一整套面向多企业级的运营平台地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真
7、/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 4UMP Universal Message Platform 集团短信通用平台由玄武科技自主研发的一整套面向单企业级的通用平台XML Extensible Markup Language 扩展型可标记语言面向短期的临时数据处理、面向万维网络，是 Soap的基础。SOAP Simple Object Access Protocol 简单对象访问协议 是 XML Web Service 的通信协议。WSDL Web Services Description Language
8、WSDL 文件一个 XML 文档，用于说明一组 SOAP 消息以及如何交换这些消息。SMS Short Messaging Service 短消息业务 普及率最高的一种短消息业务MMS Multimedia Messaging Service 多媒体消息业务 中国移动公司把它定名为“彩信”RES Response 提交响应提交运营商网关的响应报告，用于判断是否成功提交到运营商行业网关RPT Report 状态报告提交手机的响应报告，用于，用于判断是否成功下发到用户手机MT 下行 下发到用户手机MO 上行 用户上行回复业务类型玄武集团短信产品对复杂的业务一种封装类型，包括了下发时间，下发通道，下
9、发的时间范围，下发黑名单等统一封装的对象，用户下发时候用系统默认的业务类型，也可进行特定的配置，详情见平台操作手册批次 单次提交的发送单元单发 单个发送内容，单个手机号码群发 同一个发送内容，不同的手机号码组发 一个发送内容，对应一个手机号码batchid 批次 ID玄武短信产品定义的区分不同批次的唯一标识，主要用户匹配状态报告地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 52. 接口描述短信接口接口说明业务系统通过此接口收发短消息。业务
10、系统通过标准的 WebService 方式，提交收发请求，玄武短信平台收发请求之后，进行标准解析和逻辑处理，并将最终处理结果返回给业务系统。地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 62.1.2. 接口流程推 送 提 交 响 应G e t R e p o r tG e t R e p o r t R e s u l tP o s t / P o s t S i n g l e / P o s t M a s s / P o s t G
11、 r o u p 玄 武 M O S / U M P业 务 系 统P o s t R e s u l t / P o s t S i n g l e R e s u l t / P o s t M a s s R e s ul t / P o s t G r o u p R e s u l t F i n d R e s p o n s eF i n d R e s p o n s e R e s u l t短 信 下 发查 询 提 交 响 应推 送 提 交 响 应G e t R e s p o n s e G e t R e s p o n s e R e s u l t 查 询 状 态 报
12、 告F i n d R e p o r tF i n d R e p o r t R e s u l t业务系统通过调用短信下发接口，下发短消息，玄武 MOS/UMP 返回接收响应；业务系统可以通过查询和推送接口，查询响应的运营商提交相应和手机状态报告。地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 7G e t M O M e s s a g e 玄 武 M O S / U M P业 务 系 统G e t M O M e s s a g
13、e R e s u l t短 信 上 行业务系统通过调用短信上行接口，获取用户上行的数据。2.2.彩信接口2.2.1. 接口说明彩信的下发，获取提交响应和状态报告跟短信类同，通过下发对象赋值不同来区分。另外，彩信没有上行接口。地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 82.2.2. 接口流程推 送 提 交 响 应G e t R e p o r tG e t R e p o r t R e s u l tP o s t / P o s
14、t S i n g l e / P o s t M a s s / P o s t G r o u p 玄 武 M O S / U M P业 务 系 统P o s t R e s u l t / P o s t S i n g l e R e s u l t / P o s t M a s s R e s ul t / P o s t G r o u p R e s u l t F i n d R e s p o n s eF i n d R e s p o n s e R e s u l t短 信 下 发查 询 提 交 响 应推 送 提 交 响 应G e t R e s p o n s e
15、G e t R e s p o n s e R e s u l t 查 询 状 态 报 告F i n d R e p o r tF i n d R e p o r t R e s u l t业务系统通过调用彩信下发接口，下发彩信，玄武 MOS/UMP 返回接收响应；业务系统可以通过查询和推送接口，查询响应的运营商提交相应和手机状态报告。对应关系：MT 与 Response，通过 batchid 与 phone 字段进行对应，同一个下发批次，如果出现重复手机号码，则无法进行绝对匹配；Response 与 Report，通过 msgid 字段进行对应。地址/Address：广州市天河区体育西路 1
16、03号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 92.3.其他接口2.3.1. 接口说明玄武 MOS/UMP 提供了一些业务数据获取接口，获取一些基本的业务数据。2.3.2. 接口流程G e t A c c o u n t I n f o 玄 武 M O S / U M P业 务 系 统G e t A c c o u n t I n f o R e s u l tG e t B u s i n e s s T y p e G e t B u s i n e s s T y p e R
17、e s u l t获 取 帐 号 信 息获 取 业 务 类 型修 改 帐 号 密 码M o d i f y P a s s w o r d M o d i f y P a s s w o r d R e s u l t业务系统通过也可调用获取帐号信息，获取业务类型，修改密码接口，得到相应的信息。2.4.上下行匹配2.4.1. 内容匹配根据规定的上行内容，匹配对应的下行。例如：下发了一批下行，规定回复 XXX 开头，则匹配到该下行。地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61
18、302222 网站/Website： 102.4.2. 扩展码匹配通过对下发的端口号进行扩展，下发短信，手机回复的上行，会带上配置的扩展码，上行和下行再通过该扩展码进行匹配。例如：原始的通道号：10690550，下行设置的扩展码：001，那么，手机回复的上行，除了收到上行内容之后，还可以收到目标地址：10690550001，通过收到的目标地址，则可找到对应的下行。设置方法：方法一：一个批次，一个扩展码MTPack pack = new MTPack();pack.setBatchID(UUID.randomUUID();pack.setBatchName(“短信测试批次“);pack.setM
19、sgType(MTPack.MsgType.SMS);pack.setBizType(0);pack.setDistinctFlag(false);ArrayList msgs = new ArrayList();/* 群发，多号码一内容 */pack.setSendType(MTPack.SendType.MASS);msgs.add(new MessageData(“13430258222“, “内容1“);msgs.add(new MessageData(“13430258333“, “内容2“);pack.setMsgs(msgs);/设置扩展码pack.setCustomNum(“0
20、01“);GsmsResponse resp = pm.post(ac, pack);方法二：每条短信，一个扩展码MTPack pack = new MTPack();pack.setBatchID(UUID.randomUUID();pack.setBatchName(“短信测试批次“);pack.setMsgType(MTPack.MsgType.SMS);pack.setBizType(0);pack.setDistinctFlag(false);ArrayList msgs = new ArrayList();/* 群发，多号码一内容 */pack.setSendType(MTPack
21、.SendType.MASS);String content = “短信“ ;MessageData md1 = new MessageData(“13433938646“, content);md1.setCustomNum(“003“);地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 11MessageData md2 = new MessageData(“13433938646“, content);md2.setCustomNum(
22、“004“);msgs.add(md1);msgs.add(md2);pack.setMsgs(msgs);GsmsResponse resp = pm.post(ac, pack);2.5.状态报告匹配2.5.1. 批次 ID+手机号码进行匹配MT 与 Response，通过 batchid 与 phone 字段进行对应，Response 与 Report，通过msgid 字段进行对应。优点：下发简单，无需每条信息都设置 msgid 字段，节约传输空间，提高传输效率。缺点：状态报告匹配相对复杂，需要通过 batchid 和 phone 才能匹配，且如果同一批次有重复手机号码，则无法进行绝对匹
23、配。2.5.2. 短信 customMsgID 进行匹配每条短信设置 customMsgID， Response 与 Report 都会返回 customMsgID，通过customMsgID 进行对应。优点：状态报告匹配简单，每条短信，状态报告都有唯一对应的 customMsgID。缺点：每条短信都需要设置唯一的 customMsgID，传输效率相对较低。3. 开发步骤在玄武 MOS/UMP 服务器新建一个企业应用玄武科技销售经理协调处理，并最终提供一个可用的发送帐号。4.2.访问并获取 WebService 服务地址在 IE 浏览器中输入如 http:/IP :PORT/Service/W
24、ebService.asmx 地址，其中IP为MOS/UMP 服务器的 IP 地址， PORT为服务的端口，80 可省略, 地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 12/Service/WebService.asmx为服务地址名，若访问服务地址成功，在 IE 中将显示如图所示信息。UMP： IP 为部署服务器 Receiver 模块的 IP。MOS： IP 为 211.147.239.62/MOS 网关 wsdl 地址：http:/
25、211.147.239.62/Service/WebService.asmx?wsdl /400 网关 wsdl 地址：http:/211.147.239.62:8500/Service/WebService.asmx?wsdl 正确显示服务信息后，记住此服务地址：http:/IP :PORT/Service/WebService.asmx ，此地址即为WebService 服务地址 。4.3.客户端代码生成根据服务地址生产客户端代码，不同的开发语言，开发工具的生成方法不同，下面以java eclipse 为例。首先，获取 WSDL 地址，后添加?wsdl ，然后在 IE 中输入此地址，如 h
26、ttp:/IP :PORT/Service/WebService.asmx?wsdl，访问可显示 WSDL 信息。接着，在 ecplise 导入 wsdl 地址，生成相应的客户端代码。地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 13将生成的客户端及服务端代码部署到开发工程中，然后进行后续的开发步骤。4.4.接口开发及使用举例4.4.1. Post 操作4.4.1.1. 操作说明Post 调用是业务系统发起，请求发送短消息到指定手机。该操
27、作为统一的发送接口，支持单发，组发，群发操作，推荐使用。4.4.1.2. 开发代码举例原型：GsmsResponse Post(string account, string password, MTPack mtpack);输入参数：序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 account String 是 用 户 名2 password String 是 密 码 ， MD5 加 密 ，设 置 时 自 动 加 密3 mtpack MTPacks 是下 行 批 次 包 ， 最 大下 发 手 机 号 码 数 为100 万 。Mtpack：序 字 段 名 称 数 据 类 型 是
28、否 必 须 说 明1. batchID UUID 否 信 息 批 次 唯 一 序 号 2. batchName String 否 批 次 名 称地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 143. sendType int32 是发 送 类 型 ：群 发 (0 默 认 )组 发 (1)单 发 是 以 上 两 者 的特 例4. msgType int32 是消 息 类 型 ：短 信 (1 默 认 )彩 信 (2),WAPPUSH(3);5
29、. medias MediaItem 否 公 共 彩 信 资 源 列 表6. msgs MessageData 是 数 条 短 信7. bizType int32 否信息业务类型,对应于 BusinessType(业务类型)的 ID8. distinctFlag bool 是 是 否 过 滤 重 复 号 码（ 默 认 ： false）9. scheduleTime int64 否 计 划 发 送 时 间10. remark String 否 备 注11. customNum String 否 用 户 扩 展 码12. deadline long 否 下 发 截 至 时 间输出参数：序 字 段
30、名 称 数 据 类 型 是 否 必 须 说 明1 GsmsResponse GsmsResponse 是玄 武 MOS/UMP 响 应报 告 ， 详 细 返 回 代码 见 ： MT 提 交 状 态码输出 xml：0代码片段：/ / 短信发送/ public void PostMSG()var wb = new WebServiceSoapClient();MessageData messagedatas = new MessageData3; /号码数量#region 群发/地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 6130222
31、2-8855 电话/Tel：+86 20 61302222 网站/Website： 15/for (int i = 0; i /for (int i = 0; i / 彩信发送/ public void PostMMS()var wb = new WebServiceSoapClient();MessageData messagedatas = new MessageData2; /手机号码数量MTPacks mtpack = new MTPacks();mtpack.batchID = Guid.NewGuid();mtpack.batchName = “ttttttttttt“;/ +Da
32、teTime.Now.Millisecond; / 分批名称mtpack.msgType = 2; / 消息类型，短信 1、彩信 2mtpack.bizType = 1; / 业务类型 IDmtpack.customNum = “1380“; / 扩展号mtpack.scheduleTime = 0; / 时间使用 int64 类型，是指从 1970-1-1 00:00:00开始到当前的毫秒数mtpack.sendType = 0; / 发送类型，群发 0、组发 1mtpack.distinctFlag = true; / 是否过滤重复号码mtpack.deadline = 0; / 时间使用
33、 int64 类型，是指从 1970-1-1 00:00:00 开始到当前的毫秒数地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 17mtpack.remark = “; / 备注mtpack.medias = SetMedias(“D:玄武项目WebserviceWebServiceClientResourcespublic“); /设置公共彩信资源#region 群发for (int i = 0; i 0代码片段地址/Address：广
34、州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 194.4.3. PostMass 操作4.4.3.1. 操作说明PostMass 调用是业务系统发起，请求群发短消息到一个指定地址（或地址集合） 。建议使用 Post 操作。4.4.3.2. 开发代码举例原型：int PostMass(string account, string password, string mobiles, string content, string subid);输入参数：序 字 段 名
35、 称 数 据 类 型 是 否 必 须 说 明1 account String 是 用 户 名2 password String 是 密 码 ， MD5 加 密 ，设 置 时 自 动 加 密3 mobiles String 是短 信 发 送 的 目 的 手机 号 码 数 组 ， 最 大下 发 手 机 号 码 数 为100 万 。4 content String 是 短 信 发 送 的 内 容5 subid String 否 扩 展 ID输出参数：序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 int Int 是 返 回 值 ： 见 MT 提交 状 态 码输出 xml：0代码片段地址
36、/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 204.4.4. PostGroup 操作4.4.4.1. 操作说明PostGroup 调用是业务系统发起，请求组发短消息到一个指定地址（或地址集合） 。建议使用 Post 操作。4.4.4.2. 开发代码举例原型：int PostGroup(string account, string password, MessageData mssages, string subid);输入参数：序 字 段
37、 名 称 数 据 类 型 是 否 必 须 说 明1 account String 是 用 户 名2 password String 是 密 码 ， MD5 加 密 ，设 置 时 自 动 加 密3 mssages MessageData 是短 信 发 送 的 多 个 目的 的 数 组 ， 最 大 下发 手 机 号 码 数 为100 万 。4 subid String 否 扩 展 IDMessageData序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 phone String 是 手 机 号 码2 content String 是 短 信 内 容3 medias MediaItem
38、 否 私 有 彩 信 资 源 列 表4 customMsgID String 否 用 户 自 定 义 消 息ID5 customNum String 否 用 户 扩 展 码5 vipFlag bool 是 是 否 VIP 号 码(默 认 ： false)输出参数：序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 int Int 是 返 回 值 ： 见 MT 提交 状 态 码输出 xml：地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Websit
39、e： 210代码片段4.4.5. GetResponse 操作4.4.5.1. 操作说明GetResponse 调用是业务系统发起，请求推送运营商提交相应。已经推送过的提交相应，下次无法继续推送。4.4.5.2. 开发代码举例原型：MTResponse GetResponse(string account, string password, int pagesize);输入参数：序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 account String 是 用 户 名2 password String 是 密 码 ， MD5 加 密 ，设 置 时 自 动 加 密3 pagesi
40、ze Int 是获 取 数 量 ， 当 超 过500 时 ， 系 统 默 认为 500输出参数：序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 MTResponse MTResponse 是 获 取 的 提 交 相 应 实体 对 象MTResponse序 字 段 名 称 数 据 类 型 是 否 必 须 说 明1 batchID UUID 是 批 次 号2 msgID String 是 消 息 ID3 customMsgID String 否 用 户 自 定 义 消 息ID4 state int32 是玄 武 网 关 根 据originResult 转义 的 状 态 ， 见Resp
41、onse 转 义 状地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 22态 码5 phone String 是 手 机 号 码6 total int32 否 分 段 总 数 （ 用 于 长短 信 ）7 number int32 否 当 前 段 数 （ 用 于 长短 信 ）8 submitRespTime int64 是 提 交 运 营 商 响 应 时间9 originResult String 否 运 营 商 返 回 原 始 提交 响 应
42、结 果10 reserve String 否 保 留 字 段输出 xml：162b77b4-bbaa-4045-92df-a3bb58e861c357156525320211343393864612013-05-07T01:56:520108130ecc65a-3d1b-0548-8baf-73b381c2310b5726522411343393864612013-05-07T02:06:0801391地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Webs
43、ite： 23代码片段/ / 获取提交报告/ / 获取条数public void GetResponse(int count)if (count 13852162b77b4-bbaa-4045-92df-a3bb58e861c31343393864657156525320202013-05-07T01:56:002013-05-07T01:57:00DELIVRD1403630ecc65a-3d1b-0548-8baf-73b381c2310b134339386465726522402013-05-07T02:06:002013-05-07T02:06:00DELIVRD代码片段地址/Addr
44、ess：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 26/ / 获取状态报告/ / 获取条数public void GetReport(int count)var webService = new WebServiceSoapClient();MTReport info = webService.GetReport(account, password, count);if (info != null)for (int i = 0; i 162b77b4-bb
45、aa-4045-92df-a3bb58e861c3571565253202113433938646112013-05-07T01:56:52077024030ecc65a-3d1b-0548-8baf-73b381c2310b57265224113433938646112013-05-07T02:06:080770259代码片段/ / 查询提交报告/ / 批次 ID地址/Address：广州市天河区体育西路 103号维多利广场 B塔 19层 传真/Fax：+86 20 61302222-8855 电话/Tel：+86 20 61302222 网站/Website： 29/ 手机号码/ 页数/ 查询方式；0：模糊查询、1：精确查询public void FindResponse(string bitch, string phone, int page, int flag)var webService = ne
