华为云 BSS 接口实战：代金券余额与到期时间为什么必须读 balance 而不是 face_value

一、问题：为什么查了券还是不知道能用多少钱

用 AK/SK 调华为云 BSS 接口查代金券，很多人会直接读返回里的 face_value。这个字段是券的面值，不是你能花的钱。一张面值 200 元的「华为云体验代金券」，如果已经抵扣过一部分，face_value 仍然是 200，而真正剩下的钱在 balance 字段里。

笔者实测的两个账号就是活例子：185 账号的券 CP261016212823G6TR 面值 200 元、balance 只有 136.62 元；139 账号的券 CP2610181838307RII 面值 200 元、balance 197.35 元。如果按面值估算可用额度，会高估 60 元以上，足以让一次续费决策出错。

二、第一个坑：路径不是 /v2/promotions/coupons

公开资料里（包括不少搜索结果）把代金券查询接口写成：

GET https://bss.myhuaweicloud.com/v2/promotions/coupons

这个路径实测不可用，返回：

HTTP 404
{"error_code":"APIGW.0101",
 "error_msg":"The API does not exist or has not been published in the environment"}

正确的是 benefits/coupons：

GET https://bss.myhuaweicloud.com/v2/promotions/benefits/coupons
    ?limit=50&offset=0&coupon_type=1&status=2

这个错误路径会浪费不少时间：它返回的是"接口不存在"而不是"参数错误"，很容易让人以为是 AK/SK 或区域配错了，从而往错误方向排查。

三、第二个坑：BSS 是全局服务，签名要带 query string

BSS 与 VPC/ECS 不同，它是全局服务，host 里没有 region：

host = bss.myhuaweicloud.com

同时 BSS 请求带查询串，因此 canonical request 必须包含排序并 URI 编码后的 query string。这一步是区域类服务的签名器通常不做的。构造方式：

canonical_request = METHOD + "\n" +
                    canonical_uri(末尾补 /) + "\n" +
                    canonical_query(按 key 排序, RFC3986 编码) + "\n" +
                    canonical_headers + "\n" +
                    signed_headers + "\n" +
                    hex(sha256(body))

string_to_sign = "SDK-HMAC-SHA256" + "\n" +
                 sdk_date + "\n" +
                 hex(sha256(canonical_request))

signature = hex(hmac_sha256(SK, string_to_sign))

两个容易漏的细节：canonical_uri 末尾要补 /，否则签名不匹配；空 body 的 payload hash 是 sha256("") 的 hex，不能省略。

四、状态与类型要循环查

一次请求只返回一种状态，status 取值含义：

• 1 = 未生效
• 2 = 可使用
• 3 = 已使用
• 4 = 已过期
• 5 = 已回收

coupon_type：1 = 代金券，2 = 折扣券，4 = 现金券。要盘点全部券就得循环 status 1..5。另外 is_frozen 是字符串 "0"/"1"，判断时要按字符串比，不能当布尔用。

五、顺手可查的现金账户余额

另一个常用接口：

GET https://bss.myhuaweicloud.com/v2/accounts/customer-accounts/balances

返回 account_balances[]。注意一个反直觉的事实：很多账号的现金账户 amount 是 0，价值全在代金券里。所以判断"账上的钱够不够续费"时，看的应该是代金券余额合计，而不是现金账户。

六、小结

1. 查代金券用 /v2/promotions/benefits/coupons，不是 /v2/promotions/coupons；
2. 可用额度读 balance，面值读 face_value，两者都要看；
3. BSS 是全局服务，canonical request 必须带排序编码后的 query string，URI 末尾补 /；
4. status 1-5 与 coupon_type 1/2/4 要循环查，才能盘点完整；
5. 现金账户经常为 0，别把它当成总资产。