WebService 接口通信文档
1.1. WebService方式通信适配插件接口
WebService方式通信适配插件提供了对各种通信能力的统一封装，供集团客户应用系统和MAS服务器应用插件进行调用。同时，提供统一WebService方式封装也降低了SI的开发难度，将繁杂的通信能力协议与具体的业务应用分离开来，对SI呈现简单的标准接口。WebService方式通信适配插件接口封装了以下移动通信能力：
ü 短信
ü 彩信
ü wap
ü ussd
ü LBS
此外，还提供基座与应用插件之间的插件管理功能接口。
MAS服务器应提供配置工具，指定对于某个集团客户应用系统或应用插件，通过WebService方式通信适配插件或数据库方式通信适配插件接入MAS服务器。
1.1.1.Web服务公共数据定义
5.2.1.1 命名空间
公共数据类型的命名空间参见：
http://www.csapi.org/schema/common/v2_0
公共异常的命名空间参见：
http://www.csapi.org/wsdl/common_faults/v2_0
5.2.1.2 WEB服务调用方式
WEB服务应支持HTTP上的SOAP调用，使集团客户应用系统以及各插件可通过HTTP方式与服务器进行通信。
5.2.1.3 XML数据类型
XML数据类型参见XML Schema（W3C Recommendation (2 May 2001): "XML Schema Part2: Datatypes"）。
5.2.1.4 XML Schema数据类型定义
5.2.1.4.1. TimeMetricsValues
数据类型为枚举型。
| 值 |
描述 |
| Millisecond |
毫秒 |
| Second |
秒 |
| Minute |
分 |
| Hour |
小时 |
| Day |
日 |
| Week |
星期 |
| Month |
月 |
| Year |
年 |
5.2.1.4.2. TimeMetric
数据类型为结构。
| 名称 |
类型 |
描述 |
| Metric |
TimeMetricValues |
计量单位 |
| Units |
xsd:int |
数值 |
5.2.1.4.3. ServiceError
数据类型为结构。
| 名称 |
类型 |
描述 |
| MessageId |
xsd:string |
消息标识 |
| Text |
xsd:string |
消息说明 |
| Variables |
xsd:string [0..unbounded] |
变量 |
5.2.1.4.4. SimpleReference
数据类型为结构。
| 名称 |
类型 |
描述 |
| Endpoint |
xsd:anyURI |
端口 |
| InterfaceName |
xsd:string |
接口名称 |
| Correlator |
xsd:string |
关联标识 |
5.2.1.4.5. CMAbility
数据类型为枚举。
| 值 |
描述 |
| SMSbility |
对短信能力的需求 |
| MMSAbility |
对彩信能力的需求 |
| WAPAbility |
对WAP能力的需求 |
| USSDAbility |
对USSD能力的需求 |
| LBSAbility |
对LBS能力的需求 |
| GPRSAbility |
对GPRS能力的需求 |
5.2.1.4.6. MessageNotificationType
用于集团客户应用系统和应用插件通知通信能力需求及所提供的web服务端地址。
数据类型为结构：
| 名称 |
类型 |
描述 |
| CMAbility |
CMAbility |
对应某一个通信能力 |
| WSURI |
xsd:anyURI |
对应该通信能力，应用系统或插件提供的WEB服务端地址 |
5.2.1.5 公共异常定义
5.2.1.5.1. 业务异常
业务异常消息使用保留的消息标识符‘SVC’，并使用从0001到0999的号码来定义。其中0001至0199被保留作公共差错定义，0200至0999作为其它Web Service指定用途。从‘1000’至‘9999’为自定义。
| 名称 |
类型 |
描述 |
| MessageId |
xsd:string |
消息标识符，前缀为SVC |
| Text |
xsd:string |
消息文本，可变可替代部分用%来标识 |
| Variables |
xsd:string [0..unbounded] |
替代文本字串中的可变部分 |
SVC0001: 业务错误
| 名称 |
描述 |
| Message Id |
SVC0001 |
| Text |
发生了一个业务错误。错误代码是%1 |
| Variables |
%1－来自业务的错误码。 |
SVC0002: 不合法的输入值
| 名称 |
描述 |
| Message Id |
SVC0002 |
| Text |
消息部分%1有不合法的输入值。 |
| Variables |
%1－消息部分。 |
SVC0003:不合法的输入值包含部分合法值
| 名称 |
描述 |
| Message Id |
SVC0003 |
| Text |
消息部分%1有不合法的输入值，%2是合法值。 |
| Variables |
%1－消息部分； %2－合法值列表。 |
SVC0004: 不合法地址
| 名称 |
描述 |
| Message Id |
SVC0004 |
| Text |
消息部分%1未提供合法地址。 |
| Variables |
%1－消息部分。 |
SVC0005:重复关联符
| 名称 |
描述 |
| Message Id |
SVC0005 |
| Text |
消息部分%2中描述的关联符%1是重复的。 |
| Variables |
%1－关联符。 %2－消息部分。 |
SVC0006: 不合法的组
| 名称 |
描述 |
| Message Id |
SVC0006 |
| Text |
消息部分%2中的组%1不是一个合法的组。 |
| Variables |
%1－不合法的组的标识符。 %2－消息部分。 |
SVC0902:因内容过滤，被拒绝
| 名称 |
描述 |
| Message Id |
SVC0902 |
| Text |
因内容过滤，被拒绝 |
| Variables |
无。 |
5.2.1.5.2. 策略异常
策略异常消息使用保留的消息标识符‘POL’，并使用从0001到0999的号码来定义。其中0001至0199被保留作公共差错定义，0200至0999作为其它Web Service 指定用途。从‘1000’至‘9999’为自定义。
| 名称 |
类型 |
描述 |
| MessageId |
xsd:string |
消息标识符，前缀为POL |
| Text |
xsd:string |
消息文本，可变可替代部分用%来标识。 |
| Variables |
xsd:string [1..unbounded] |
替代文本字串中的可变部分。 |
POL0001:策略错误
| 名称 |
描述 |
| Message Id |
POL0001 |
| Text |
发生了一个策略错误。错误代码是%1。 |
| Variables |
%1—来自业务的错误码。 |
POL0003:过多的地址
| 名称 |
描述 |
| Message Id |
POL0003 |
| Text |
在消息部分%1中描述了过多的地址。 |
| Variables |
%1－消息部分。 |
POL0004:不支持无限制的通知请求
| 名称 |
描述 |
| Message Id |
POL0004 |
| Text |
不支持无限制的通知请求。 |
| Variables |
无。 |
POL0005:请求了过多的通知
| 名称 |
描述 |
| Message Id |
POL0005 |
| Text |
请求了过多的通知。 |
| Variables |
无。 |
POL0006:组地址不被允许
| 名称 |
描述 |
| Message Id |
POL0006 |
| Text |
在消息部分%1中描述的组不被允许。 |
| Variables |
%1－消息部分。 |
POL0007:嵌套的组不被允许
| 名称 |
描述 |
| Message Id |
POL0007 |
| Text |
在消息部分%1中描述的嵌套的组不被允许。 |
| Variables |
%1－消息部分。 |
POL0009:请求的频率不合法
| 名称 |
描述 |
| Message Id |
POL0009 |
| Text |
请求的频率不合法。 |
| Variables |
无。 |
POL0900: 不支持群发
| 名称 |
描述 |
| Message Id |
POL0900 |
| Text |
不支持群发请求。 |
| Variables |
无。 |
POL0903: 超过状态保留时长
| 名称 |
描述 |
| Message Id |
POL0903 |
| Text |
超过状态保留时长。 |
| Variables |
无。 |
POL0904: 超过流量门限
| 名称 |
描述 |
| Message Id |
POL0904 |
| Text |
超过流量门限。 |
| Variables |
无。 |
POL0905: 不被支持操作或者请求
| 名称 |
描述 |
| Message Id |
POL0905 |
| Text |
系统不支持此API调用。 |
| Variables |
无。 |
POL0906: 不被允许操作或者请求
| 名称 |
描述 |
| Message Id |
POL0906 |
| Text |
不被允许操作或者请求。 |
| Variables |
无。 |
POL0907: 不允许群发请求
| 名称 |
描述 |
| Message Id |
POL0907 |
| Text |
不允许群发请求。 |
| Variables |
无。 |
POL0908: 短信消息超长
| 名称 |
描述 |
| Message Id |
POL0908 |
| Text |
短信消息超长。 |
| Variables |
无。 |
POL0910: 超过消息上限
| 名称 |
描述 |
| Message Id |
POL0910 |
| Text |
超过消息上限。 |
| Variables |
无。 |
5.2.1.6 AnyUri格式说明
关于anyURI中各类型的格式定义如下：
| 类型 |
格式 |
描述 |
| 电话号码 |
tel:电话号码 |
表示接收者是一个电话号码 |
| 群组 |
tel:组名称;type=grp |
表示接收者是一个群组，用于群发，需要与基座中的地址本管理模块配合使用。 |
| 部门 |
tel:部门名称;type=dpt |
表示接收者是一个部门，用于群发，需要与基座中的地址本管理模块配合使用。 |
| Web服务地址 |
http:URL |
URL |
号码、群组、部门可以组合使用，中间用一个“,”号分开。
其它遵循以下标准
RFC 2396 Uniform Resource Identifiers (URI): GenericSyntax
RFC 3966 The tel URI for Telephone Numbers
http://www.w3.org/2001/XMLSchema.dtd
1.1.2.插件管理接口
5.2.2.1 接口说明
插件管理接口实现对应用插件的注册、注销、暂停和恢复，各插件通过此接口报告插件状态。插件管理具体内容包括：
ü 插件的注册、注销、启用、暂停
ü 插件状态报告
ü 业务鉴权
ü 业务性能通知
WebService方式通信适配插件作为基座插件管理模块的代理，实现插件管理相关操作信息的处理和转发。
5.2.2.2 流程说明
插件管理流程如下：
图5-1 插件管理流程示意图
MAS服务器系统中的应用插件必须注册通过后方可使用，WebService方式通信适配插件将该注册请求转发到插件管理模块并获得结果，将结果封装在响应消息中返回给应用插件，注册及响应过程通过APRegistration操作实现。
应用插件注册通过后，要周期性地进行状态汇报并获取响应，状态报告及响应过程通过APStatusRep操作完成。
插件分为提供Web服务端和不提供Web服务端两种。对于提供Web服务端的情况，需在插件注册操作中指明服务端的URL，插件管理模块对该插件的所有后续管理操作均通过调用该服务端的操作实现；对于不提供Web服务端的插件，插件管理模块对该插件的所有后续管理操作均通过APStatusRep的响应消息带回。
在应用插件运行过程中，根据从MAS统一服务平台得到的业务能力信息，插件管理模块可以主动地发出命令，暂停或恢复特定的插件，这些指令经WebService方式通信适配插件通知给应用插件，通过APStatusRep、PauseAP和RecoveryAP操作实现。
对于提供服务端和不提供服务端的插件，暂停和恢复流程分别如下图所示：
图5-1 插件暂停及恢复流程
MAS服务器在运行过程中，将根据业务管理的需求，与MAS统一服务平台之间进行业务鉴权和业务性能数据上报，而鉴权数据和业务性能数据需要由应用插件提供。因此，MAS服务器需要从应用插件获取原始的鉴权数据和业务性能数据，通过APStatusRep、APSvcCfgRep、APSvcAuthentic、APSvcPerfCmd和APSvcPerfReport操作实现。
对于提供服务端和不提供服务端的插件，业务鉴权和业务性能数据上报流程分别如下图所示：
图5-3 业务鉴权和业务性能数据上报流程
在应用插件结束之前，应用插件主动发起注销操作APLogOut。
考虑到一个应用插件可能包含多个进程，因此在上述流程中，注册、状态上报、注销、业务鉴权和业务性能数据上报为进程级，而暂停和恢复为插件级。
当插件管理模块发现插件进程异常或资源占用超过阀值时，并不停止该进程，而是提示告警给指定人员。
应用插件的状态图如下图所示：
图5-2 应用插件状态示意图
5.2.2.3 数据类型
注册结果：APRegResult
数据结构：枚举
| 名称 |
描述 |
| success |
注册成功 |
| illegalAP |
插件不被允许，注册失败 |
| CMAbilityNotSup |
不支持所要求的通信能力，注册失败 |
| repeatedReg |
重复注册，注册成功 |
| svcAddrMismatch |
注册请求中的插件Web服务端地址与之前的同一插件其它进程注册请求中的插件Web服务端地址不一致，注册失败。 |
AP运行状态：APStatusType
数据结构：枚举
| 名称 |
描述 |
| Normal |
状态正常 |
| OutofActiveTime |
超过有效期 |
| NeedRegistration |
未注册，需要先注册 |
| OutofService |
已经注销 |
| Paused |
已暂停 |
| Closed |
插件进程已被mas服务器强行关闭 |
| WaitingforConfirm |
插件的注册请求等待审批中 |
注销结果：APLogoutResult
数据结构：枚举
| 名称 |
描述 |
| success |
注销成功 |
| illegalAPid |
插件id不合法，注销失败 |
| repeatedLogout |
重复注销请求 |
5.2.2.4 接口定义
5.2.2.4.1. 插件注册
由应用插件AP发起进行注册：
操作：APRegistration
业务触发条件：AP插件启动后，需要自动向WebService适配插件进行注册。注册成功后才能进行其他的正常的调用，否则，WebService适配插件会拒绝该插件后续的所有操作。
输入：APRegistrationReq
| 参数 |
类型 |
可选性 |
描述 |
| Apid |
xsd: string |
M |
AP插件的标识 |
| APPid |
xsd:int |
M |
AP插件的PID |
| HostIP |
xsd: string |
M |
主机所在的ip地址 |
| MessageNotification |
MessageNotificationType[] |
M |
AP插件所需的通信能力及各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端。 |
| APWSURI |
xsd: anyURI |
O |
应用插件对应的WEB服务端URL，若无，则表示该应用插件不提供服务端。 |
输出：APRegistrationRsp
| 参数 |
类型 |
可选性 |
描述 |
| RegResult |
APRegResult |
M |
注册响应结果 |
| NextInterval |
xsd:int |
M |
表示AP的后续状态上报时间间隔（单位为秒） |
差错：
业务异常：
ü SVC0001 - 业务错误.
策略异常：
ü POL0001 - 策略错误.
5.2.2.4.2. 插件状态信息上报
由应用插件AP发起，报告插件的状态。
操作：APStatusRep
业务触发条件：在插件运行过程中，需要周期性地上报自己的运行状态。上报周期可以由MAS服务器进行控制。在状态上报响应消息中，MAS服务器将后续状态上报时间间隔反馈给AP，收到响应之后AP按照这个间隔上报插件状态。对于不提供服务端的应用插件，MAS服务器插件管理模块将需要应用插件执行的管理命令包含在状态上报响应消息中，包括暂停、恢复、业务鉴权通知、业务性能上报通知。
输入：APStatusRepReq
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
| APStatus |
APStatusType |
M |
插件运行状态 |
| APPid |
xsd:int |
M |
AP插件的PID |
输出：APStatusRepRsp
| 参数 |
类型 |
可选性 |
描述 |
| NextCommand |
xsd:string |
O |
仅对于不提供服务端的应用插件有效，表示需要插件执行的管理命令，pause代表暂停，recovery代表恢复，不填表示无命令。 |
| NextInterval |
xsd:int |
O |
插件的后续上报时间间隔（单位为秒），不填表示同上次时间间隔 |
| ApSvcAuthType |
xsd:string [0..unbounded] |
O |
仅对于不提供服务端的应用插件有效，表示要求插件立即进行业务鉴权。 |
| ApSvcPerfCmdType |
xsd:string [0..unbounded] |
O |
仅对于不提供服务端的应用插件有效，表示要求插件进行业务性能数据上报。 |
差错：
业务异常：
ü SVC0002 - 不合法的输入值.
策略异常：
ü POL0001 - 策略错误.
ApSvcAuthType定义：
ApSvcAuthType中包含插件管理模块的业务鉴权要求，格式为“订购编码:订购关系信息类型”。应用插件在收到APStatusRepRsp后，需判断其中的ApSvcAuthType字段信息，若有业务鉴权要求时，应用插件应立即按要求通过APSvcCfgRep发起业务鉴权。
例如，若要求移动办公插件（开通短信和彩信通信能力，无服务端）进行鉴权，上报订购关系变量，则在ApSvcAuthType填写812100010002:2。
ApSvcPerfCmdType定义：
ApSvcPerfCmdType包含插件管理模块的业务性能数据上报请求，格式为：“性能数据编码:业务性能上报统计的起始和结束时间”。其中，统计起始和结束时间字段的格式为“yyyymmddHHmmss, yyyymmddHHmmss”。应用插件在收到APStatusRepRsp后，需判断其中的ApSvcPerfCmdType字段信息，若有业务性能数据上报要求时，应用插件按照指令中的起始和结束时间统计性能数据，并在到达ApSvcPerfCmdType中所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据。
5.2.2.4.3. 插件发起业务鉴权
由应用插件AP根据APStatusRep中的指令发起，报告插件的订购关系信息信息。
操作：APSvcCfgRep
业务触发条件：对于无服务端的应用插件，当收到的状态报告响应APStatusRepRsp中的ApSvcAuthType字段要求插件进行业务鉴权时，需立即按要求发起业务鉴权。插件业务鉴权的目的是为MAS服务器提供业务鉴权的原始数据，供MAS服务器与统一服务平台鉴权使用。
输入：APSvcCfgRepReq
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
| SvcCfgInfo |
xsd:string [0..unbounded] |
M |
业务订购关系信息，格式及定义参见“订购关系信息”一节 |
输出：APSvcCfgRepRsp
| 参数 |
类型 |
可选性 |
描述 |
| ACK |
xsd:boolean |
M |
true表示成功，false表示失败。 |
差错
业务异常：
· SVC0001 - 业务错误.
策略异常：
· POL0001 - 策略错误.
5.2.2.4.4. 插件管理模块发起业务鉴权
对于具备web服务端的应用插件，插件管理模块通过此接口获取应用插件的业务订购关系信息。
操作：APSvcAuthentic
业务触发条件：对于具备web服务端的应用插件，MAS服务器根据自身的业务鉴权请求需要，通过此接口向应用插件发起请求，请求获取插件的订购关系信息，插件需根据请求中的具体要求返回对应的订购关系信息。
输入：APSvcAuthenticReq
| 参数 |
类型 |
可选性 |
描述 |
| Apid |
xsd: string |
M |
AP插件的标识 |
| ApSvcAuthType |
xsd: string [0..unbounded] |
M |
要求返回的鉴权数据类型 |
输出：APSvcAuthenticRsp
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
| ApSvcAuthResult |
xsd:string [0..unbounded] |
M |
业务订购关系信息，格式及定义参见“订购关系信息”一节 |
ApSvcAuthType定义：
ApSvcAuthType中包含插件管理模块的业务鉴权要求，格式为“订购编码:订购关系信息类型”。应用插件在收到APSvcAuthenticReq后，需判断其中的ApSvcAuthType字段信息，并按要求通过APSvcAuthenticRsp返回对应的订购关系信息。
例如，若要求移动办公插件（开通短信和彩信通信能力，无服务端）返回该业务的订购关系变量，则在ApSvcAuthType填写812100010002:2。
5.2.2.4.5. 业务性能上报通知
对于有WEB服务端的应用插件，插件管理模块通过此接口通知应用插件需进行业务性能上报。
操作：APSvcPerfCmd
业务触发条件：MAS服务器根据自身的业务性能上报需要，通过此接口向应用插件发起请求，请求获取该应用插件的业务性能信息，应用插件需根据要求统计对应的业务性能信息，并通过APSvcPerfReport操作上报业务性能信息。
输入：APSvcPerfCmdReq
| 参数 |
类型 |
可选性 |
描述 |
| Apid |
xsd: string |
M |
AP插件的标识 |
| ApSvcPerfCmdType |
xsd: string [0..unbounded] |
M |
业务性能数据统计要求 |
输出：APSvcPerfCmdRsp
无。
ApSvcPerfCmdType定义：
ApSvcPerfCmdType为插件管理模块的业务性能数据统计请求，格式为：“性能数据编码:业务性能上报统计的起始和结束时间”。其中，统计起始和结束时间字段的格式为“yyyymmddHHmmss, yyyymmddHHmmss”。应用插件在收到APSvcPerfCmdReq后，需判断其中的ApSvcPerfCmdType字段信息，并按照指令中的起始和结束时间统计性能数据，并在到达ApSvcPerfCmdType中所要求的性能统计结束时间之后，通过APSvcPerfReport发起性能数据上报。
5.2.2.4.6. 业务性能数据上报
操作：APSvcPerfReport
业务触发条件：此业务有两个触发条件，1）对于有Web服务端的应用插件，在收到通过APSvcPerfCmd操作发出的业务性能上报通知后；2）对于无Web服务端的应用插件，在收到APStatusRepRsp中的ApSvcPerfCmdType后。应用插件在上述两个触发条件下，应统计对应的业务性能信息。对于有Web服务端的应用插件，在到达APSvcPerfCmd中所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据；对于无Web服务端的应用插件，在到达APStatusRepRsp中ApSvcPerfCmdType字段所要求的性能统计结束时间之后，通过APSvcPerfReport发送性能数据。
输入：APSvcPerfReportReq
| 参数 |
类型 |
可选性 |
描述 |
| Apid |
xsd: string |
M |
AP插件的标识 |
| ApSvcPerfData |
xsd: string [0..unbounded] |
M |
业务性能数据 |
输出：APSvcPerfReportRsp
无。
ApSvcPerfData定义：
该项格式为：性能数据编码;性能数据;统计的起始结束时间
第一部分格式及定义参见“性能数据编码”一节的说明；
第二部分为多项’业务性能数据’的组合，各项业务性能数据之间用空格区分，如:12k 20 30对应着第一部分中的“性能编码”的000100030002，表示：GPRS流量为12k, 开户用户数为30人，活跃用户数为20人。
第三部分为统计的起始结束时间，具体格式为：yyyymmddHHmmss,yyyymmddHHmmss。
5.2.2.4.7. 注销插件
由应用插件AP发起进行注销插件进程。
操作：APLogOut
业务触发条件：应用插件AP的进程在结束之前，调用此接口进行注销。注销后的进程若重新使用，需要重新进行注册。
输入：APLogOutReq
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
| APPid |
xsd:int |
M |
AP插件的PID |
输出：APLogOutRsp
| 参数 |
类型 |
可选性 |
描述 |
| LogoutResult |
APLogoutResult |
M |
注销响应结果 |
差错：
业务异常：
ü SVC0001 - 业务错误.
策略异常：
ü POL0001 - 策略错误.
5.2.2.4.8. 插件暂停
此接口用于暂停AP的业务功能，由WebService插件发起。只有当应用插件有Web服务端的情况，才能使用该操作。
操作：PauseAP
WebService方式通信适配插件根据插件管理模块的要求，暂停AP的业务功能。如果插件要重新启用，需要在注销后由插件重新发起注册请求；或者由WebService插件重新启动AP。
输入：PauseAPReq
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
输出：PauseAPRsp
| 参数 |
类型 |
可选性 |
描述 |
| ACK |
xsd:Boolean |
M |
true表示成功，false表示失败。 |
差错：
业务异常：
ü SVC0001 - 业务错误.
策略异常：
ü POL0001 - 策略错误.
5.2.2.4.9. 插件恢复
此接口用于恢复AP的业务功能，由WebService方式通信适配插件发起，仅当应用插件有Web服务端时有效。
操作：RecoveryAP
WebService方式通信适配插件根据业务要求，恢复已暂停的AP的业务功能。
输入：RecoveryAPReq
| 参数 |
类型 |
可选性 |
描述 |
| APid |
xsd:string |
M |
AP插件的标识 |
输出：RecoveryAPRsp
| 参数 |
类型 |
可选性 |
描述 |
| ACK |
xsd:Boolean |
M |
true表示成功，false表示失败。 |
差错：
业务异常：
ü SVC0001 - 业务错误.
策略异常：
ü POL0001 - 策略错误.
1.1.3.应用系统服务通知接口
5.2.3.1 接口说明
此接口用于集团客户应用系统完成对短消息、多媒体消息、定位和USSD相关的服务通知。集团客户应用系统通过此接口通知WebService方式通信适配插件各通信能力对应的服务端URL，以及服务端是否开启或关闭。
5.2.3.2 流程说明
图5-3 应用系统服务通知流程示意图
对于应用系统支持服务端的情况，需要通过startNotification操作通知WebService方式通信适配插件各个通信能力对应的服务端URL，之后WebService方式通信适配插件可以调用服务端向应用系统发出各种消息通知，直到应用系统通过stopNotification通知服务端不可用为止。
应用系统可以多次执行startNotification和stopNotification操作，WebService方式通信适配插件以最后一次的通知为准。
WebService方式通信适配插件在向应用侧发出消息通知失败时，采用指数后退方式重试三次。若重试后仍失败，则抑制后续的所有消息通知。
5.2.3.3 接口定义
操作：startNotification
startNotification调用由应用系统发起，通知WebService方式通信适配插件，应用系统的服务端已经开启。应用系统在MessageNotification参数中注明各通信能力对应的服务端URL。
输入：startNotificationRequest
| 参数 |
类型 |
可选性 |
描述 |
| ApplicationId |
xsd:string |
M |
EC应用标识 |
| MessageNotification |
MessageNotificationType[] |
M |
应用的各通信能力对应的Web服务URL，若对应某通信能力，Web URL不填，表示对于该应用能力，应用插件不提供服务端，或服务端不可用。 |
输出：startNotificationResponse
无。
差错：
业务异常：
ü SVC0001 - 业务错误.
ü SVC0002 - 不合法的输入值.
ü SVC0005 - 重复关联符.
策略异常：
ü POL0001 - 策略错误.
操作：stopNotification
stopNotification调用由应用系统发起，通知WebService方式通信适配插件该应用系统不再提供服务端。
输入：stopNotificationRequest
| 参数 |
类型 |
可选性 |
描述 |
| ApplicationId |
xsd: string |
M |
EC应用ID |
输出：stopNotificationResponse
无。
差错
业务异常：
ü SVC0001 - 业务错误.
ü SVC0002 - 不合法的输入值.
策略异常：
ü POL0001 - 策略错误.
1.1.4.短消息接口
5.2.4.1 接口说明
集团客户应用系统和应用插件通过此接口收发短消息。WebService方式通信适配插件收到应用插件的发送请求后，通过MAS服务器基座中的SMS通信协议模块发送SMS；当从SMS通信协议模块收到SMS后，通过此接口将短消息发送给集团客户应用系统和应用插件。
5.2.4.2 流程说明
短消息接口包括发送和接收两个流程。
图5-4 短消息发送流程示意图
发送短信由应用系统或应用插件发起，通过sendSms操作实现。在提交短信发送请求之后，应用侧可以主动获取短信发送状态（getSmsDeliveryStatus操作），或由WebService方式通信适配插件通知应用侧短信发送状态（notifySmsDeliveryStatus操作）。
图5-5 短消息接收流程示意图
接收短信可以通过两种方式，一种是由应用侧发起（GetReceivedSms操作），WebService方式通信适配插件将所接收到的发往该应用的短信在响应中提交；第二种是由WebService方式通信适配插件通知应用侧有短信到达（notifySmsReception操作），短信内容包含在请求中。
5.2.4.3 数据类型
DeliveryStatus
含义：传送状态
数据类型：枚举，定义如下：
| 参数 |
描述 |
| Delivered |
短消息已成功递交。 |
| DeliveryUncertain |
递交状态未知：例如，因为短消息被发送到另外一个网络。 |
| DeliveryImpossible |
无法成功发送；短消息在超时前无法被递交。 |
| MessageWaiting |
消息仍在排队等待递交。这是一个临时状态，等待转换为前述的状态之一。 |
| DeliveryToTerminal |
短消息已发给终端。 |
| DeliveryNotificationNotSupported |
不支持短消息提交通知。 |
| KeyWordFilterFailed |
关键字过滤未通过。 |
DeliveryInformation
含义：传送消息
数据类型：结构。定义如下：
| 参数 |
类型 |
描述 |
| Address |
xsd: anyURI |
目的地址信息。 |
| DeliveryStatus |
DeliveryStatus |
发送状态。 |
SMSMessage
含义：短消息信息
数据类型：结构。定义如下：
| 参数 |
类型 |
描述 |
| Message |
xsd:string |
短消息中的文本。 |
| SmsServiceActivationNumber |
xsd: anyURI |
与被调用的消息业务相关的号码，即，终端用来发送消息的目标地址。 |
| SenderAddress |
xsd:anyURI |
指示短消息发送者的名称，即作为消息发起者显示在用户终端上的名称。 |
| MessageFormat |
MessageFormat |
编码格式。 |
MessageFormat
含义：消息编码类型
数据类型：枚举。定义如下：
| 参数 |
描述 |
| ASCII |
ASCII字符。 |
| UCS2 |
USC2格式的UniCode字符。 |
| GB18030 |
GB18030格式的中文字符。 |
| GB2312 |
GB2312格式的中文字符。 |
| Binary |
二进制短信，用十六进制字符串。 |
SendMethodType
含义：发送选项
数据类型：枚举。定义如下：
| 参数 |
描述 |
| Normal |
普通短信 |
| Instant |
普通短信立即显示 |
| Long |
长短信 |
| Structured |
长度小于160字节，但UDHI需置为1 |
5.2.4.4 接口定义
5.2.4.4.1. 发送短消息
操作：sendSms
sendSms调用是由应用系统或插件发起，请求发送一条短消息到一个指定地址（或地址集合），该短消息由Message描述，目的地址由DestinationAddress描述。对于可任意扩展服务代码的应用，应用可以通过ExtendCode填写应用内部的扩展码，MAS服务器需自动在其前面补充为该业务分配的长服务号码。对本接口的调用，MAS服务器应返回RequestIdentifier标识这次发送请求。如果消息的长度大于可支持的最大长度，此条消息将被分成若干条短消息进行发送。应用通过DeliverResultRequest告知是否需要返回状态报告。MAS根据要求用notifySmsDeliveryStatus接口返回状态报告。
输入：sendSmsRequest
| 参数 |
类型 |
可选性 |
描述 |
| ApplicationID |
xsd:string |
M |
应用ID或插件的ID。 |
| DestinationAddresses |
xsd:anyURI [0..unbounded] |
M |
短消息要被发送到的地址。 群发短消息的最大数量为254。 |
| ExtendCode |
xsd:string |
O |
指由该应用填写的内部扩展号码。MAS服务器需自动补充为此业务分配的长服务号码。 |
| Message |
xsd：string |
M |
在短消息中发送的文本。 |
| MessageFormat |
MessageFormat |
M |
消息编码类型。 |
| SendMethod |
SendMethodType |
M |
发送消息选项。 |
| DeliveryResultRequest |
xsd:boolean |
O |
指示是否需要网络侧返回递交状态报告。若无，则不返回。True表示需要网络侧返回递交状态报告，false表示不需要网络侧返回递交状态报告。 |
输出：sendSmsResponse
| 参数 |
类型 |
可选性 |
描述 |
| RequestIdentifier |
xsd:string |
M |
标识一个特定的短消息发送请求。 |
差错：
业务异常：
ü SVC0001 - 业务错误.
ü SVC0002 - 不合法的输入值.
ü SVC0004 - 不合法地址.
ü SVC0006 - 不合法的组.
ü SVC0280 - 消息过长.
策略异常：
ü POL0001 - 策略错误.
ü POL0003 –地址超界.
ü POL0006 - 组不被允许.
ü POL0007 - 嵌套的组不被允许.
ü POL0008 - 不允许支付.
操作：GetSmsDeliveryStatus
用于集团客户应用系统或应用插件查询短消息的发送状态。集团客户应用系统或应用插件通过requestIdentifier指定查询对应的发送请求，状态信息由DeliveryStatus返回。
输入：GetSmsDeliveryStatusRequest
| 参数 |
类型 |
可选性 |
描述 |
| ApplicationID |
xsd:string |
M |
应用ID或插件ID。 |
| RequestIdentifier |
xsd:string |
M |
在发送短信时由WebService方式通信适配插件分配的发送请求标识。 |
输出：GetSmsDeliveryStatusResponse
| 参数 |
类型 |
可选性 |
描述 |
| DeliveryStatus |
DeliveryInformation[0..unbounded] |
M |
列出短消息发送状态。 |
差错：
业务异常：
ü SVC0001 - 业务错误.
ü SVC0002 - 不合法的输入值.
策略异常：
ü POL0001 - 策略错误
5.2.4.4.2. 短消息通知
操作：notifySmsReception
通信适配插件收到发送到特定地址的短消息时，调用本接口，通知集团客户应用系统和应用插件有短消息到达，前提是应用系统或插件具备Web服务端。
输入：notifySmsReceptionRequest
| 参数 |
类型 |
可选性 |
描述 |
| Message |
SmsMessage |
M |
在短消息中发送的文本。 |
输出：notifySmsReceptionResponse
无。
差错：
无。
操作：notifySmsDeliveryStatus
应用系统或应用插件通过通信适配插件发送了短消息之后，通信适配插件对该短消息的发送分配了一个标识符RequestIdentifier。当通信适配插件获得状态报告后，调用本接口将短消息的发送状态报告给应用侧，前提是应用系统或插件具备Web服务端。状态信息在DeliveryInfomation中具体描述。
输入：notifySmsDeliveryStatusRequest
| 参数 |
类型 |
可选性 |
描述 |
| RequestIdentifier |
xsd:string |
M |
标识一个短消息发送请求。 |
| DeliveryInformation |
deliveryInformation[0..unbounded] |
M |
短消息递交状态参数。 |
输出：notifySmsDeliveryStatusResponse
无。
差错：
无。
5.2.4.4.3. 短消息接收
操作：GetReceivedSms
用于集团客户应用系统和应用插件从通信适配插件获取接收到的短消息。
通信适配插件返回receivedSms，包含短消息的发送者和内容。
输入：GetReceivedSmsRequest
| 参数 |
类型 |
可选性 |
描述 |
| ApplicationID |
xsd:string |
M |
应用ID或插件ID。 |
输出：GetReceivedSmsResponse
| 参数 |
类型 |
可选性 |
描述 |
| ReceivedSms |
SmsMessage [0..unbounded] |
M |
接收的短消息 |
差错：
业务异常：
ü SVC0001 - 业务错误.
ü SVC0002 - 不合法的输入值.
策略异常：
ü POL0001 - 策略错误
5.2.4.5 差错定义
业务异常：
SVC0280: 消息过长
| 参数 |
描述 |
| Message Id |
SVC0280 |
| Text |
消息过长。最大长度是%1字符。 |
| Variables |
%1在一个消息中允许的字符的数目。 |
SVC0281: 未知的数据格式
| 参数 |
描述 |
| Message Id |
SVC0281 |
| Text |
消息部分%1的数据格式不被认识。 |
| Variables |
%1带有不被认识的数据格式的消息。 |