中国电信宽乐通信接口规范文档.docx

1、中国电信宽乐通信接口规范文档深圳电信宽乐通信业务接口规范(修订版 2.0) 深圳电信分公司增值业务部1、概述 31.1 接口原则 31.2 目标 31.3 接口的调用方式 31.4 帐号申请 42、卓越通信向第三方提供的接口信息描述 42.1 总述 42.2 接口定义说明 72.2.1 注册接口 72.2.2 CTD 相关接口 92.2.3 CTC相关接口 122.2.4 SendSMS短信相关接口 182.2.5 第三方服务器需要实现通用回调函数 203、加密规则 244、通用失败码 241 概述本文档主要描述了深圳电信宽乐通信接口平台对第三方合作商开放业务能力的WebService接口和使

2、用规范。经运营商分配给使用账号后，第三方合作商能够使用宽乐通信业务平台的通信服务资源，主要有点击拨号、短信收发、多方会议、网络传真功能等服务。 1.1 接口原则第三方软件商在进行开发，使用相关接口时，须遵循以下原则： 严格按照接口规范文档中所定义的规范格式，进行数据处理 对于新增通信服务，将由深圳电信制定标准接口，并更新接口协议，通知第三方各软件合作商；1.2 目标宽乐通信与第三方软件商接口功能达到如下目标： 接口简单便于操作，并能够兼容接口以后扩充； 提供对外的开放性，能够具备接入认证功能，保证系统的安全性； 接口标准对外可靠和高效； 提供解决故障的手段和流程机制，由于面向客户提供的服务将由

3、传统方式中的运营商一种角色，转变成软件合作商和运营商多个角色，因此须提供高效的机制，能够定位故障和解决。1.3 接口的调用方式实现方式：调用Web Service服务，遵循标准的soap协议。第三方软件产品与宽乐通信业务平台互为客户端和服务端。第三方软件产品按照各操作规范和文档格式进行数据填充，主动调用宽乐通信业务平台提供的相关Web Service服务。平台根据应用请求注册的回调处理地址，异步返回回调处理。 1.4 帐号申请凡需使用深圳电信宽乐通信相关通信资源的的第三方合作商，需至深圳电信申请相应的宽乐通信帐号。该宽乐通信帐号具备相应的业务使用能力。2 宽乐通信向第三方提供的接口信息描述2.

4、1 总述第三方合作商应用服务器与宽乐通信业务平台互相开放WebService接口，互为服务端和客户端，接口符合本文定义。无论第三方应用服务器通过公网或者专线接入宽乐通信业务平台，都需要宽乐通信业务平台提供注册回调地址，以便宽乐通信业务平台能够异步推送结果响应和相关服务结果，同时需保证第三方应用服务器能够正常访问宽乐通信业务平台的WebService服务。 宽乐通信业务平台提供5个WebService 接口：a、 注册接口：RegisterURL: http:/202.105.212.146:8080/jboss-net/services/Registerb、CTD 接口：CTDCallURL:

5、http:/IP:port/ axis /services/CTDCallc、CTC 接口:CTCCallURL:http:/IP:port/ axis /services/CTCCalld、收发短信：SendSMSURL: http:/202.105.212.146:8080/jboss-net/services/SendSMS方法包括：sendSMSe、FAX接口：FAXServ请参见网络传真接口规范文档客户端在进行访问以上接口服务时均需进行鉴权，需添加用户名，密码。鉴权信息如下：用户名：test 密码：test 第三方必须提供WebService 回调地址，主要含如下内容：接口： 方法：

6、notifyStatusURL：由第三方软件合作商给出。 下表列出宽乐通信接口平台定义的全部WebService请求和事件报告所使用的接口方法：接口请求和事件方法（函数）方向（3rd Server为第三方应用平台、KLTX为宽乐通信业务平台）注册接口获取随机数请求getRandom3rd Server KLTX注册回调地址请求setCallBackAddr3rd Server KLTX回调地址更改报告notifyStatusKLTX 3rd ServerCTD接口发起CTD呼叫请求dialCall3rd Server KLTX发起CTD呼叫结果报告notifyStatusKLTX 3rd Se

7、rver终止CTD呼叫请求releaseCall3rd Server KLTX呼叫终止结果报告notifyStatusKLTX 3rd Server查询CTD呼叫请求getCallStatus3rd Server KLTXCTC接口发起会议请求createConf3rd Server KLTX发起会议结果报告notifyStatusKLTX 3rd Server查询会议列表getConfList3rd Server KLTX查询指定ID 会议室信息getConfInfo3rd Server KLTX查询指定ID 会议室的与会成员getConfMember3rd Server KLTX主持人邀请

8、与会者请求addIntoConf3rd Server KLTX主持人断开与会者请求delFromConf3rd Server KLTX主持人结束会议请求releaseConf3rd Server KLTX与会者进入会议通知notifyStatusKLTX 3rd Server与会者退出会议通知notifyStatusKLTX 3rd Server会议结束通知notifyStatusKLTX 3rd Server收发短信发送短信请求SendSMS3rd Server KLTX发送短信结果报告NotifyStatusKLTX 3rd Server发送短信回执EchoOfSendSMSKLTX 3r

9、d Server接收短信请求RecvSMSKLTX 3rd Server 第三方合作商应用平台调用宽乐通信业务平台WebService 接口的典型流程如下：(1) 第三方应用平台调用宽乐通信业务平台的GetRandom获取校验用的随机数。(2) 第三方应用平台用随机数与登录密码加密后，向宽乐通信业务平台发起注册回调地址请求SetCallBackAddr，该请求携带回调地址参数指明第三方服务器对宽乐通信业务平台开放的WebService接口的IP地址、URL和端口。宽乐通信业务平台对帐号密码鉴权通过后注册该帐号及对应的回调服务信息，生成一个连接id返回给第三方服务器，该连接id在第三方服务器后续

10、的请求中携带。一个帐号只能创建一个连接，最新的注册将使以前注册的回调地址信息失效。(3) 第三方应用平台重新调用宽乐通信业务平台的GetRandom获取校验用的随机数，并用该随机数加密DialCall接口调用的宽乐通信帐号和密码。(4) 第三方应用平台调用宽乐通信业务平台CTD呼叫请求DialCall接口。鉴权通过后宽乐通信业务平台服务器同步返回CTD会话id。(5) 宽乐通信业务平台根据CTD请求携带的主被叫号码发起CTD呼叫，首先呼通主叫，然后呼通被叫，接通主被叫。在此过程中，宽乐通信业务平台通过调用NotifyStatus接口向第三方应用平台上报正在接续主叫、接通主叫、呼叫建立开始通话等

11、事件。(6) 宽乐通信业务平台监控到主叫或被叫挂机，呼叫结束时，将通过NotifyStatus接口向第三方应用平台上报呼叫结束事件。(7) 呼叫结束前，第三方应用平台可通过CTD会话id调用ReleaseCall终止呼叫。 典型的交互流程如下图所示：2.2 接口定义说明以下可选项，可以填空字符串” ”。对于宽乐通信业务平台各业务能力服务调用时的数据填充以及对返回结果，请严格遵守如下相关规范说明和定义。2.2.1 注册接口2.2.1.1 获取随机数 接口说明：第三方服务器通过该接口获取对后续请求加密的随机数。每次调用其他函数，都需要先调用该函数获取新的随机数。 接口格式String GetRan

12、dom(); 输入参数说明无 返回参数说明参数类型必选/可选说明randString必选成功返回大于0 的随机数失败返回-12.2.1.2 注册/更改回调地址 接口说明该接口用于第三方服务器注册它的回调WebService 接口的地址，获取连接id。 接口格式String SetCallbackAddr(String uc,String pw, String rand, String url); 输入参数说明参数类型必选/可选说明ucString必选宽乐通信业务系统分配给第三方应用平台注册WebService 的用户号码pwString必选“GetRandom 获取的rand 参数+宽乐通信帐

13、号密码+宽乐通信帐号密码”经过MD5 加密后的字符串（以下加密方式相同）randString必选随机数urlString必选回调服务器的url（完整的WebService 访问地址，如：http:/102.71.103.47:8080/jboss-net/services/Callback） 返回参数说明参数类型必选/可选说明connIDString必选代表一个第三方应用平台与宽乐通信业务平台间的连接。第三方应用平台调用宽乐通信业务平台WebService接口时携带连接id，宽乐通信业务平台根据连接id 确定回调地址。返回值0 为连接通道ID；0 成功返回，返回值为呼叫标识；0 成功返回，表示

14、为会议标识0 失败码，同通用失败码。2.2.3.2 ReleaseConf 接口说明：用户用来终止自己发起的会议，通过宽乐通信业务平台释放指定的会场。 接口格式：String releaseConf(String uc, String pw, String rand,String confID) ; 输入参数说明：参数类型必选/可选说明ucString必选本次会议使用的宽乐通信号码.pwString必选“GetRandom 获取的rand 参数+宽乐通信帐号密码+宽乐通信帐号的密码”经过MD5 加密后的字符串（以下加密方式相同）randString必选随机数confIDString必选需释放的

15、会议ID 返回参数说明：参数类型必选/可选说明resString必选返回码说明：0 成功返回其他同通用失败码。2.2.3.3 GetConfInfo 接口说明：用户用来终止自己发起的会议，通过宽乐通信业务平台释放指定的会场。 接口格式：String getConfInfo(String uc, String pw, String rand,String confID) ; 输入参数说明：参数类型必选/可选说明ucString必选本次会议使用的宽乐通信号码.pwString必选“GetRandom 获取的rand 参数+宽乐通信帐号密码+卓宽乐通信帐号的密码”经过MD5 加密后的字符串（以下加密

16、方式相同）randString必选随机数confIDString必选需查询的会议ID 返回参数说明：参数类型必选/可选说明resString必选返回码说明：0 成功返回其他同通用失败码。sbjString可选会议主题（BASE64 编码后的字符串。）startString必选会议开始时间（格式:hhmmss 时分秒6 位字符串）pwString可选会议密码CerString必选会议主持人szString必选业务级的会场最大方数bgfString必选会议属性1，保留bgString可选会议属性2，保留recString必选会议属性4，保留tpString可选会场类型。0：普通会议conf-sta

17、teString必选会场的状态：0：初始化中（正在创建一个会议），不允许接受事务请求1：创建会议成功正在加入其他与会者，不允许接受事务请求。2：会议中，允许接受事务请求。创建会议成功，与会者加入完成后，为该状态3：结束会议，或者业务逻辑结束会议（主持人退出）时为该状态备注：返回值说明：返回的数组格式为res ,ConfID, sbj, start, pw, Cer, sz, bgf, bg, rec, tp,conf-state 2.2.3.4 GetConfMember 接口说明：用户查看指定会议的与会者信息。 接口格式：String getConfMember(String uc, Str

18、ing pw, String rand, String confID)； 输入参数说明：参数类型必选/可选说明ucString必选本次会议使用的宽乐通信号码.pwString必选“GetRandom 获取的rand 参数+宽乐通信帐号密码+宽乐通信帐号的密码”经过MD5 加密后的字符串（以下加密方式相同）randString必选随机数confIDString必选会议ID 返回参数说明：参数类型必选/可选说明resString必选返回码：0 成功返回。其他同通用失败码。numString必选与会者个数CallInfoceeString必选与会者号码stateString必选与会者状态：1 会议中

19、3 与会者保持会议autString必选与会者属性1，保留timeString必选与会者加入时间HHMMSS备注：返返回数组的格式为res,num,Ceeinfo1,Ceeinfo2其中：CeeInfo=cee|state|aut|time2.2.3.5 GetConfList 接口说明：用于查看该UC 号码正在进行中的会议。 接口格式：String getConfList(String uc, String pw, String rand)； 输入参数说明：参数类型必选/可选说明ucString必选本次会议使用的宽乐通信号码.pwString必选“GetRandom 获取的rand 参数+宽乐通信帐号密码+宽乐通信帐号的密码”经过MD5 加密后的字符串（以下加密方式相同）randString必选随机数 返回参数说明：参数类型必选/可选说明resString必选返回码：0 成功返回。其他同通用失败码。numString