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

中国电信深圳分公司增值业务中心作者：审核人：-1-深圳电信宽乐通信业务接口规范(修订版2.0)深圳电信分公司增值业务部中国电信深圳分公司增值业务中心作者：审核人：-2-1、概述................................................................31.1接口原则.........................................................31.2目标.............................................................31.3接口的调用方式...................................................31.4帐号申请.........................................................42、卓越通信向第三方提供的接口信息描述..................................42.1总述.............................................................42.2接口定义说明.....................................................82.2.1注册接口.....................................................82.2.2CTD相关接口................................................102.2.3CTC相关接口................................................142.2.4SendSMS短信相关接口........................................252.2.5第三方服务器需要实现通用回调函数............................283、加密规则...........................................................344、通用失败码.........................................................34中国电信深圳分公司增值业务中心作者：审核人：-3-1概述本文档主要描述了深圳电信宽乐通信接口平台对第三方合作商开放业务能力的WebService接口和使用规范。经运营商分配给使用账号后，第三方合作商能够使用宽乐通信业务平台的通信服务资源，主要有点击拨号、短信收发、多方会议、网络传真功能等服务。1.1接口原则第三方软件商在进行开发，使用相关接口时，须遵循以下原则：严格按照接口规范文档中所定义的规范格式，进行数据处理对于新增通信服务，将由深圳电信制定标准接口，并更新接口协议，通知第三方各软件合作商；1.2目标宽乐通信与第三方软件商接口功能达到如下目标：接口简单便于操作，并能够兼容接口以后扩充；提供对外的开放性，能够具备接入认证功能，保证系统的安全性；接口标准对外可靠和高效；提供解决故障的手段和流程机制，由于面向客户提供的服务将由传统方式中的运营商一种角色，转变成软件合作商和运营商多个角色，因此须提供高效的机制，能够定位故障和解决。1.3接口的调用方式实现方式：调用WebService服务，遵循标准的soap协议。第三方软件产品与宽乐通信业务平台互为客户端和服务端。第三方软件产品按照各操作规范和文档格式进行数据填充，主动调用宽乐通信业务中国电信深圳分公司增值业务中心作者：审核人：-4-平台提供的相关WebService服务。平台根据应用请求注册的回调处理地址，异步返回回调处理。??????????????????????????????1.4帐号申请凡需使用深圳电信宽乐通信相关通信资源的的第三方合作商，需至深圳电信申请相应的宽乐通信帐号。该宽乐通信帐号具备相应的业务使用能力。2宽乐通信向第三方提供的接口信息描述2.1总述第三方合作商应用服务器与宽乐通信业务平台互相开放WebService接口，互为服务端和客户端，接口符合本文定义。无论第三方应用服务器通过公网或者专线接入宽乐通信业务平台，都需要宽乐通信业务平台提供注册回调地址，以便宽乐通信业务平台能够异步推送结果响应和相关服务结果，同时需保证第三方应用服务器能够正常访问宽乐通信业务平台的WebService服务。宽乐通信业务平台提供5个WebService接口：a、注册接口：RegisterURL:、CTD接口：CTDCallURL:、CTC接口:CTCCall中国电信深圳分公司增值业务中心作者：审核人：-5-URL:、收发短信：SendSMSURL:方法包括：sendSMSe、FAX接口：FAXServ请参见《网络传真接口规范文档》客户端在进行访问以上接口服务时均需进行鉴权，需添加用户名，密码。鉴权信息如下：用户名：test密码：test第三方必须提供WebService回调地址，主要含如下内容：接口：方法：notifyStatusURL：由第三方软件合作商给出。下表列出宽乐通信接口平台定义的全部WebService请求和事件报告所使用的接口方法：接口请求和事件方法（函数）方向（3rdServer为第三方应用平台、KLTX为宽乐通信业务平台）注册接口获取随机数请求getRandom3rdServer→KLTX注册回调地址请求setCallBackAddr3rdServer→KLTX回调地址更改报告notifyStatusKLTX→3rdServerCTD接口发起CTD呼叫请求dialCall3rdServer→KLTX发起CTD呼叫结果报告notifyStatusKLTX→3rdServer终止CTD呼叫请求releaseCall3rdServer→KLTX呼叫终止结果报告notifyStatusKLTX→3rdServer查询CTD呼叫请求getCallStatus3rdServer→KLTX中国电信深圳分公司增值业务中心作者：审核人：-6-CTC接口发起会议请求createConf3rdServer→KLTX发起会议结果报告notifyStatusKLTX→3rdServer查询会议列表getConfList3rdServer→KLTX查询指定ID会议室信息getConfInfo3rdServer→KLTX查询指定ID会议室的与会成员getConfMember3rdServer→KLTX主持人邀请与会者请求addIntoConf3rdServer→KLTX主持人断开与会者请求delFromConf3rdServer→KLTX主持人结束会议请求releaseConf3rdServer→KLTX与会者进入会议通知notifyStatusKLTX→3rdServer与会者退出会议通知notifyStatusKLTX→3rdServer会议结束通知notifyStatusKLTX→3rdServer收发短信发送短信请求SendSMS3rdServer→KLTX发送短信结果报告NotifyStatusKLTX→3rdServer发送短信回执EchoOfSendSMSKLTX→3rdServer接收短信请求RecvSMSKLTX→3rdServer第三方合作商应用平台调用宽乐通信业务平台WebService接口的典型流程如下：(1)第三方应用平台调用宽乐通信业务平台的GetRandom获取校验用的随机数。(2)第三方应用平台用随机数与登录密码加密后，向宽乐通信业务平台发起注册回调地址请求SetCallBackAddr，该请求携带回调地址参数指明第三方服务器对宽乐通信业务平台开放的WebService接口的IP地址、URL和端口。宽乐通信业务平台对帐号密码鉴权通过后注册该帐号及对应的回调服务信息，生成一个连接id返回给第三方服务器，该连接id在第三方服务器后续的请求中携带。一个帐号只能创建一个连接，最新的注册将使以前注册的回调地址信息失效。(3)第三方应用平台重新调用宽乐通信业务平台的GetRandom获取校验用的中国电信深圳分公司增值业务中心作者：审核人：-7-随机数，并用该随机数加密DialCall接口调用的宽乐通信帐号和密码。(4)第三方应用平台调用宽乐通信业务平台CTD呼叫请求DialCall接口。鉴权通过后宽乐通信业务平台服务器同步返回CTD会话id。(5)宽乐通信业务平台根据CTD请求携带的主被叫号码发起CTD呼叫，首先呼通主叫，然后呼通被叫，接通主被叫。在此过程中，宽乐通信业务平台通过调用NotifyStatus接口向第三方应用平台上报正在接续主叫、接通主叫、呼叫建立开始通话等事件。(6)宽乐通信业务平台监控到主叫或被叫挂机，呼叫结束时，将通过NotifyStatus接口向第三方应用平台上报呼叫结束事件。(7)呼叫结束前，第三方应用平台可通过CTD会话id调用ReleaseCall终止呼叫。典型的交互流程如下图所示：GetRandomrandSetCallBackAddrConnectionidGetRandomrandDialCallSessionidNotifyStatusNotifyStatusNotifyStatusNotifyStatus第三方应用平台ZYTX平台中国电信深圳分公司增值业务中心作者：审核人：-8-2.2接口定义说明以下可选项，可以填空字符串””。对于宽乐通信业务平台各业务能力服务调用时的数据填充以及对返回结果，请严格遵守如下相关规范说明和定义。2.2.1注册接口2.2.1.1获取随机数接口说明：第三方服务器通过该接口获取对后续请求加密的随机数。每次调用其他函数，都需要先调用该函数获取新的随机数。接口格式StringGetRandom();输入参数说明无返回参数说明参数类型必选/可选说明randString必选成功返回大于0的随机数失败返回-12.2.1.2注册/更改回调地址接口说明该接口用于第三方服务器注册它的回调WebService接口的地址，获取连接id。接口格式StringSetCallbackAddr(Stringuc,Stringpw,Stringrand,Stringurl);输入参数说明中国电信深圳分公司增值业务中心作者：审核人：-9-参数类型必选/可选说明ucString必选宽乐通信业务系统分配给第三方应用平台注册WebService的用户号码pwString必选“GetRandom获取的rand参数+宽乐通信帐号密码+宽乐通信帐号密码”经过MD5加密后的字符串（以下加密方式相同）randString必选随机数urlString必选回调服务器的url（完整的WebService访问地址，如：）返回参数说明参数类型必选/可选说明connIDString必选代表一个第三方应用平台与宽乐通信业务平台间的连接。第三方应用平台调用宽乐通信业务平台WebService接口时携带连接id，宽乐通信业务平台根据连接id确定回调地址。返回值0为连接通道ID；0为失败码，同通用失败码。中国电信深圳分公司增值业务中心作者：审核人：-10-2.2.2CTD相关接口2.2.2.1发起CTD呼叫接口说明：CTD呼叫即为用户指