宽乐通信Web Service接口说明书V1.1-短信
宽乐通信Web Service接口说明书V1.1（短信部分）中国电信股份有限公司广州研究院
宽乐通信 Web Service接口说明书（短信部分）
摘要：本文档主要描述宽乐通信对第三方服务器开放收发短信业务能力的Web Service接口，对接口格式和相应的参数给出了详细的描述。
1总述
宽乐系统（UC）通过Web Service接口对外提供CTD(点击拨号)、CTC（点击会议）、SMS(收发短信)等业务能力。
1.1宽乐帐号说明
宽乐系统分配给第三方服务器2种用户号码，Web注册访问用户（可以用于注册回调地址，可以发送短信等操作），Web访问用户（不可以注册回调地址，对应的注册访问用户注册后，可以发送短信等操作）。
补充说明：Web访问用户在哪个应用发送短信，就要在该应用下接受短信。
第三方服务器与宽乐Web Service服务器互相开放Web Service接口，互为服务器和客户端，接口符合本文定义。注意无论第三方服务器在公网或者私网内，都需要向宽乐Web Service服务器提供Web Service服务接口并能够访问宽乐的Web Service服务。
1.2接口总体说明
宽乐提供的短信相关的Web Service接口：
1）注册接口：Register
URL: http://202.105.212.146:8080/jboss-net/services/Register
2）发送短信：SendSMS
URL:http://202.105.212.146:8080/jboss-net/services/SendSMS
以上接口都需要客户端API鉴权，访问WebService时请添加用户名，密码(test/test)。
第三方必须提供WebService回调接口：
接口名：由第三方给出
方法：NotifyStatus、RecvSMS、EchoOfSendSMS
URL：由第三方给出
下表列出宽乐系统定义的Web Service（短信相关）请求和事件报告所使用的接口方法：
1.3收发短信流程
1.3.1注册
注意：第三方应用启动后，只需要调用一次该接口获得连接id即可，后续所有要用到connID的地方都可以用该值，不需要每次发送短信都注册。
(1)第三方服务器调用Web Service服务器的getRandom获取校验用的随机数。
(2)第三方服务器用随机数与登录密码加密后，向Web Service服务器发起注册回调地
址请求setCallBackAddr，该请求携带回调地址参数指明第三方服务器对UC开放的
WebService接口的IP地址、URL和端口。UC对帐号密码鉴权通过后注册该帐号及对
应的回调服务信息，生成一个连接id返回给第三方服务器，该连接id在第三方服
务器后续的请求中携带。一个帐号只能创建一个连接，最新的注册将使以前注册
的回调地址信息失效。
1.3.2发送短信
(1)第三方服务器重新调用Web Service服务器的getRandom获取校验用的随机数，并
用该随机数加密sendSMS接口调用的UC密码。
(2)第三方服务器调用Web Service服务器的发送短信请求sendSMS接口。
(3)Web Service服务器把短信请求提交给AS。
(4)如果鉴权成功，AS把短信提交到短信中心。
(5)AS通知Web Service服务器发送成功。
(6)Web Service服务器通过调用回调事件接口NotifyStatus向第三方服务器上报发
送短信状态。
(7)被叫接收到短信，Web Service服务器通知AS短信回执。
(8)AS计费，落话单。
(9)AS通知Web Service服务器第三方收到回执
(10)Web Service服务器通过调用发送短信回执EchoOfSendSMS接口向第三方服务器通
知被叫接收短信状态。
短信发送流程如下：
1.3.3接收短信
注意：宽乐帐号要能接收到短信，需要Web注册访问账号已经注册过（提交了回调地址）。
(1)宽乐接收短信时，Web Service服务器通过调用接收短信接口RecvSMS向第三方服
务器通知接收短信。
2接口定义
以下可选项，可以填空字符串””。
2.1注册接口
2.1.1获取随机数
?接口说明：
第三方服务器通过该接口获取对后续请求加密的随机数。每次调用其他函数，都需要先调用该函数获取新的随机数。
?接口格式：
String getRandom();
2.1.2注册/更改回调地址
?接口说明：
该接口用于第三方服务器注册它的回调WebService接口的地址，获取连接id。
?接口格式：
String setCallBackAddr(String uc, String pw, String rand, String url);
?输入参数说明：
>0：为连接通道ID
<0：为失败码，同通用失败码
2.2收发短信相关接口
2.2.1发送短信请求
?接口说明：
第三方服务器可以通过该接口使用UC号码发送短信。
该接口同步返回请求结果，如果UC系统接受此请求则返回发送短信成功码，如果失败则返回错误码（具体成功和错误码请参见如下返回值说明）。
发送短信的状态将通过NotifyStatus调用异步返回给第三方服务器。
?接口格式：
String sendSMS(String uc, String pw, String rand, String callee[], String isreturn, String cont, int msgid, String connID);
?输入参数说明：
=0：成功返回
<0：失败码如下
失败码说明：
-1：系统异常，发送短信失败；
-4：用户类型非法（该用户没有权限完成该操作）
-5：随字符串超时；
-7：通道ID不存在；
-12：系统超时；
-25：传入参数不合法；
-45：随机数字段长度不合法，或随机字符串无法转成Long型
-47：用户状态不正确（非激活状态）
-71：发送短信UC号码不存在；
-72：发送短信UC号码余额或限额不足；
-73：发送短信UC号码状态未激活；
-74：发送短信UC号码未开通短信功能；
-75：接收短信UC号码不存在；
-76：接收短信UC号码状态未激活；
-77：接收短信UC号码未开通短信功能；
-78：短信发送失败
-79：不能发送短信到接收号码
-84：短信群发超过群发允许的上限
-85：超过短信群发的日最大条数限制
-86：超过短信群发的月最大条数限制
2.2.2发送短信回执
?接口说明：
如果发送的短信被终端用户收到，会为短信发送用户提供短信回执。第三方服务器需要提供发送短信回执接口接收短信回执。
?接口格式：
void EchoOfSendSMS(String ucNum, String cee, int msgid, int res, String
recvt);
?输入参数说明：
回执的结果说明：
1：接收方成功接收短信
-1：系统异常；
-12：系统超时；
-92：被叫号码不存在、对方短信中心异常、被叫号码状态异常等等2.2.3接收短信请求
?接口说明：
第三方服务器需要提供接收短信WebService接口接收在其上登记的UC号码的短信。
该接口同步返回结果，如果第三方服务器成功接收短信，将结果立即返回。
?接口格式：
String RecvSMS(String caller, String time, String cont, String ucNum);
?输入参数说明：
?返回参数说明：
=0：成功返回
<0：失败码
失败码说明：
-1：接收失败
2.3第三方服务器需要实现通用回调函数
?接口说明：
第三方服务器需要实现NotifyStatus函数用于接收相关参数并对相关参数进行处理。
?接口格式：
void NotifyStatus(int eventID, String s essionID,int res,String para1);
的具体意义与回调事件相关。参见回调事件的具体说明。
2.3.1设置回调地址回调事件
二、状态码说明：1：回调地址发生更改
三、失败码说明：见回调事件通用失败码
2.3.2发送短信回调事件
端将该应答与短信发送请求对应。
其中如果该事件是群发短信请求的应答事件，para1参数中返回失败的目的号码，用“|”分割。
二、状态码说明：
1：短信发送成功（只代表本系统发送短信成功，还未得到短信回执）
三、失败码说明：
-1：系统异常；
-4：用户类型非法（该用户没有权限完成该操作）
-5：随字符串超时；
-7：通道ID不存在；
-12：系统超时；
-25：传入参数不合法；
-45：随机数字段长度不合法，或随机字符串无法转成Long型
-47：用户状态不正确（非激活状态）
-71：发送短信UC号码不存在；
-72：发送短信UC号码余额或限额不足；
-73：发送短信UC号码状态未激活；
-74：发送短信UC号码未开通短信功能；
-75：接收短信UC号码不存在；
-76：接收短信UC号码状态未激活；
-77：接收短信UC号码未开通短信功能；
-78：短信发送失败
-79：不能发送短信到接收号码
-84：短信群发超过群发允许的上限
-85：超过短信群发的日最大条数限制
-86：超过短信群发的月最大条数限制
其它错误码见回调事件通用失败码
3加密规则
4通用失败码
-1 系统异常
-2 加密后的密码验证不通过
-3请求中的UC号码不存在
-4 用户类型非法（该用户没有权限完成该操作）
-5 随机串超时，被disable了
-6 与会者号码号码列表为空
-7 通道ID不存在
-8 WebService发起的CTD呼叫和CTC呼叫的主叫号码被限制
//-9 UC已达最大同时使用数；(未用)
-10 该用户查询的CTD呼叫不存在
-12 系统超时
-19 由于预算数据没有配置，预算返回失败，提示主叫“被叫无法接通”
-25 参数不合法
-26 会议人数大于系统级配置值
-29 呼叫不存在
-30 会议不存在
-31 UC号码非指定会场主持人
-33 UC号码非发起CTD号码
-34 主持人UC号码不存在
-35 该与会者号码不在会议中
-36 事务正忙，不允许进行该操作
-37 会议不存在或会议尚未结束。
-38 已经在录音，无需再启动
-39 已经停止录音，无需再停止
-40 该用户没有会议列表
-41 已经在播放背景音，无需再启动
-42 已经在停止背景音，无需再停止
-45 随机数字段长度不合法，或随机字符串无法转成Long型
-43 无需修改听说权
-44 主持人不能修改听说权
-46 CTC主持人类型不正确
-47 用户状态不正确（非激活状态）
-48 主持人不能被踢出
-49 主叫号码或UC号码输入过长
-50 被叫号码或目的号码输入过长
//-78 该UC号码无权Web接入（未用）
-84：短信群发超过群发允许的上限
-85：超过短信群发的日最大条数限制
-86：超过短信群发的月最大条数限制
-99 操作频繁
-103 没有订阅传真功能
5回调事件通用失败码
-1 系统异常；
-80 帐户未到生效日期针对预付费帐户而言-81 帐户已过有效期针对预付费帐户而言
-82 发起呼叫预算时,少了计费数据