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

深圳电信宽乐通信业务接口规范深圳电信宽乐通信业务接口规范 修订版修订版 2 0 深圳电信分公司深圳电信分公司 增值业务部增值业务部 1 1 概述 概述 3 3 1 1接口原则 3 1 2目标 3 1 3接口的调用方式 3 1 4帐号申请 4 2 2 卓越通信向第三方提供的接口信息描述 卓越通信向第三方提供的接口信息描述 4 4 2 1总述 4 2 2接口定义说明 7 2 2 1注册接口 7 2 2 2CTD 相关接口 9 2 2 3CTC 相关接口 12 2 2 4SendSMS 短信相关接口 18 2 2 5第三方服务器需要实现通用回调函数 20 3 3 加密规则 加密规则 2424 4 4 通用失败码通用失败码 2424 1 概述概述 本文档主要描述了深圳电信宽乐通信接口平台对第三方合作商开放业务能力的 WebService 接口和使用规范 经运营商分配给使用账号后 第三方合作商能够使用宽乐通信业务平台的通信服务资 源 主要有点击拨号 短信收发 多方会议 网络传真功能等服务 1 1 接口原则接口原则 第三方软件商在进行开发 使用相关接口时 须遵循以下原则 严格按照接口规范文档中所定义的规范格式 进行数据处理 对于新增通信服务 将由深圳电信制定标准接口 并更新接口协议 通知第三方 各软件合作商 1 2 目标目标 宽乐通信与第三方软件商接口功能达到如下目标 接口简单便于操作 并能够兼容接口以后扩充 提供对外的开放性 能够具备接入认证功能 保证系统的安全性 接口标准对外可靠和高效 提供解决故障的手段和流程机制 由于面向客户提供的服务将由传统方式中的运 营商一种角色 转变成软件合作商和运营商多个角色 因此须提供高效的机制 能够定位故障和解决 1 3 接口的调用方式接口的调用方式 实现方式 调用 Web Service 服务 遵循标准的 soap 协议 第三方软件产品与宽乐通信业务平台互为客户端和服务端 第三方软件产品按照各操作规范和文档格式进行数据填充 主动调用宽乐通信业 务平台提供的相关 Web Service 服务 平台根据应用请求注册的回调处理地址 异步 返回回调处理 异步调用 同步响应 请求 卓越通信通信 资源 第三方应用系统或 软件产品 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 URL http IP port axis services CTDCall c CTC 接口 CTCCall URL http IP port axis services CTCCall d 收发短信 SendSMS URL http 202 105 212 146 8080 jboss net services SendSMS 方法包括 sendSMS e FAX 接口 FAXServ 请参见 网络传真接口规范文档 客户端在进行访问以上接口服务时均需进行鉴权 需添加用户名 密码 鉴权信 息如下 用户名 test 密码 test 第三方必须提供WebService 回调地址 主要含如下内容 接口 方法 notifyStatus URL 由第三方软件合作商给出 下表列出宽乐通信接口平台定义的全部WebService请求和事件报告所使用的接口 方法 接口 请求和事件方法 函数 方向 3rd Server 为第三方应用平台 KLTX 为宽乐通信业 务平台 获取随机数请求 getRandom3rd Server KLTX 注册回调地址请求 setCallBackAddr3rd Server KLTX 注册 接口 回调地址更改报告 notifyStatusKLTX 3rd Server 发起 CTD 呼叫请求 dialCall3rd Server KLTX 发起 CTD 呼叫结果 报告 notifyStatusKLTX 3rd Server 终止 CTD 呼叫请求 releaseCall3rd Server KLTX 呼叫终止结果报告 notifyStatusKLTX 3rd Server CTD 接口 查询 CTD 呼叫请求 getCallStatus3rd Server KLTX 发起会议请求 createConf3rd Server KLTX 发起会议结果报告 notifyStatusKLTX 3rd Server 查询会议列表 getConfList3rd Server KLTX 查询指定 ID 会议室 信息 getConfInfo3rd Server KLTX 查询指定 ID 会议室 的与会成员 getConfMember3rd Server KLTX 主持人邀请与会者 请求 addIntoConf3rd Server KLTX 主持人断开与会者 请求 delFromConf3rd Server KLTX 主持人结束会议请 求 releaseConf3rd Server KLTX 与会者进入会议通 知 notifyStatusKLTX 3rd Server 与会者退出会议通 知 notifyStatusKLTX 3rd Server CTC 接口 会议结束通知 notifyStatusKLTX 3rd Server 发送短信请求 SendSMS3rd Server KLTX 发送短信结果报告 NotifyStatusKLTX 3rd Server 发送短信回执 EchoOfSendSMSKLTX 3rd Server 收发 短信 接收短信请求 RecvSMSKLTX 3rd Server 第三方合作商应用平台调用宽乐通信业务平台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终止呼 叫 典型的交互流程如下图所示 GetRandom rand SetCallBackAddr Connectionid GetRandom rand DialCall Sessionid NotifyStatus NotifyStatus NotifyStatus NotifyStatus 第三方应用平台ZYTX平台 2 2 接口定义说明接口定义说明 以下可选项 可以填空字符串 对于宽乐通信业务平台各业务能力服务调用时的数据填充以及对返回结果 请严格遵 守如下相关规范说明和定义 2 2 1 注册接口注册接口 2 2 1 1 获取随机数 接口说明 第三方服务器通过该接口获取对后续请求加密的随机数 每次调用其他函 数 都需要先调用该函数获取新的随机数 接口格式 String GetRandom 输入参数说明 无 返回参数说明 参数类型必选 可 选 说明 randString必选成功返回大于0 的 随机数 失败返回 1 2 2 1 2 注册 更改回调地址 接口说明 该接口用于第三方服务器注册它的回调 WebService 接口的地址 获取连接 id 接口格式 String SetCallbackAddr String uc String pw String rand String url 输入参数说明 参 数 类型必选 可选 说明 ucString必选宽乐通信业务系统分配给第三方应用平台 注册WebService 的用户号码 pwString必选 GetRandom 获取的rand 参数 宽乐通信 帐号密码 宽乐通信帐号密码 经过MD5 加密 后的字符串 以下加密方式相同 randString必选随机数 urlString必选回调服务器的url 完整的WebService 访 问地址 如 http 102 71 103 47 8080 jboss net services Callback 返回参数说明 参数类型必选 可 选 说明 connIDString必选代表一个第三方应 用平台与宽乐通信业务 平台间的连接 第三方 应用平台调用宽乐通信 业务平台WebService接 口时携带连接id 宽乐 通信业务平台根据连接 id 确定回调地址 返回值 0 为连接 通道ID 0 成功返回 返回值为呼叫标识 0 成功返回 表示为会议标识 0 失败码 同通用失败码 2 2 3 2 ReleaseConf 接口说明 用户用来终止自己发起的会议 通过宽乐通信业务平台释放指定的会场 接口格式 String releaseConf String uc String pw String rand String confID 输入参数说明 参数类型必 选 可选 说明 ucString必 选 本次会议使用的宽乐通信号码 pwString必 选 GetRandom 获取的rand 参数 宽乐通信帐号密码 宽乐通信帐号 的密码 经过MD5 加密后的字符串 以下加密方式相同 randString必 选 随机数 confIDString必 选 需释放的会议ID 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码说明 0 成功返回 其他同通用失败码 2 2 3 3 GetConfInfo 接口说明 用户用来终止自己发起的会议 通过宽乐通信业务平台释放指定的会场 接口格式 String getConfInfo String uc String pw String rand String confID 输入参数说明 参数类型必 选 可选 说明 ucString必 选 本次会议使用的宽乐通信号码 pwString必 选 GetRandom 获取的rand 参数 宽乐通信帐号密码 卓宽乐通信帐 号的密码 经过MD5 加密后的字符 串 以下加密方式相同 randString必 选 随机数 confIDString必 选 需查询的会议ID 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码说明 0 成功返回 其他同通用失败码 sbjSt ring 可 选 会议主题 BASE64 编码后的字符 串 startSt ring 必 选 会议开始时间 格式 hhmmss 时分 秒6 位字符串 pwSt ring 可 选 会议密码 CerSt ring 必 选 会议主持人 szSt ring 必 选 业务级的会场最大方数 bgfSt ring 必 选 会议属性1 保留 bgSt可会议属性2 保留 ring选 recSt ring 必 选 会议属性4 保留 tpSt ring 可 选 会场类型 0 普通会议 conf state St ring 必 选 会场的状态 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 String pw String rand String confID 输入参数说明 参数类型必 选 可选 说明 ucString必 选 本次会议使用的宽乐通信号码 pwString必 选 GetRandom 获取的rand 参数 宽乐通信帐号密码 宽乐通信帐号 的密码 经过MD5 加密后的字符串 以下加密方式相同 randString必 选 随机数 confIDString必 选 会议ID 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码 0 成功返回 其他同通用 失败码 numSt ring 必 选 与会者个数 ceeSt ring 必 选 与会者号码 stat e St ring 必 选 与会者状态 1 会议中 3 与会者保持会议 autSt ring 必 选 与会者属性1 保留 Ca llInfo tim e St ring 必 选 与会者加入时间HHMMSS 备注 返返回数组的格式为 res num Ceeinfo1 Ceeinfo2 其中 CeeInfo cee state aut time 2 2 3 5 GetConfList 接口说明 用于查看该UC 号码正在进行中的会议 接口格式 String getConfList String uc String pw String rand 输入参数说明 参 数 类 型 必 选 可 选 说明 ucSt ring 必 选 本次会议使用的宽乐通信号码 pwSt ring 必 选 GetRandom 获取的rand 参数 宽乐通信 帐号密码 宽乐通信帐号的密码 经过MD5 加 密后的字符串 以下加密方式相同 ra nd St ring 必 选 随机数 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码 0 成功返回 其他同通用 失败码 numSt ring 必 选 会议个数 如果返回码为失败码 该参数为null confIDSt ring 必 选 会场ID 备注 返回数组格式为 res num confID1 confID2 confID3 2 2 3 6 AddIntoConf 接口说明 用于邀请其他人员加入指定会议 接口格式 String addIntoConf String uc String pw String rand String nums String confID 输入参数说明 参数类型必 选 可 选 说明 ucString必 选 本次会议使用的宽乐通信号码 pwString必 选 GetRandom 获取的rand 参数 宽乐通信帐号密码 宽乐通信帐号的密 码 经过MD5 加密后的字符串 以下 加密方式相同 randString必 选 随机数 c ee S tring 必 选 待加入的与会者号码 a ut S tring 必 选 与会者属性1 保留 固定取值1 nums 邀请参 与会议的相 关人员 nums cell1 cell2 其中 cell cee aut pwd p wd S tring 必 选 与会者属性2 保留 取值空 confIDString必 选 会场ID 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码 0 成功返回 其他同通用 失败码 失败码 返回成功表示UC 号 码鉴 权成功以及会议鉴权成功 准备添 加与会者 与会者添加成功与否通 过NotifyStatus 上报状态 失败码说明 0 成功返回 其他同通用失败码 2 2 3 7 DelFromConf 接口说明 会议主持人使与会者离开指定的会议 接口格式 String delFromConf String uc String pw String rand String cee String confID 输入参数说明 参数类型必 选 可 选 说明 ucString必本次会议使用的宽乐通信号码 选 pwString必 选 GetRandom 获取的rand 参数 宽乐通信帐号密码 宽乐通信帐号的密 码 经过MD5 加密后的字符串 以下 加密方式相同 randString必 选 随机数 ceeString必 选 待踢出的与会者号码 confIDString必 选 会场ID 返回参数说明 参数类 型 必 选 可选 说明 resSt ring 必 选 返回码 0 成功返回 其他同通用 失败码 2 2 4SendSMS 短信相关接口短信相关接口 2 2 4 1 SendMsg 接口说明 第三方服务器可以通过该接口使用 UC 号码发送短信 该接口同步返回请求结果 如果 UC 系统接受此请求则返回发送短信对应的会话 id 作 为该发送短信请求后续的事件上报的识别 id 如果失败则返回错误信息 发送短信的状态将通过NotifyStatus调用异步返回给第三方服务器 接口格式 String SendSMS String uc String pw String rand String callee String isreturn String cont int msgid String connID 输入参数说明 参数类型必选 可选说明 ucString 必选宽乐通信业务平台分配给第三方服务器 发起 WebService 呼叫的用户号码 本次呼叫的使用的宽乐通信业务号码 费用记在该宽乐通信业务号码号码上 pwString 必选宽乐通信业务号码号码对应的密码 MD5 加密 randString 必选随机数 callee String 必选被叫号码 带区号 可以带多个被叫号 码 iseturnString 必选该短信是否需要回执 0 不需要回执 1 需要回执 contString 可选短信内容 msgidint 必选由第三方生成的短信的标识 第三方级 唯一 connIDString 必选连接通道 ID 说明 Callee Callee1 Callee2 返回参数说明 参数参数类型类型必选必选 可选可选说明说明 resString必选 返回值说明 0 成功返回 0 失败码如下 失败码说明 1 发送短信失败 2 2 4 22 2 4 2notifySmsReceipt 接口说明 如果发送的短信被第三方用户收到 会为短信发送用户提供短信回执 第三方服务器 需要提供发送短信回执接口接收短信回执 接口格式 Void EchoOfSendSMS String ucNum String cee int msgid int res String recvt 输入参数说明 参数参数类型类型必选必选 可选可选说明说明 ucNumString 必选发送方号码 用于第三方服务器定位发 送客户端 ceeString 必选接收方号码 msgidint 必选短消息编号 用于客户端匹配请求 消息 resint 必选回执的结果 recvtString 必选短消时间 回执的结果说明 1 接收方成功接收短信 1 系统异常 12 系统超时 2 2 4 32 2 4 3recvMsgrecvMsg 接口说明 第三方服务器需要提供接收短信 WebService 接口接收在其上登记的宽乐通信业务号 码号码的短信 该接口同步返回结果 如果第三方服务器成功接收短信 将结果立即返回 接口格式 String RecvSMS String caller String time String cont String ucNum 输入参数说明 参数参数类型类型必选必选 可选可选说明说明 callerString 必选短信的发送者号码 timeString 必选短信发送时间 以 http 接口传过来的 时间为准 contString 必选短信内容 ucNumString 必选短信接收者号码 接收短信的 UC 号码 返回参数说明 参数参数类型类型必选必选 可选可选说明说明 resString 必选 返回值说明 0 成功返回 0 失败码 失败码说明 1 接收失败 2 2 5 第三方服务器需要实现通用回调函数第三方服务器需要实现通用回调函数 接口说明 第三方服务器需要实现NotifyStatus 函数用于接收相关参数并对相关参数进 行处理 接口格式 void NotifyStatus int eventID String sessionID int res String para1 输入参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 接口事件ID 区别相应接口调用返回 以及对其他事件的上报 sessionI D S tring 必 选 呼叫标识 会议标识 当eventID为短 信事件ID 13时 该字段值为短信 msgID resS tring 必 选 失败码 状态码 para1S tring 可 选 参数1 其与具体回调事件相关 请 参见回调事件的具体说明 2 2 5 1设置回调地址回调事件 部分返回参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 1 para1S tring 可 选 resS tring 状态码说明 1 回调地址发生更改 失败码说明 1 系统异常 2 2 5 2发起 CTD 呼叫回调事件 返回参数说明 参数类必说明 型选 可选 eventIDi nt 必 选 2 para1S tring 可 选 resS tring 状态码说明 1 正在接通主叫 2 成功接通主叫 正在接通被叫 3 呼叫建立 开始通话 失败码说明 1 系统异常 8 UC 余额或月限额不足 12 系统超时 13 主叫无法接通 包括挂机 未激 活 14 被叫无法接通 包括挂机 未激 活 17 主叫忙 18 被叫忙 19 主叫无应答 20 被叫无应答 24 保留 25 保留 41 发起者未激活 2 2 5 3呼叫释放回调事件 部分返回参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 3 para1S tring 可 选 resS tring 状态码说明 1 呼叫结束成功 失败码说明 1 系统异常 2 2 5 4多方会议回调事件 2 2 5 4 1发起多方会议回调事件 部分返回参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 4 para1S tring 可 选 resS tring 必 选 状态码说明 1 正在接通主持人 2 主持人加入会议 失败码说明 1 系统异常 11 发起者UC号码不存在 12 发起者状态未激活 13 发起者余额或月限额不足 14 发起者未订阅此功能 15 主持人鉴权失败 16 主持人忙 17 主持人无应答 18 路由主持人失败 2 2 5 4 2与会者进入会议回调事件 部分返回参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 5 para1S tring 可 选 与会者号码 resS tring 必 选 状态码说明 0 与会者加入会议 失败码说明 1 系统异常 加入失败 2 会场已满 3 用户已在会场中 4 用户类型不正确 8 主持人余额或月限额不足 会议 期间费用被扣完 22 保留 61 与会者无法接通 17 与会者忙 18 与会者无应答 2 2 5 4 3与会者退出会议回调事件 部分返回参数说明 参数类 型 必 选 可选 说明 eventIDi nt 必 选 6 para1S tring 可 选 与会者号码