中国电信宽乐通信接口规范文档文档格式.docx
《中国电信宽乐通信接口规范文档文档格式.docx》由会员分享，可在线阅读，更多相关《中国电信宽乐通信接口规范文档文档格式.docx（35页珍藏版）》请在冰豆网上搜索。
1.3接口的调用方式
实现方式：
调用WebService服务，遵循标准的soap协议。
第三方软件产品与宽乐通信业务平台互为客户端和服务端。
第三方软件产品按照各操作规范和文档格式进行数据填充，主动调用宽乐通信业务平台提供的相关WebService服务。
平台根据应用请求注册的回调处理地址，异步返回回调处理。
1.4帐号申请
凡需使用深圳电信宽乐通信相关通信资源的的第三方合作商，需至深圳电信申请相应的宽乐通信帐号。
该宽乐通信帐号具备相应的业务使用能力。
2宽乐通信向第三方提供的接口信息描述
2.1总述
第三方合作商应用服务器与宽乐通信业务平台互相开放WebService接口，互为服务端和客户端，接口符合本文定义。
无论第三方应用服务器通过公网或者专线接入宽乐通信业务平台，都需要宽乐通信业务平台提供注册回调地址，以便宽乐通信业务平台能够异步推送结果响应和相关服务结果，同时需保证第三方应用服务器能够正常访问宽乐通信业务平台的WebService服务。
●宽乐通信业务平台提供5个WebService接口：
a、注册接口：
Register
URL:
http:
//202.105.212.146:
8080/jboss-net/services/Register
b、CTD接口：
CTDCall
http:
//IP:
port/axis/services/CTDCall
c、CTC接口:
CTCCall
port/axis/services/CTCCall
d、收发短信：
SendSMS
8080/jboss-net/services/SendSMS
方法包括：
sendSMS
e、FAX接口：
FAXServ
请参见《网络传真接口规范文档》
客户端在进行访问以上接口服务时均需进行鉴权，需添加用户名，密码。
鉴权信息如下：
用户名：
test
密码：
test
●第三方必须提供WebService回调地址，主要含如下内容：
接口：
方法：
notifyStatus
URL：
由第三方软件合作商给出。
●下表列出宽乐通信接口平台定义的全部WebService请求和事件报告所使用的接口方法：
接口
请求和事件
方法（函数）
方向（3rdServer为第三方应用平台、KLTX为宽乐通信业务平台）
注册接口
获取随机数请求
getRandom
3rdServer→KLTX
注册回调地址请求
setCallBackAddr
回调地址更改报告
KLTX→3rdServer
CTD接口
发起CTD呼叫请求
dialCall
发起CTD呼叫结果报告
KLTX→3rdServer
终止CTD呼叫请求
releaseCall
呼叫终止结果报告
查询CTD呼叫请求
getCallStatus
CTC接口
发起会议请求
createConf
发起会议结果报告
查询会议列表
getConfList
查询指定ID会议室信息
getConfInfo
查询指定ID会议室的与会成员
getConfMember
主持人邀请与会者请求
addIntoConf
主持人断开与会者请求
delFromConf
主持人结束会议请求
releaseConf
与会者进入会议通知
与会者退出会议通知
会议结束通知
收发短信
发送短信请求
发送短信结果报告
NotifyStatus
发送短信回执
EchoOfSendSMS
接收短信请求
RecvSMS
●第三方合作商应用平台调用宽乐通信业务平台WebService接口的典型流程如下：
（1）第三方应用平台调用宽乐通信业务平台的GetRandom获取校验用的随机数。
（2）第三方应用平台用随机数与登录密码加密后，向宽乐通信业务平台发起注册回调地址请求SetCallBackAddr，该请求携带回调地址参数指明第三方服务器对宽乐通信业务平台开放的WebService接口的IP地址、URL和端口。
宽乐通信业务平台对帐号密码鉴权通过后注册该帐号及对应的回调服务信息，生成一个连接id返回给第三方服务器，该连接id在第三方服务器后续的请求中携带。
一个帐号只能创建一个连接，最新的注册将使以前注册的回调地址信息失效。
（3）第三方应用平台重新调用宽乐通信业务平台的GetRandom获取校验用的随机数，并用该随机数加密DialCall接口调用的宽乐通信帐号和密码。
（4）第三方应用平台调用宽乐通信业务平台CTD呼叫请求DialCall接口。
鉴权通过后宽乐通信业务平台服务器同步返回CTD会话id。
（5）宽乐通信业务平台根据CTD请求携带的主被叫号码发起CTD呼叫，首先呼通主叫，然后呼通被叫，接通主被叫。
在此过程中，宽乐通信业务平台通过调用NotifyStatus接口向第三方应用平台上报正在接续主叫、接通主叫、呼叫建立开始通话等事件。
（6）宽乐通信业务平台监控到主叫或被叫挂机，呼叫结束时，将通过NotifyStatus接口向第三方应用平台上报呼叫结束事件。
（7）呼叫结束前，第三方应用平台可通过CTD会话id调用ReleaseCall终止呼叫。
●典型的交互流程如下图所示：
2.2接口定义说明
以下可选项，可以填空字符串””。
对于宽乐通信业务平台各业务能力服务调用时的数据填充以及对返回结果，请严格遵守如下相关规范说明和定义。
2.2.1注册接口
2.2.1.1获取随机数
●接口说明：
第三方服务器通过该接口获取对后续请求加密的随机数。
每次调用其他函数，都需要先调用该函数获取新的随机数。
●接口格式
StringGetRandom（）;
●输入参数说明
无
●返回参数说明
参数
类型
必选/可选
说明
rand
String
必选
成功返回大于0的随机数
失败返回-1
2.2.1.2注册/更改回调地址
●接口说明
该接口用于第三方服务器注册它的回调WebService接口的地址，获取连接id。
StringSetCallbackAddr（Stringuc,Stringpw,Stringrand,Stringurl）;
uc
宽乐通信业务系统分配给第三方应用平台注册WebService的用户号码
pw
“GetRandom获取的rand参数+宽乐通信帐号密码+宽乐通信帐号密码”经过MD5加密后的字符串（以下加密方式相同）
随机数
url
回调服务器的url（完整的WebService访问地址，如：
//102.71.103.47:
8080/jboss-net/services/Callback）
connID
代表一个第三方应用平台与宽乐通信业务平台间的连接。
第三方应用平台调用宽乐通信业务平台WebService接口时携带连接id，宽乐通信业务平台根据连接id确定回调地址。
返回值>
0为连接通道ID；
<
0为失败码，同通用失败码。
2.2.2CTD相关接口
2.2.2.1发起CTD呼叫
CTD呼叫即为用户指定主叫号码和被叫号码，通过宽乐通信业务平台建立主被叫之间的呼叫连接。
宽乐通信业务平台收到该请求后，鉴权该帐号，先呼起主叫，主叫摘机后，再呼起指定的被叫，被叫摘机后将呼叫连通。
该接口同步返回请求结果，如果宽乐通信业务系统接受此请求则返回CTD呼叫对应的会话id作为该呼叫后续请求和事件上报的识别id，如果失败则返回错误信息。
CTD呼叫状态将通过NotifyStatus调用异步返回给第三方服务器。
●接口格式：
StringDialCall（Stringuc,Stringpw,Stringrand,String[]callee,StringconnID,Stringcee）;
●输入参数说明：
参数类型必选/可选说明
宽乐通信平台分配给第三方应用的发起WebService呼叫的用户号码。
本次呼叫用的宽乐通信号码，费用记在该宽乐通信号码上
callee1
cee
必选主叫号码（带区号）
可选
主叫号码属性，保留，取值””
callee2
必选被叫号码（带区号）
连接通道ID
Cee
来电显示号码
说明：
callee={callee1,callee2}
其中：
callee1=cee|pw,callee2=cee|pw
（目前pw取值空，callee1=cee|,callee2=cee|）
●返回参数说明：
SessionID
呼叫标识：
在UCWebServer上具有唯一性。
标识一个CTD呼叫。
对用户不可见。
呼叫过程中可以通过呼叫标识作为关键字定位到该呼叫。
>
0成功返回，返回值为呼叫标识；
0失败码，同通用失败码
2.2.2.2终止CTD呼叫
用户用来终止他自己发起的CTD呼叫，通过宽乐通信业务平台断开主被叫之间的呼叫连接。
StringReleaseCall（Stringuc,Stringpw,Stringrand,StringSessionID）;
本次呼叫使用的宽乐通信号码.
“GetRandom获取的rand参数+宽乐通信帐号密码+宽乐通信帐号的密码”经过MD5加密后的字符串（以下加密方式相同）
必选呼叫标识
res
返回码:
0成功返回,其他同通用失败码。
2.2.2.3查询CTD呼叫状态
用户查看该宽乐通信号码的呼叫属性，可能返回多个呼叫信息。
String[]GetCallStatus（Stringuc,Stringpw,Stringrand）;
●输入参数说明：
UC号码
“GetRandom获取的rand参数+宽乐通信帐号+宽乐通信帐号的密码”经过MD5加密后的字符串
返回码：
0成功返回。
其他同通用失败码。
num
呼叫个数（如果res为失败码，该值为null。
）
CallInfo
Sessionid
呼叫标识
start
呼叫开始时间YYYYMMDDhhmmss（年月日时分秒，14位数字。
dur
可选呼叫持续时间
单位：
秒
Cer
主叫方
被叫方
state
呼叫状态:
1正在接通主叫。
2成功接通主叫，正在接通被叫。
3呼叫建立，正在通话。
4呼叫结束
备注：
返回值为字符串数组，格式为={res,num,CallInfo1,CallInfo2..}其中：
CallInfon=Sessionid|start|dur|Cer|Cee|state
2.2.3CTC相关接口
2.2.3.1CreateConf
用户指定主持人号码和与会者号码，通过宽乐通信业务平台建立主持人与各与会者的会议连接。
宽乐通信业务平台收到该请求后，鉴权用户帐号，先呼起主持人，主持人摘机进入会议后，再呼起指定的各个与会者，与会者摘机后进入会议。
宽乐通信业务平台在接受用户会议请求后，则返回该会议对应的会场id作为该会议后续请求和事件上报的识别id，如果失败则返回错误信息。
宽乐通信业务平台将通过NotifyStatus异步返回给第三方应用平台该会议的相关状态。
StringcreateConf（Stringuc,Stringpw,Stringrand,StringconnID,Stringnums[],Stringsbj,Stringconfpw）;
本次会议使用的宽乐通信号码.
连接ID
nums
参与会议的相关人员，（第一个为主持人，包含零、一个或者多个与会者），nums={cell1,cell2…}其中:
cell=cee|aut|pwd
与会者号码
aut
与会者属性1，保留，目前固定填1
pwd
与会者属性2，保留，目前为空
sbj
会议主题
confpw
会议密码
confID
会议标识：
在宽乐通信业务平台上具有唯一性。
标识一个会议。
返回值说明：
0成功返回，表示为会议标识
0失败码，同通用失败码。
2.2.3.2ReleaseConf
用户用来终止自己发起的会议，通过宽乐通信业务平台释放指定的会场。
StringreleaseConf（Stringuc,Stringpw,Stringrand,StringconfID）;
需释放的会议ID
返回码说明：
0成功返回
2.2.3.3GetConfInfo
String[]getConfInfo（Stringuc,Stringpw,Stringrand,StringconfID）;
“GetRandom获取的rand参数+宽乐通信帐号密码+卓宽乐通信帐号的密码”经过MD5加密后的字符串（以下加密方式相同）
需查询的会议ID
会议主题（BASE64编码后的字符
串。
会议开始时间（格式:
hhmmss时分
秒6位字符串）
会议主持人
sz
业务级的会场最大方数
bgf
会议属性1，保留
bg
会议属性2，保留
rec
会议属性4，保留
tp
会场类型。
0：
普通会议
conf-state
会场的状态：
初始化中（正在创建一个会议），不允许接受事务请求
1：
创建会议成功正在加入其他与会者，不允许接受事务请求。
2：
会议中，允许接受事务请求。
创建会议成功，与会者加入完成后，为该状态
3：
结束会议，或者业务逻辑结束会议（主持人退出）时为该状态
返回的数组格式为{res,ConfID,sbj,start,pw,Cer,sz,bgf,bg,rec,tp,conf-state}
2.2.3.4GetConfMember
用户查看指定会议的与会者信息。
String[]getConfMember（Stringuc,Stringpw,Stringrand,StringconfID）；
会议ID
与会者个数
与会者状态：
1会议中
3与会者保持会议
与会者属性1，保留
time
与会者加入时间HHMMSS
返返回数组的格式为{res,num,Ceeinfo1,Ceeinfo2…}其中：
CeeInfo=cee|state|aut|time
2.2.3.5GetConfList
用于查看该UC号码正在进行中的会议。
String[]getConfList（Stringuc,Stringpw,Stringrand）；
升级会员 