X号码状态通知接口

接口功能

X号码状态变化时，隐私保护通话平台会向客户推送通知。号码状态变化包括：

因号码删除、欠费、停机，号码状态从可用变为不可用；
号码状态从不可用恢复为可用；
不可用原因变化，例如从欠费变为停机。

请求方向

隐私保护通话平台（服务端） → 客户服务器（客户端）

使用说明

前提条件
 客户添加应用时需启用推送X号码状态功能并设置呼叫状态接收地址或X号码状态接收地址，并确保提供的地址能够正常处理隐私保护通话平台发送的通知消息。
注：若需单独接收X号码状态通知，需填写X号码状态接收地址。若呼叫状态接收地址和X号码状态接收地址都填写了，隐私保护通话平台会向呼叫状态接收地址推送呼叫事件通知，向X号码状态接收地址推送X号码状态通知。
使用限制
 业务平台推送呼叫状态给开发者应用，仅支持POST方式。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限，具体权限要求请参见权限管理。

接口类型

表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时携带。

表5 numInfo定义
参数名称	是否必须	参数类型	说明
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"}]}