目录

1. 接口对接

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

URL格式 

请求方式：POST
请求地址：https://api.ucpaas.com/{version}/Accounts/{accountSid}/safetyCalls/applyNumber?sig={SigParameter}\\

URL参数属性说明

属性 说明
Version 云之讯REST API版本号，当前版本号为：2014-06-30
Account 此参数为默认固定值
accountSid 注册云之讯官网，在控制台中即可获取此参数
Calls 业务功能
voiceNotify 业务操作，业务功能的各类具体操作分支
SigParameter 请求URL必须带有此参数

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}

请求参数说明

属性 类型 约束 说明
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回调通知地址，不填推到默认协商地址

响应参数说明

属性 类型 约束 说明
appId String 必选 创建应用时系统分配的唯一标示，在“应用列表”中可以查询
caller String 必选 主叫号码
callee String 必选 被叫号码
dstVirtualNum String 必选 用户指定分配的直呼虚拟中间保护号码 规则为0086+区号首位0+号码
bindId String 必选 分配唯一针对中间号码与主被叫号码的绑定Id

请求JSON 示例

请求JSON 示例 

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”
}


正确响应JSON 示例

正确响应JSON 示例 

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"
}


错误响应JSON 示例

错误响应JSON 示例 

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}

请求参数说明

属性 类型 约束 说明
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回调通知地址，不填推到默认协商地址

响应参数说明

属性 类型 约束 说明
appId String 必选 创建应用时系统分配的唯一标示，在“应用列表”中可以查询
caller String 必选 主叫号码(必须为11位手机号，号码前加0086，如008613631686024)
callee String 必选 规则同caller
dstVirtualNum String 必选 分配的直呼虚拟中间保护号码
bindId String 必选 分配唯一针对中间号码与主被叫号码的唯一绑定Id

请求JSON 示例

请求JSON 示例 

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”
}


正确响应JSON 示例

正确响应JSON 示例 

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"
}


错误响应JSON 示例

错误响应JSON 示例 

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}

请求参数说明

属性 类型 约束 说明
appId String 必选 创建应用时系统分配的唯一标示，在“应用列表”中可以查询
bindId String 必选 双方号码+中间号绑定ID，该ID全局唯一
cityId String 必选 城市Id格式为 0086+去零区号

请求JSON 示例

请求JSON 示例 

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",
}


正确响应JSON 示例

正确响应JSON 示例 

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"}


错误响应JSON 示例

错误响应JSON 示例 

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}

请求JSON示例

请求JSON示例 

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"
}


正确响应json示例

正确响应json示例 

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"}


错误响应json示例

错误响应json示例 

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

请求参数说明

属性 类型 约束 说明
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 可选 本次呼叫中被叫所显示号码

响应参数说明

属性 类型 约束 说明
retcode String 必选 返回错误码，0：成功 非0：失败
reason String 必选 原因描述

请求JSON 示例

请求JSON 示例 

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",
}

响应json 示例

响应json 示例 

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

请求参数说明

属性 类型 约束 说明
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 可选 本次呼叫中被叫所显示号码

响应参数说明

属性 类型 约束 说明
retcode String 必选 返回错误码，0：成功 非0：失败
reason String 必选 原因描述

请求json 示例

请求json 示例 

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"
}


响应json 示例

响应json 示例 

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

请求参数说明

属性 类型 约束 说明
appId String 必选 应用唯一标识
callId String 必选 通话唯一标识Id
requestId String 必选 接口传入唯一Id
caller String 必选 主叫号码
callee String 必选 被叫号码
dstVirtualNum String 必选 虚拟保护号码即中间号码
recordUrl String 必选 录音下载URL
bindId String 必选 绑定Id, 客户方平台保证唯一
calleeDisplayNum String 可选 本次呼叫中被叫所显示号码

响应参数说明

属性 类型 约束 说明
retcode String 必选 返回错误码，0：成功 非0：失败
reason String 必选 原因描述

请求json 示例

请求json 示例 

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"
}


响应json 示例

响应json 示例 

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"}