按需使用量推送（新）
接口说明
用户在云商店开通按需资源并产生使用量后，商家需通过此接口返回用户的实际使用量话单，云商店获取话单后根据使用量计费并对用户扣费。
URI
POST https://mkt.myhuaweicloud.com/api/mkp-openapi-public/global/v1/isv/usage-data
“mkt.myhuaweicloud.com”域名不可用时请使用“mkt.myhuaweicloud.cn”进行重试。
① 按需计量商品购买和使用流程
② 用完即停套餐包商品购买和使用流程
请求消息
请求参数说明请参见下表：
请求方法：POST
参数 |
是否必选 |
类型 |
最大字符长度 |
说明 |
|---|---|---|---|---|
signature |
是 |
String |
1000 |
@Header 接口签名(base64(hmacSHA256(商家对接秘钥,ts={ts}&nonce={nonce}&body={body}))) 此处body按自然排序后参与签名 |
ts |
是 |
String |
20 |
@Header 接口请求时的unix时间戳(毫秒数) |
nonce |
是 |
String |
64 |
@Header 安全随机数 |
usage_records |
是 |
List<UsagePushData> |
1000 |
业务使用量纪录集合，UsagePushData个数不得超过1000。 |
参数 |
是否必选 |
参数类型 |
最大字符长度 |
描述 |
|---|---|---|---|---|
instance_id |
是 |
String |
64 |
按需实例ID（注意：使用按需接口返回的） |
record_time |
是 |
String |
17 |
使用量记录生成时间（UTC），格式为： yyyyMMdd'T'HHmmss'Z' |
begin_time |
是 |
String |
17 |
计量开始时间（UTC），格式为： yyyyMMdd'T'HHmmss'Z' |
end_time |
是 |
String |
17 |
计量结束时间（UTC），格式为： yyyyMMdd'T'HHmmss'Z' |
usage_value |
是 |
Double(12,4) |
20 |
使用量具体值，最多支持4位有效小数，需为大于0的数值 |
metering_sn |
是 |
String |
64 |
商家话单记录唯一性标识，建议是随机码 |
relate_pkg_instance |
否 |
String |
64 |
用完即停套餐包场景下话单必传，需要传递当前用量对应的扣减包实例ID |
请求消息示例：
Post {domain}/api/mkp-openapi-public/global/v1/isv/usage-data
Content-Type:application/json
nonce: 6c63c221-1f6b-4141-8ff4-22f5dfe82b65
ts: 1709690865879
signature: gikLsIgimIscagwSamClFJ1CFT4QprHSDHW…
{
"usage_records": [
{
"instance_id": "7f141bf1-aec8-4859-8323-fb3a8ad50721",
"record_time": "20220809T091000Z",
"begin_time": "20220809T080000Z",
"end_time": "20220809T090000Z",
"usage_value": "99",
"metering_sn": "6c75c177b5fe4b8cbb6fc2aa33facfcd"
},
{
"instance_id": "7f141bf1-aec8-4859-8323-fb3a8ad50721",
"record_time": "20220809T091000Z",
"begin_time": "20220809T080000Z",
"end_time": "20220809T090000Z",
"usage_value": "999",
"metering_sn": "6c75c177b5fe4b8cbb6fc2aa33facfcb"
}
]
}
1、接口调用上传时，如果话单数据异常，不会在接口层进行报错；后台定时任务会对上传的数据进行校验和处理，生成可以使用的话单数据。如果后台数据处理失败，需要商家重新进行上报。
异常数据可以在 “卖家中心＞交易管理＞话单管理” 进行查看！
2、话单上报周期要求：
- 按小时计费
需要至少每小时上报一次话单数据，且最好在消费时间下一个小时的0-15分钟内完成上报，譬如，用户消费时间在13:25，最好在14:00-14:15内上报，这样能及时给用户扣费，否则就会出现扣费延迟，如果无法实现实时上报，需要在2小时完成上报
- 按天计费
推荐每小时将已经明确的用量话单上报到云商店，如果必须每天汇总上报一次，需要保证必须在次日的00:00-00:15内完成上报，最大不能超过01:00，否则用户的扣费会延迟到下一天
3、话单数据上报要求：
- 资源未关闭：
- 话单开始时间（begin_time）≥资源开始时间
- 话单开始时间（begin_time）≤话单结束时间（end_time）≤ 话单上报时间
- 资源关闭后：
- 话单结束时间（end_time）≤资源关闭时间
4、话单上报中的时间为UTC 时间，与北京时间相差 8 小时；
5、同一个记录的时间，即begin_time 和end_time 时间都一致的情况下，如多次上报记录，会被识别为重复话单，只会处理第一条数据，一旦话单采集后形成正式账单将无法逆向错误话单（话单采集时间：按天计费为每天凌晨1点，按小时计费为每小时15分）。
重复话单将视为异常，异常数据可以在 “卖家中心＞交易管理＞话单管理” 进行查看！
6、使用量推送接口使用按需交易中生成的按需实例ID，不能使用套餐包返回的实例ID。
响应消息
响应参数说明请参见下表：
参数 |
是否必选 |
类型 |
最大字符长度 |
说明 |
|---|---|---|---|---|
error_code |
M |
String |
6 |
调用结果码。 具体请参见调用结果码说明。 |
error_msg |
O |
String |
255 |
调用结果描述。 |
data |
O |
AbnormalUsageDataInfo |
返回异常话单错误信息 |
参数 |
是否必选 |
参数类型 |
最大字符长度 |
描述 |
|---|---|---|---|---|
abnormal_usage_data |
是 |
List<AbnormalUsageData> |
1000 |
异常话单列表 |
参数 |
是否必选 |
参数类型 |
最大字符长度 |
描述 |
|---|---|---|---|---|
metering_sn |
是 |
String |
64 |
商家话单记录唯一性标识 |
error_code |
是 |
String |
16 |
话单级错误码 001：实例不存在； 002：时间格式异常； 003：用量异常； 004：缺少话单唯一标识； 005：话单唯一标识重复 006：实例对应的商品已退市 007：话单时间已过期 009：实例与商家不匹配 010：话单重复 011：话单时间范围无效 012：实例非按需资源 013：实例资源状态异常 014：实例资源已关闭 015：话单开始时间小于资源开通时间 016：实例资源开通中 017：用完即停场景下，relate_pkg_instance为空 018：用完即停场景下，relate_pkg_instance不合法，实例不存在或与instance_id不匹配 |
error_msg |
是 |
String |
255 |
话单错误描述 |
错误码：
http状态码 |
error_code |
error_msg |
描述 |
|---|---|---|---|
200 |
MKT.0000 |
Success |
请求成功 |
500 |
94060001 |
System error! |
其它服务内部错误 |
401 |
94060002 |
Auth failed! |
输入参数校验失败 参数范围超限，非法值或格式错误 |
400 |
94060004 |
Param invalid |
参数无效 输入非接口定义的参数，多参数或少必选参数 比如：传递非法数值、没有实例id等 |
400 |
94060005 |
Time format error |
时间格式错误 |
400 |
94060006 |
TimeStamp invalid |
时间戳无效 |
401 |
94060007 |
Signature invalid |
签名校验失败 |
400 |
94060008 |
Replay error |
请求重放错误 |
500 |
94060009 |
Failed to report usage data |
话单调用失败 |
401 |
94060010 |
isv status invalid |
商家状态无效 |
200 |
94060999 |
Failed |
该错误码时，会返回话单级错误信息，详见响应示例 |
当您调用API时，如果遇到“APIGW”开头的错误码，请参见API网关错误码进行处理。
响应消息示例：
{
"error_code":"MKT.0000",
"error_msg":"Success"
}
{
"error_code": "94060999",
"error_msg": "Failed",
"data": {
"abnormal_usage_data": [
{
"error_code": "005",
"error_msg": "METERING_SN_DUPLICATE",
"metering_sn": "6c75c177b5fe4b8cbb6fc2aa33facfcb"
}
]
}
}
