# X号码状态通知接口 #### 接口功能 X号码状态变化时，隐私保护通话平台会向客户推送通知。号码状态变化包括： - 因号码删除、欠费、停机，号码状态从可用变为不可用； - 号码状态从不可用恢复为可用； - 不可用原因变化，例如从欠费变为停机。 #### 请求方向 隐私保护通话平台（客户端） → 客户服务器（服务端） #### 使用说明 - 前提条件 客户添加应用时需设置呼叫状态接收地址并启用推送X号码状态功能，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。 注：若需单独接收X号码状态通知，需填写**X号码状态接收地址。** 若**呼叫状态接收地址** 和**X号码状态接收地址** 都填写了，隐私保护通话平台会向**呼叫状态接收地址** 推送呼叫事件通知，向**X号码状态接收地址**推送X号码状态通知。 - 使用限制 业务平台推送呼叫状态给开发者应用，仅支持POST方式。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见[权限管理](https://support.huaweicloud.com/productdesc-PrivateNumber/privatenumber_permissions.html)。 #### 接口类型 表1接口类型说明 | 请求方法 | POST | |---|---| | **访问URI** | 客户添加应用时填写的**呼叫状态接收地址** /**X号码状态接收地址** | | **通信协议** | HTTPS/HTTP | #### 请求参数 表2请求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。不同编程语言中将UTC时间戳转换为普通时间时使用的格式不同，部分语言可参考[表3]。 | 表3不同编程语言的时间格式 | 编程语言 | 时间格式 | |:---|:---| | 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()转换后的时间格式去除毫秒后即为本接口要求的时间格式。 | 表4请求Body参数说明 | 参数名称 | 是否必选 | 参数类型 | 说明 | |:---|:---|:---|:---| | eventType | 是 | String(枚举) | **参数解释：** 通知的事件类型。 **约束限制：** 不涉及。 **取值范围：** numStatus：X号码状态变化。 **默认取值：** 不涉及。 | | numInfo | 否 | [numInfo \[1-100\]] | X号码状态变化事件的信息，参数取值为列表，最大100条。 当eventType参数为numStatus时携带。 | 表5numInfo定义 | 参数名称 | 是否必须 | 参数类型 | 说明 | |:---|:---|:---|:---| | number | 是 | String | 状态变化的X号码。 | | status | 是 | String | **参数解释：** 号码状态。 **约束限制：** 不涉及。 **取值范围：** - 5：正常，该状态下业务无影响。 - 9：暂停，该状态下绑定、呼叫和短信都不可用。 - 10：不可用，该状态下绑定、呼叫和短信都不可用。 - 11：冻结绑定，该状态下号码不可新增绑定关系，但已存在的绑定关系的呼叫和短信业务不受影响。 **默认取值：** 不涉及。 | | cause | 否 | String | 号码不可用原因。仅status为不可用时携带。 - 1：号码已删除 - 2：欠费 - 3：停机 - 5：X号码被运营商限呼 - 6：X号码限呼恢复 - 7：X号码开通了无条件前转业务 - 8：X号码开通了无应答前转业务 - 9：X号码开通了被叫忙前转业务 | 接口示例 ``` POST /Xnumber/status HTTP/1.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 {"eventType":"numStatus","numInfo":[{"number":"+86156****0000","status":"9"}]} ``` #### 响应参数 客户服务器接收到隐私保护通话平台的X号码状态变化通知后，返回的响应消息。 接口示例 ``` HTTP/1.1 200 OK ```