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