# AXB模式绑定接口 - CreateAXBBinding #### 接口功能 该接口用于客户向隐私保护通话平台设置用户A、隐私号码X和用户B之间的绑定关系。 #### 请求方向 客户应用（客户端） → 隐私保护通话平台（服务端） #### 使用说明 **前提条件** - 已创建隐私保护通话应用，获取了APP_Key，APP_Secret和APP接入地址。 - 已申请到隐私保护号码。 - 已报备实际使用人号码（隐私号A路）。 ![](https://support.huaweicloud.com/api-PrivateNumber/public_sys-resources/note_3.0-zh-cn.png) 未报备的A号码不会影响绑定，但呼叫会被拦截。 - 若需要使用自定义放音，需要提前在[放音文件管理](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)页面上传并等待审核通过。 **使用限制** 1个X号码允许绑定5000对用户号码，但用户号码不可重复。例如，允许同时绑定AXB和CXD，但不允许同时绑定AXB和BXC。 **注意事项** - AXB模式支持设置AXB绑定关系时长（通过duration参数设置），绑定关系到期后自动解绑；还支持设置单次通话进行的最长时间（通过maxDuration参数设置），到期后系统自动挂断通话。 - 若要使用录音功能，需要完成以下两个步骤： 1. 创建隐私保护通话应用时，"是否开通录音"选择"是"。 2. 调用本接口设置归属该应用的隐私号码绑定关系时设置"recordFlag"为"true"。 注：如果是在控制台设置归属该应用的隐私号码绑定关系，需在设置绑定关系时勾选"支持录音"。 - 若要使用短信功能，需要完成以下三个步骤： 1. 创建隐私保护通话应用时，"是否开通短信"选择"是"； 2. 订购号码时，"是否需要短信功能"选择"是"； 3. 调用本接口设置归属该应用的隐私号码绑定关系时不携带"privateSms"或设置"privateSms"为"true"。 注：如果是在控制台设置归属该应用的隐私号码绑定关系，需在设置绑定关系时勾选"支持短信"。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限管理](https://support.huaweicloud.com/productdesc-PrivateNumber/privatenumber_permissions.html)。 #### URI POST /rest/caas/relationnumber/partners/v1.0 #### 请求参数 表1请求Headers参数说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | Content-Type | 是 | String | **参数解释：** 消息体的类型（格式）。 **约束限制：** 不涉及。 **取值范围：** 固定填写为application/json;charset=UTF-8。 **默认取值：** 不涉及。 | | Authorization | 是 | String | 固定填写为AKSK realm="SDP",profile="UsernameToken",type="Appkey"。 | | X-AKSK | 是 | String | 取值为UsernameToken Username="APP_Key的值", PasswordDigest="PasswordDigest的值", Nonce="随机数", Created="随机数生成时间"。 - PasswordDigest：根据PasswordDigest = Base64 (HMAC-SHA256 (Password，Nonce + Created))生成。其中，Password为APP_Secret的值。Nonce、Created、Password直接进行字符串拼接即可，无需包含+号和空格。 - Nonce：客户发送请求时生成的一个随机数，长度为1\~128位，可包含数字和大小写字母。例如：66C92B11FF8A425FB8D4CCFE0ED9ED1F。 - Created：随机数生成时间。采用标准UTC格式，例如：2018-02-12T15:30:20Z。不同编程语言中的时间格式转换方式不同，部分语言可参考[表2]。 | 表2不同编程语言的时间格式 | 编程语言 | 时间格式 | |:---|:---| | Java | yyyy-MM-dd'T'HH:mm:ss'Z' | | PHP | Y-m-d\\TH:i:s\\Z | | Python | %Y-%m-%dT%H:%M:%SZ | | C# | yyyy-MM-ddTHH:mm:ssZ | | Node.js | toISOString().replace(/.\[0-9\]+\\Z/, 'Z') 注：Node.js中，使用toISOString()转换后的时间格式去除毫秒后即为本接口要求的时间格式。 | 表3请求Body参数说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | callerNum | 是 | String(4-31) | AXB中的A号码。 填写为全局号码格式。 - 手机号码格式为国家码（如+86）+手机号码（11位数字的手机号码，如138\*\*\*\*0001），填写为"+86138\*\*\*\*0001"。 - 固话号码为国家码（如+86）+不带前置0的区号（如755）+本地固话号码（7或8位数字的固话号码，以实际号码为准，如28\*\*\*\*01），填写为"+8675528\*\*\*\*01"。 说明： - 因运营商管控，固话号码只能接收来自X号码的呼叫，不能作为主叫呼叫X号码。即当A号码为固话号码时，B（手机号码）可以拨打X号码联系A，但A无法通过拨打X号码联系B。 - 若需双向呼叫，A和B号码都必须是手机号码。 | | relationNum | 否 | String(4-31) | 指定已申请到的X号码进行绑定。 可在隐私保护通话控制台的"号码管理"页面或订购号码成功后返回的号码表中查看已申请到的X号码。 填写为全局号码格式（国家码+11位数字的手机号码），如：+86138\*\*\*\*0021。 - 当callerNum（A号码）是手机号码时： - 同时携带relationNum和areaCode时系统以relationNum为准。 - 当relationNum和areaCode都未携带时，隐私保护通话平台会从客户应用下已申请到的X号码中，优先选择与A号码同城市的X号码进行绑定。 - 当callerNum（A号码）是固话号码时： - **该参数与areaCode是二选一关系。** - 同时携带relationNum和areaCode时系统以relationNum为准。 | | areaCode | 否 | String(0-32) | 指定城市码，由隐私保护通话平台从客户已申请到的X号码中选择可用号码进行绑定。 填写为标准格式的城市码，如：0755、010等。 X号码对应城市码可在订购号码成功后返回的号码表中查看，[点击查看如何下载号码表](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_numberareacode.html)。 - 当callerNum（A号码）是手机号码时： - 同时携带relationNum和areaCode时系统以relationNum为准。 - 当relationNum和areaCode都未携带时，隐私保护通话平台会从客户应用下已申请到的X号码中，优先选择与A号码同城市的X号码进行绑定。 - 当callerNum（A号码）是固话号码时： - **该参数与relationNum是二选一关系。** - 同时携带relationNum和areaCode时系统以relationNum为准。 | | areaMatchMode | 否 | String(枚举) | 号码筛选方式。当指定areaCode或根据callerNum（A号码）区号选择X号码（relationNum和areaCode都不携带）时，此参数生效。 - 当指定areaCode时： - 0：严格匹配，应用下无对应areaCode的X号码时，号码分配失败。 - 1：非严格匹配，应用下无对应areaCode的X号码时，会优先选择该应用下与areaCode对应区域同省份的号码，若也没有同省份的号码，则从该应用下全部X号码中随机选择。 - 根据A号码区号选择X号码时： - 0：严格匹配，应用下没有和A号码同区域的X号码时，号码分配失败。 - 1：非严格匹配，应用下没有和A号码同区域的X号码时，会优先选择该应用下与A号码所属区域同省份的号码，若也没有同省份的号码，则从该应用下全部X号码中随机选择。 不携带该参数时，系统默认为严格匹配模式。 | | calleeNum | 是 | String(4-31) | AXB中的B号码。 填写为全局号码格式。 - 手机号码格式为国家码（如+86）+手机号码（11位数字的手机号码，如138\*\*\*\*0001），填写为"+86138\*\*\*\*0001"。 - 固话号码为国家码（如+86）+不带前置0的区号（如755）+本地固话号码（7或8位数字的固话号码，以实际号码为准，如28\*\*\*\*01），填写为"+8675528\*\*\*\*01"。 说明： - 因运营商管控，固话号码只能接收来自X号码的呼叫，不能作为主叫呼叫X号码。即当B号码为固话号码时，A（手机号码）可以拨打X号码联系B，但B无法通过拨打X号码联系A。 - 若需双向呼叫，A和B号码都必须是手机号码。 | | callDirection | 否 | Integer | 表示该绑定关系允许的呼叫方向，取值范围： - 0：bidirectional，表示callerNum和calleeNum都可以通过X号码呼叫对方。 - 1：caller to callee，表示只允许callerNum通过X号码呼叫calleeNum。 - 2：callee to caller，表示只允许calleeNum通过X号码呼叫callerNum。 如果不携带该参数，系统默认允许双向呼叫。 | | duration | 否 | Integer | 绑定关系保持时间，单位为秒。 取值范围：0\~7776000（90天）。 绑定关系过期后会被系统自动解除。 **如果不携带该参数或携带为0，系统默认永不过期。** | | recordFlag | 否 | String(枚举) | 是否需要针对该绑定关系产生的所有通话录音。 - false：表示不录音 - true：表示录音。 该参数仅当客户添加应用时申请开通了录音功能才有效。 如果不携带该参数，系统默认不录音。 | | recordHintTone | 否 | String(1-128) | 该参数仅在recordFlag为true时有效。 该参数用于设置录音提示音，填写为放音文件名，可在[放音文件管理](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)页面查看。 说明： 因隐私协议及运营商管控，录音的呼叫必须携带该参数，否则呼叫会被运营商拦截。 | | preVoice | 否 | [ApiPlayInfo] | 设置个性化通话前等待音，即主叫听到的回铃音。 说明： **仅部分号码支持，如需使用该功能请咨询华为云客服。** | | maxDuration | 否 | Integer | 设置允许单次通话进行的最长时间，单位为分钟。通话时间从接通被叫的时刻开始计算。 取值范围：0\~1440 - 0：系统不主动结束通话，由主被叫双方结束通话。 - 1\~1440：当通话时长达到此配置值，系统主动结束通话。 不携带时，参数值默认为0。 | | lastMinVoice | 否 | String(0-128) | 设置通话剩余最后一分钟时的提示音，填写为放音文件名，可在[放音文件管理](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)页面查看。 当maxDuration字段设置为非0时此参数有效。 不携带该参数表示通话剩余最后一分钟时不放音。 说明： **仅部分号码支持，如需使用该功能请咨询华为云客服。** | | privateSms | 否 | String(枚举) | 设置该绑定关系是否支持短信功能。 若客户添加应用时未开通短信功能，请勿携带此参数。 取值范围： - false：不支持短信 - true：支持短信 如果客户添加应用时开通了短信功能，不携带该参数时系统默认支持短信。 | | displayNumMode | 否 | Integer | 主叫号码显示模式。 隐私号呼叫场景：呼叫时被叫看到的主叫号码。 - 0：A呼叫X和B呼叫X，被叫显示的主叫号码都是X号码。 - 1：A呼叫X时，被叫B显示的号码是A。 - 2：B呼叫X时，被叫A显示的号码是B。 - 3：A呼叫X时，被叫B显示的号码是A；B呼叫X时，被叫A显示的号码是B。 隐私号短信场景：是否在短信内容里携带主叫号码。 - 0：短信内容中不做处理。 - 1：A给X发短信，短信内容结束增加\[From{A号码}\]，B给X发送不增加。 - 2：B给X发短信，短信内容结束增加\[From{B号码}\]，A给X发送不增加。 - 3：A给X发短信，短信内容结束增加\[From{A号码}\]；B给X发短信，短信内容结束增加\[From{B号码}\]。 如果不携带该参数，系统默认该参数为0。 说明： 由于运营商管控，当前平台要求该参数必须设置为0，否则绑定会失败、呼叫会被运营商拦截。 | | backupNumFlag | 否 | String(枚举) | 是否需要支持备用X号码。 参数设置为"true"时，当和A、B绑定的X号码（"relationNum"）被运营商限呼后，A/B号码再次呼叫X号码时，会使用备用X号码呼出。 - false：表示不支持。 - true：表示支持。 如果不携带该参数，系统默认不支持。 说明： - 该参数的使用场景请联系华为云客服确认。 - 使用该参数时，请注意以下问题： - 建议收到"X号码被限呼"的X号码状态通知时再通过[AXB模式绑定信息修改接口](https://support.huaweicloud.com/api-PrivateNumber/privatenumber_02_0004.html)开启该功能。 - X号码数量不足时，分配备用X号码会失败，建议增加X号码数量。 | | userData | 否 | String(1-256) | 用户自定义数据。 - 不允许携带以下字符："\^"，"{"，"}"。 - 不允许包含中文字符，如果包含中文字符请采用Base64编码。 说明： 若在设置绑定关系时携带该参数，绑定关系对应的呼叫、话单和短信通知消息中也会携带该参数。 | | carrier | 否 | Integer | 指定运营商，由隐私保护通话平台从客户已申请到的X号码中选择指定运营商的号码进行绑定。 取值范围： 1：指定中国移动的业务号码进行绑定。 2：指定中国联通的业务号码进行绑定。 3：指定中国电信的业务号码进行绑定。 4：指定中国广电的业务号码进行绑定。 注意：当指定了relationNum时，此参数不生效。 | | backupRelationNum | 否 | String(1-32) | 备用X号码。 说明： 使用备用X号码呼叫时，建议将主备两个号码同时通知给A/B号码，防止A/B号码看到陌生号码拒接。 | 表4ApiPlayInfo定义 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | callerHintTone | 否 | String(0-128) | 设置A拨打X号码时的通话前等待音，填写为放音文件名，可在[放音文件管理](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)页面查看。 不携带该参数时A会听到B的回铃音。 | | calleeHintTone | 否 | String(0-128) | 设置B拨打X号码时的通话前等待音，填写为放音文件名，可在[放音文件管理](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)页面查看。 不携带该参数时B会听到A的回铃音。 | #### 响应参数 表5响应结果参数 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | resultcode | 是 | String(1-32) | 请求返回的结果码。 | | resultdesc | 是 | String(1-256) | 操作结果描述。 | | subscriptionId | 否 | String(1-64) | 绑定ID，唯一标识一组绑定关系。成功响应时必定返回。请记录该ID用于后续接口调用。 | | relationNum | 否 | String(1-32) | 绑定的X号码。 成功响应时必定返回。 | | callDirection | 否 | Integer | 绑定关系允许的呼叫方向，取值含义参见请求参数。 成功响应时必定返回。 | | duration | 否 | Integer | 绑定关系保持时间，单位为秒，0表示永不过期。 成功响应时必定返回。 | | maxDuration | 否 | Integer | 允许单次通话进行的最长时间，通话时间从被叫接通的时刻开始计算，0表示系统不主动结束通话。 成功响应时必定返回。 | | userData | 否 | String(1-256) | 用户自定义数据。 当请求中携带且成功响应时必定返回。 | | backupRelationNum | 否 | String(1-32) | 备用X号码。 当"backupNumFlag"为"true"且分配了备用X号码时返回。 说明： 使用备用X号码呼叫时，建议将主备两个号码同时通知给A/B号码，防止A/B号码看到陌生号码拒接。 | #### 结果码说明 表6响应结果码 | 响应码 | 结果码 | 英文描述 | 中文描述 | 处理方法 | |:---|:---|:---|:---|:---| | 200 | 0 | Success. | 成功。 | - | | 400 | 1023006 | Authorization not contained in the HTTP header. | HTTP消息头未找到Authorization字段。 | 请检查HTTP消息头中是否携带了Authorization字段。 | | 400 | 1023007 | realm not contained in Authorization. | Authorization字段中未找到realm属性。 | 请检查Authorization字段中的是否携带了realm属性。 | | 400 | 1023008 | profile not contained in Authorization. | Authorization字段中未找到profile属性。 | 请检查Authorization字段中的是否携带了profile属性。 | | 400 | 1023009 | The value of realm in Authorization must be SDP. | Authorization中realm属性值应该为"SDP"。 | 请检查Authorization字段中的realm属性值是否为"SDP"。 | | 400 | 1023010 | The value of profile in Authorization must be UsernameToken. | Authorization中profile属性值应该为"UsernameToken"。 | 请检查Authorization字段中的profile属性值是否为"UsernameToken"。 | | 400 | 1023011 | The value of type in Authorization must be app_key. | Authorization中type属性值应该为"Appkey"。 | 请检查Authorization字段中的type属性值是否为"Appkey"。 | | 400 | 1023012 | type not contained in Authorization. | Authorization字段中未找到type属性。 | 请检查Authorization字段中是否携带了type属性。 | | 400 | 1023033 | HTTP header not found X-AKSK field. | HTTP头未找到X-AKSK字段。 | 请检查HTTP消息头中是否携带了X-AKSK字段。 | | 400 | 1023034 | UserName not contained in X-AKSK. | X-AKSK字段中未找到UserName属性。 | 请检查X-AKSK字段中的是否携带了Username属性。 | | 400 | 1023035 | Nonce not contained in X-AKSK. | X-AKSK字段中未找到Nonce属性。 | 请检查X-AKSK字段中的是否携带了Nonce属性。 | | 400 | 1023036 | Created not contained in X-AKSK. | X-AKSK字段中未找到Created属性。 | 请检查X-AKSK字段中的是否携带了Created属性。 | | 400 | 1023037 | PasswordDigest not contained in X-AKSK. | X-AKSK字段中未找到PasswordDigest属性。 | 请检查X-AKSK字段中的是否携带了PasswordDigest属性。 | | 400 | 1023038 | UsernameToken not contained in X-AKSK. | X-AKSK中没有携带UsernameToken。 | 请检查X-AKSK字段中的是否携带了UsernameToken属性。 | | 401 | 1010010 | Invalid digest. | PasswordDigest校验失败。 | 请检查PasswordDigest字段填写是否正确。 | | 401 | 1010013 | Time out limit. | 时间超出限制。 | 请确认X-AKSK鉴权时，生成随机数的时间与发送请求时的本地时间不能相差太大（具体差值请与管理员确认）。 | | 403 | 1010002 | Invalid request. | 无效请求。 | 参考各接口参数说明，检查请求携带的参数格式是否正确，如以下参数格式问题： - **绑定接口**填写的号码参数需为全局号码格式，如+86138\*\*\*\*0001或+8675528\*\*\*\*01； - 放音文件需上传通过审核才可通过接口调用，[点击查看如何上传审核](https://support.huaweicloud.com/usermanual-PrivateNumber/pn_um_05.html)。 - 参考接口参数说明，检查是否携带了不能同时携带的参数； - 参数长度或格式是否错误。 | | 403 | 1010003 | Invalid app_key. | 无效的app_key。 | 请检查请求携带的app_key填写是否正确。 | | 403 | 1010008 | The status of the app_key is unavailable. | app_key状态异常。 | 请检查请求携带的app_key所属应用状态是否正常。应用状态可登录控制台后在"应用管理"界面查看。 | | 403 | 1010010 | The flow control upper limit is reached on the platform. | 平台达到系统流控上限。 | 请稍等一分钟后再试。 | | 403 | 1010029 | The subscriber status is frozen. | 用户账号已冻结。 | - 查看账户是否欠费。如欠费需充值后才能继续使用。 - 若未欠费，请联系华为云客服处理。 | | 403 | 1010040 | The app_key is not allowed to invoke the API. | app_key没有调用本API的权限。 | 调用的接口和app_key所属的应用模式不一致。如添加应用时选择的AXB模式的应用，调用接口时只能调用AXB模式的接口，不能调用其他模式的接口。 | | 403 | 1012001 | Resource of number is not to be applied. | 资源未申请。 | 携带的app_key和X号码没有绑定关系，请检查携带的X号码是否属于该应用。 | | 403 | 1012007 | The record does not exist. | 记录不存在。 | 指定的X号码不存在，请检查relationNum参数的填写是否正确。 | | 403 | 1012008 | Insufficient number of resources | 资源不足。 | 没有可分配的X号码，请申请新的号码资源或修改areaCode的值。[点击查看处理方法](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_00028_2.html) | | 403 | 1012009 | Maximum number of resources has been exceeded | 指定的X号码的绑定数量已达到上限。 | 一个X号码只能同时绑定5000对关系。请修改relationNum的值，或者解除指定的X号码上的部分绑定关系。 | | 403 | 1012010 | The number $ has been bound. | 绑定关系已存在。 | 出现该错误码表示调用[AXB模式绑定接口](https://support.huaweicloud.com/api-PrivateNumber/privatenumber_02_0002.html)时携带的X号码（relationNum）和A号码（callerNum）或B号码（calleeNum）已存在绑定关系，可确认后更换其他X号码进行绑定。 | | 403 | 1012012 | Application does not open recording function. | 应用未开启录音功能。 | 请确认app_key所属的应用是否开启了录音功能，[点击查看如何开启录音功能](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_00023_10.html)。 | | 403 | 1012102 | The number status is abnormal. | 号码状态异常。 | 出现该错误码表示调用接口时指定的X号码因投诉或号码状态异常被隐私保护通话平台加入了黑名单，请查看订购号码时填写的邮箱是否有业务下线通知邮件，如果没有，请拨打400电话联系华为云客服处理。 | | 403 | 1020166 | The app client ip is not in ip white list. | 对端app IP不在白名单列表中。 | 联系管理员检查IP白名单是否配置正确。 | | 403 | 1020176 | Authentication failed, try again later | 鉴权失败，稍后重试 | IP因鉴权失败次数过多导致被拉黑，请30分钟后重试，或联系管理员放通该IP。 | | 403 | 1020179 | Application does not enable sms function. | 应用未开启短信功能。 | 请确认app_key所属的应用是否开启了短信功能，[点击查看如何开启短信功能](https://support.huaweicloud.com/PrivateNumber_faq/pn_faq_00023_11.html)。 | | 403 | 1020178 | The transparent mode is not allowed. | 不允许显示真实主叫号码。 | 您的应用不支持显示真实主叫号码，请修改displayNumMode参数的取值为"0"（显示X号码）后再次绑定。 | | 500 | 1010001 | Internal system error. | 系统错误。 | 请联系客服处理。 | | 500 | 1023001 | Internal error. | 内部错误。 | 请联系客服处理。 | | 500 | 1023002 | Response timeout. | 响应超时。 | 重新发送一次请求，若依然返回响应超时，请联系管理员处理。 | #### 接口示例 接口示例仅供参考，请以实际消息为准。 - 请求示例 ``` POST /rest/caas/relationnumber/partners/v1.0 HTTP1.1 content-type: application/json;charset=UTF-8 authorization: AKSK realm="SDP",profile="UsernameToken",type="Appkey" x-aksk: UsernameToken Username="************",PasswordDigest="*************",Nonce="ac1c911c4792492687f8f6b2264a491e",Created="2018-05-26T00:35:30Z" content-length:xx { "callerNum":"+86138****0021", "relationNum":"+86138****6666", "calleeNum":"+86138****0023", "callDirection":0, "duration":0, "preVoice": { "callerHintTone": "callerHintTone.wav", "calleeHintTone": "calleeHintTone.wav" }, "maxDuration":0 } ``` - 响应示例 ``` HTTP/1.1 200 OK Content-Type: application/json;charset=utf-8 Content-Length: xx { "resultcode":"0", "resultdesc":"Success" , "subscriptionId":"****", "relationNum":"+86138****6666", "callDirection":0, "duration":0, "maxDuration":0 } ```