宽乐通信WebService接口说明书V1.1-短信.doc

宽乐通信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） 注册接口：RegisterURL: 46:8080/jboss-net/services/Register2） 发送短信：SendSMSURL:46:8080/jboss-net/services/SendSMS以上接口都需要客户端API鉴权，访问WebService时请添加用户名，密码(test/test)。第三方必须提供WebService回调接口：接口名：由第三方给出方法：NotifyStatus、RecvSMS、EchoOfSendSMSURL：由第三方给出下表列出宽乐系统定义的Web Service（短信相关）请求和事件报告所使用的接口方法：接口请求和事件方法（函数）方向注册接口获取随机数请求getRandom3rd Server UC Portal注册接口注册回调地址请求setCallBackAddr3rd Server UC Portal回调地址更改报告NotifyStatusUC Portal 3rd Server收发短信发送短信请求sendSMS3rd Server UC Portal发送短信结果报告NotifyStatusUC Portal 3rd Server发送短信回执EchoOfSendSMSUC Portal 3rd Server接收短信请求RecvSMSUC Portal 3rd Server1.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(); 输入参数说明：参数类型必选/可选说明 返回参数说明：参数类型必选/可选说明randString必选成功返回大于0的随机数失败返回-12.1.2 注册/更改回调地址 接口说明：该接口用于第三方服务器注册它的回调WebService接口的地址，获取连接id。 接口格式：String setCallBackAddr(String uc, String pw, String rand, String url); 输入参数说明：参数类型必选/可选说明ucString必选UC系统分配给第三方服务器注册WebService的用户号码pwString必选“getRandom获取的rand参数+UC密码+UC密码” 经过MD5加密后的字符串（以下加密方式相同）randString必选随机数urlString必选回调服务器的url完整的WebService访问地址，如：7:8080/jboss-net/services/CallBack 返回参数说明：参数类型必选/可选说明connIDString必选连接id，代表一个第三方服务器与UC Portal的连接。第三方服务器调用UC WebService接口时携带连接id，UC Portal根据连接id确定回调地址。返回值说明：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); 输入参数说明：参数类型必选/可选说明ucString必选UC系统分配给第三方服务器发起WebService呼叫的用户号码。本次呼叫的使用的UC号码，费用记在该UC号码上。pwString必选“getRandom获取的rand参数+UC密码+UC密码” 经过MD5加密后的字符串randString必选随机数calleeString必选被叫号码（带区号）可以带多个被叫号码，最多10个。isreturnString必选该短信是否需要回执（0：不需要回执；1：需要回执。）contString可选短信内容（第三方服务器需要对短信内容进行BASE64编码）msgidint必选由终端生成的短信的标识，终端级唯一，用于接收发送状态、回执时匹配connIDString必选连接通道ID说明：callee = callee1,callee2 返回参数说明：参数类型必选/可选说明resString必选返回值说明：=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); 输入参数说明：参数类型必选/可选说明ucNumString必选发送方号码，用于第三方服务器定位发送客户端ceeString必选接收方号码msgidint必选短消息编号，用于客户端匹配请求消息resint必选回执的结果recvtString必选短消时间回执的结果说明：1： 接收方成功接收短信-1： 系统异常；-12：系统超时；-92：被叫号码不存在、对方短信中心异常、被叫号码状态异常等等2.2.3 接收短信请求 接口说明：第三方服务器需要提供接收短信WebService接口接收在其上登记的UC号码的短信。该接口同步返回结果，如果第三方服务器成功接收短信，将结果立即返回。 接口格式： String RecvSMS(String caller, String time, String cont, String ucNum); 输入参数说明：参数类型必选/可选说明callerString必选短信的发送者号码timeString必选短信发送时间，以http接口传过来的时间为准contString必选短信内容（第三方服务器需要对短信内容进行BASE64解码）ucNumString必选短信接受者号码（接收短信的UC号码） 返回参数说明：参数类型必选/可选说明resString必选返回值说明：=0：成功返回0：失败码失败码说明：-1：接收失败2.3 第三方服务器需要实现通用回调函数 接口说明：第三方服务器需要实现NotifyStatus函数用于接收相关参数并对相关参数进行处理。 接口格式：void NotifyStatus(int eventID, String sessionID,int res,String para1); 输入参数说明：参数类型必选/可选说明eventIDint必选接口事件ID：区别相应接口调用返回以及对其他事件的上报。sessionIDString必选呼叫标识/会议标识/短信标识/传真标识： resint必选失败码/状态码。para1String可选参数1其中失败码值小于0，全局编码；状态码与回调事件相关，值大于或等于0；para1参数的具体意义与回调事件相关。参见回调事件的具体说明。2.3.1 设置回调地址回调事件一、部分返回参数说明：eventIDint必选1para1String可选二、状态码说明：1：回调地址发生更改三、失败码说明：见回调事件通用失败码2.3.2 发送短信回调事件一、返回参数说明：eventIDint必选13para1String可选群发(兼容单发)短信的失败号码列表,该列表中的所有号码对应同一个错误码,号码之间采用|隔开本事件中sessionID参数即为请求消息中终端带过来的msgid参数，用于终端将该应答与短信发送请求对应。其中如果该事件是群发短信请求的应答事件，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 加密规则pwString“getRandom获取的rand参数+UC密码+UC密码” 经过MD5加密后的字符串4 通用失败码-1 系统异常-2 加密后的密码验证不通过-3请求中的UC号码不存在-4 用户类型非法（该用户没有权限完成该操作）-5 随机串超时，被disable了-6 与会者号码号码列表为空-7 通道ID不存在-8 WebService发起