======1. 接口对接======

注意： 为了确保数据隐私和安全， REST API须通过HTTPS方式请求（查询子账号信息接口除外）

**URL格式** \\ 请求方式：POST 请求地址：https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/applyNumber?sig={SigParameter}\\ **URL参数属性说明** \\ {| !style="width:100%;","text-align:center;" ! |属性 ! |说明 |- |Version |云之讯REST API版本号，当前版本号为：2014-06-30 |- |Account |此参数为默认固定值 |- |accountSid |注册云之讯官网，在控制台中即可获取此参数 |- |Calls |业务功能 |- |voiceNotify |业务操作，业务功能的各类具体操作分支 |- |SigParameter |请求URL必须带有此参数 |- |} **** {| !style="width:100%;","text-align:center;" |Accept |客户端响应接收数据格式：application/xml、application/json |- |Content-Type |类型：application/xml;charset=utf-8、application/json;charset=utf-8 |- |Authorization |验证信息 |- |Content-Length |包体长度 |- |} **关键点** SigParameter是REST API 验证参数 URL后必须带有sig参数，sig= MD5（账户Id + 账户授权令牌 + 时间戳），共32位(注:转成大写) 使用MD5加密（账户Id + 账户授权令牌 + 时间戳），共32位 时间戳是当前系统时间（24小时制），格式“yyyyMMddHHmmss”。时间戳有效时间为50分钟。 Authorization是包头验证信息 使用Base64编码（账户Id + 冒号 + 时间戳） 冒号为英文冒号 时间戳是当前系统时间（24小时制），格式“yyyyMMddHHmmss”，需与SigParameter中时间戳相同 =====请求参数说明==== =======1. 双向绑定号码同步接口======= **接口功能** 本接口适用于隐号通话业务，也称为AXB 业务，即A、X、B 三个号码绑定，并且客户指定中间号码X。 此接口可以实现真实号码（A、B）和中间号码（X）之间的绑定关系，完成绑定后才可以使用中间号码的基本通信能力。 **请求方法** 请设置成“POST” **请求URL** https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/applyNumber?sig={SigParameter} 请求参数说明 {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |创建应用时系统分配的唯一标示，在“应用列表”中可以查询 |- |caller |String |必选 |主叫号码(必须为11位手机号，号码前加0086，如008613631686024) |- |callee |String |必选 |规则同caller |- |callerRingName |String |可选 |主叫呼入时播放IVR语音文件名 |- |calleeRingName |String |可选 |被叫呼入时播放IVR语音文件名 |- |dstVirtualNum |String |必选 |分配的直呼虚拟中间保护号码 规则为0086+区号首位0+号码 |- |bindId |String |必选 |绑定id，客户方平台保证唯一 |- |maxAge |String |必选 |主被叫+虚拟保护号码允许合作方最大cache存储时间(单位秒) |- |cityId |String |必选 |城市id |- |requestId |String |可选 |字符串最大长度不超过128字节，该requestId在后面话单和录音URL推送中原样带回 |- |record |String |可选 |是否录音，0表示不录音，1表示录音。默认为不录音 |- |maxAllowTime |String |可选 |允许最大通话时间单位分钟，不填默认为10分钟 |- |statusUrl |String |可选 |状态回调通知地址，正式环境可以配置默认推送地址 |- |hangupUrl |String |可选 |话单推送地址，不填推到默认协商地址 |- |recordUrl |String |可选 |录单URL回调通知地址，不填推到默认协商地址 |- |} 响应参数说明 {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |创建应用时系统分配的唯一标示，在“应用列表”中可以查询 |- |caller |String |必选 |主叫号码 |- |callee |String |必选 |被叫号码 |- |dstVirtualNum |String |必选 |用户指定分配的直呼虚拟中间保护号码 规则为0086+区号首位0+号码 |- |bindId |String |必选 |分配唯一针对中间号码与主被叫号码的绑定Id |- |} Encoding: UTF-8 Http-Method: POST {Accept=[application/json], accept-encoding=[gzip,deflate], connection=[Keep-Alive], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1], Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM= { "hangupUrl": "", "caller": "008618612341234", "appId": "7df01234567841ed816564bb12345678", "callerRingName": "1124", "bindId": “7df0123456ipoopujk7841ed816564bb12345678”, "requestId": "sel-define follow your heart and rules", “maxAge”: “600”, “record”: “0”, “maxAllowTime”: “10”, “dstVirtualNum”: “00861054890813”, “calleeRingName”: “1142”, “statusUrl”: “”, “callee”: “008613611133396”, “recordUrl”: “” “cityId”:”008610” } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]} Payload: { "caller":"18612341234", "appId":"7df01234567841ed816564bb12345678", "bindId":"7df0123456ipoopujk7841ed816564bb12345678", "dstVirtualNum":"0086201000123", "callee":"13611133396" } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:21:54 GMT]} Payload: {"errorCode":"102102"} \\ ======2.隐号通话接口对接--双向绑定号码申请接口====== **接口功能** 本接口适用于隐号通话业务，也称为AXB 业务，即A、X、B 三个号码绑定，并且中间号码X由云之讯进行分配。 此接口可以实现真实号码（A、B）和中间号码（X）之间的绑定关系，完成绑定后才可以使用中间号码的基本通信能力。 **请求方法** 请设置成“POST” **请求URL**\\ https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/allocNumber?sig={SigParameter} **请求参数说明**\\ {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |创建应用时系统分配的唯一标示，在“应用列表”中可以查询 |- |caller |String |必选 |主叫号码(必须为11位手机号，号码前加0086，如008613631686024) |- |callee |String |必选 |规则同caller |- |callerRingName |String |可选 |主叫呼入时播放IVR语音文件名 |- |calleeRingName |String |可选 |被叫呼入时播放IVR语音文件名 |- |maxAge |String |必选 |主被叫+虚拟保护号码允许合作方最大cache存储时间(单位秒) |- |cityId |String |必选 |城市id |- |requestId |String |可选 |字符串最大长度不超过128字节，该requestId在后面话单和录音URL推送中原样带回 |- |record |String |可选 |是否录音，0表示不录音，1表示录音。默认为不录音 |- |maxAllowTime |String |可选 |允许最大通话时间单位分钟，不填默认为10分钟 |- |statusUrl |String |可选 |状态回调通知地址，正式环境可以配置默认推送地址 |- |hangupUrl |String |可选 |话单推送地址，不填推到默认协商地址 |- |recordUrl |String |可选 |录单URL回调通知地址，不填推到默认协商地址 |- |} **响应参数说明**\\ {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |创建应用时系统分配的唯一标示，在“应用列表”中可以查询 |- |caller |String |必选 |主叫号码(必须为11位手机号，号码前加0086，如008613631686024) |- |callee |String |必选 |规则同caller |- |dstVirtualNum |String |必选 |分配的直呼虚拟中间保护号码 |- |bindId |String |必选 |分配唯一针对中间号码与主被叫号码的唯一绑定Id |- |} Encoding: UTF-8 Http-Method: POST {Accept=[application/json], accept-encoding=[gzip,deflate], connection=[Keep-Alive], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1], Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM= { "hangupUrl": "", "caller": "18612341234", "appId": "7df01234567841ed816564bb12345678", "callerRingName": "a.mp3", "requestId": "111111", "maxAge": "600", "record": "0", "maxAllowTime": "10", "dstVirtualNum": "0086221000123", "calleeRingName": "b.mp3", "statusUrl": "", "callee": "008613611133396", "recordUrl": "" “cityId”:”008620” } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]} Payload: { "caller":"18612341234", "appId":"7df01234567841ed816564bb12345678", "bindId":"7df01234567841ed816564bb12345678", "dstVirtualNum":"0221000123", "callee":"13611133396" } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:21:54 GMT]} Payload: {"errorCode":"102102"} =======3.隐号通话接口对接—双向绑定关系解除接口======= **接口说明** 本接口适用于隐号通话业务，当不再需要真实号码（ A、 B） 和虚拟号码（ X） 之间的绑定关系时，通知云之讯隐号通话平台将真实号码和虚拟 号码之间的绑定关系解除。解绑以后原真实号码用户将无法正常使用虚拟号码的基本通信能力。 **请求方式** 请设置成“POST” **请求路径** https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/freeNumber?sig={SigParameter} **请求参数说明**\\ {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |创建应用时系统分配的唯一标示，在“应用列表”中可以查询 |- |bindId |String |必选 |双方号码+中间号绑定ID，该ID全局唯一 |- |cityId |String |必选 |城市Id格式为 0086+去零区号 |- |} Encoding: UTF-8 Http-Method: POST {Accept=[application/json], accept-encoding=[gzip,deflate], connection=[Keep-Alive], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1], Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM= { “appId”: “1234b71f7c274b0782173a04509b1234”, "bindId": “7df0123456784ikyui1ed816564bb12345678”, "cityId": "008620", } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:28:39 GMT]} Payload: {"errorCode":"000000"} \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:24:15 GMT]} Payload: {"errorCode":"104127"} ======4.隐号通话接口对接—实时绑定并发数查询接口====== **接口说明** 本接口适用于交易类（AXB）隐号业务，通过该接口查询某个地区的线路并发数量。 **请求方式** 请设置成“POST” **请求URL路径**\\ https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/getConcurrent?sig={SigParameter} Encoding: UTF-8 Http-Method: POST Headers: {Accept=[application/json], accept-encoding=[gzip,deflate], connection=[Keep-Alive], Content-Length=[2], content-type=[application/json;charset=UTF-8], Authorization:ZTAzYmM5MTA2YzZlZDBlYWViZmNlOGMzNjhmZGNkNDg6MjAxNDA2MjMxODQ1MjM= { "appId":"125489wslfjlsjfklsjfljdslfjkf756962eaefa0", "cityId":"0086755" } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[39], Date=[Wed, 15 Jun 2016 09:33:16 GMT]} Payload: {"total":"0","008610":"0","008620":"0"} \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[22], Date=[Wed, 15 Jun 2016 09:35:22 GMT]} Payload: {"errorCode":"100007"} ======5.隐号通话接口对接—通话状态回调接口====== **接口说明** 查询某个呼叫的通话状态 **通话状态回调路径**\\ 可通过接口传参给定URL地址或者采用配置默认URL **请求参数说明**\\ {| !style="width:100%;","text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |平台分配 |- |callId |String |必选 |回拨请求响应中返回的callId |- |requestId |String |必选 |回拨请求时请求携带的requestId，原样返回 |- |caller |String |必选 |主叫号码 |- |dstVirtualNum |String |必选 |主叫通讯录直拨虚拟保护号码 |- |callee |String |必选 |被叫号码 |- |userFlag |String |必选 |该路通话中用于区分状态属于主叫/被叫 caller：主叫 callee：被叫，非绑定关系中的主被 |- |callStatus |String |必选 |invite：发起呼叫 ringing：响铃 answered：接听 refused：拒绝 disconnected：正常挂机 failed：呼叫异常 |- |errorCode |String |可选 |sip响应码 |- |timeStamp |String |必选 |状态发生的unix时间戳 |- |bindId |String |必选 |分配唯一针对中间号码与主被叫号码的绑定Id |- |calleeDisplayNum |String |可选 |本次呼叫中被叫所显示号码 |- |} **响应参数说明**\\ {| !style="width:100%;" , "text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |retcode |String |必选 |返回错误码，0：成功 非0：失败 |- |reason |String |必选 |原因描述 |- |} Encoding: UTF-8 Http-Method: POST Headers: {Accept=[application/json], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1]} { "appId":"123456", "callId":"fc84cc206c2d6b86af5fe9f37d4b13c3", "requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN", "caller":"008618503073759", "dstVirtualNum":"008675566616484", "callee":"008613828772876", "userFlag":"caller", "callStatus":"invite", "errorCode":0, "timeStamp":"1470620220", "bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166", "calleeDisplayNum":"008613828772876", } Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]} Payload: {"retcode":0,"reason":"OK“} ======6.隐号通话接口对接—话单回调接口======= **接口说明** 推送某个通话话单 **话单回调请求地址** 可通过接口传参给定URL地址或者采用配置默认URL **请求参数说明**\\ {| !style="width:100%;" , "text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |应用唯一标识 |- |callId |String |必选 |通话唯一标识Id |- |requestId |String |必选 |接口传入唯一Id |- |caller |String |必选 |主叫号码 |- |callee |String |必选 |主叫通讯录直拨虚拟保护号码 |- |dstVirtualNum |String |必选 |虚拟保护号码即中间号码 |- |callCenterAcceptTime |String |必选 |虚拟保护号码平台收到呼叫时间 |- |startDstCallTime |String |必选 |被叫呼叫开始时间 |- |startDstRingTime |String |可选 |被叫响铃开始时间 |- |dstAcceptTime |String |必选 |被叫接听时间 |- |endCallTime |String |必选 |用户挂机通话结束时间 |- |callEndStatus |String |必选 |通话最后状态[0：未知状态 1：正常通话 2：查询呼叫转移被叫号异常 ] |- |callerDuration |String |必选 |主叫接通虚拟保护号码到通话结束通话时间 |- |calleeDuration |String |必选 |呼叫转接被叫接通收到200ok到通话结束通话时间 |- |bindId |String |必选 |绑定id，客户方平台保证唯一 |- |calleeDisplayNum |String |可选 |本次呼叫中被叫所显示号码 |- |} **响应参数说明**\\ {| !style="width:100%;" , "text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |retcode |String |必选 |返回错误码，0：成功 非0：失败 |- |reason |String |必选 |原因描述 |- |} Encoding: UTF-8 Http-Method: POST Headers: {Accept=[application/json], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1] { "appId":"123456", "callId":"fc84cc206c2d6b86af5fe9f37d4b13c3", "requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN", "caller":"008618503073759", "callee":"008613828772876", "dstVirtualNum":"008675566616484", "callCenterAcceptTime":"1470620220", "startDstCallTime":"1470620220", "startDstRingTime":"1470620220", "dstAcceptTime":"1470620220", "endCallTime":"1470620222", "callerDuration":"2", "calleeDuration":"2", "callEndStatus":"1", "bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166", "calleeDisplayNum":"008613828772876" } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]} Payload: {"retcode":0,"reason":"OK"} ======7.隐号通话接口对接—录音回调接口====== **接口说明** 推送某个呼叫的录音文件下载到URL中 **录音回调请求地址** 可通过接口传参给定URL地址或者采用配置默认URL **请求参数说明** {| !style="width:100%;" , "text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |appId |String |必选 |应用唯一标识 |- |callId |String |必选 |通话唯一标识Id |- |requestId |String |必选 |接口传入唯一Id |- |caller |String |必选 |主叫号码 |- |callee |String |必选 |被叫号码 |- |dstVirtualNum |String |必选 |虚拟保护号码即中间号码 |- |recordUrl |String |必选 |录音下载URL |- |bindId |String |必选 |绑定Id, 客户方平台保证唯一 |- |calleeDisplayNum |String |可选 |本次呼叫中被叫所显示号码 |- |} **响应参数说明**\\ {| !style="width:100%;" , "text-align:center;" ! |属性 ! |类型 ! |约束 ! |说明 |- |retcode |String |必选 |返回错误码，0：成功 非0：失败 |- |reason |String |必选 |原因描述 |- |} Encoding: UTF-8 Http-Method: POST Headers: {Accept=[application/json], Content-Length=[316], content-type=[application/json;charset=UTF-8], host=[127.0.0.1] { "appId":"123456", "callId":"fc84cc206c2d6b86af5fe9f37d4b13c3", "requestId":"888F1ZXNzc3QyMjg5EIKABBjzjue5BSIkNTY4ODM4MzctN", "caller":"008618503073759", "callee":"008613828772876", "dstVirtualNum":"008675566616484", "recordUrl":"http://voiceproxy.oss-cn-beijing.aliyuncs.com/qq.proxy/20160808/7df0153d055841ed816564bb66aca62c_fc84cc206c2d6b86af5fe9f37d4b13c3_20160808.mp3", "bindId":"9999137-4ea5-43b7-9b49-5d4b95225144-5d4b95225166", "calleeDisplayNum":"008613828772876" } \\ Response-Code: 200 Content-Type: application/json;charset=utf-8 Headers: {Content-Type=[application/json;charset=utf-8], Content-Length=[163], Date=[Wed, 15 Jun 2016 09:13:58 GMT]} Payload: {"retcode":0,"reason":"OK"}