查询优惠券列表
功能介绍
伙伴可以查询自身的优惠券信息。
伙伴登录伙伴中心查询已发放代金券列表请参见这里，查看已下发代金券的内容。
说明：
- 目前国际站没有现金券和折扣券。
- 不返回超过已失效一年时间的代金券/折扣券信息。
- 当券的失效时间小于当前时间时，券将不再有效，此时券的状态称之为已失效。
接口约束
该接口使用合作伙伴的AK/SK或者Token调用时，只能查询合作伙伴或伙伴名下云经销商的优惠券列表信息。若是查询伙伴名下客户的优惠券，需要置换子客户token，置换前需伙伴申请客户授权或客户给伙伴创建委托。
调试
您可以在API Explorer中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。
URI
GET /v2/promotions/benefits/coupons
参数说明请参见下表。
|
参数 |
是否必选 |
参数类型 |
取值范围 |
描述 |
|---|---|---|---|---|
|
coupon_id |
否 |
String |
最大长度：64 |
优惠券ID。 此参数不携带或携带值为空时，不作为筛选条件。 |
|
order_id |
否 |
String |
最大长度：64 |
订单ID。 此参数不携带或携带值为空时，不作为筛选条件。 |
|
promotion_plan_id |
否 |
String |
最大长度：64 |
促销计划ID。 此参数不携带或携带值为空时，不作为筛选条件。 |
|
coupon_type |
否 |
Integer |
[1-4] |
优惠券类型：
此参数不携带或携带值为空或携带值为null时，不作为筛选条件；不支持携带值为空串。 |
|
status |
否 |
Integer |
[1-5] |
客户优惠券实例状态：
此参数不携带或携带值为空时，不作为筛选条件。 |
|
active_start_time |
否 |
String |
最大长度：64 |
激活开始时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。 此参数不携带或携带值为空时，不作为筛选条件；不支持携带值为空串或携带值为null。 |
|
active_end_time |
否 |
String |
最大长度：64 |
激活结束时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。其中，HH范围是0～23，mm和ss范围是0～59。 此参数不携带或携带值为空时，不作为筛选条件；不支持携带值为空串或携带值为null。 |
|
offset |
否 |
Integer |
[0-最大整数] |
偏移量，从0开始。默认值为0。 说明：
offset用于分页处理，如不涉及分页，请使用默认值0。offset表示相对于满足条件的第一个数据的偏移量。如offset = 1，则返回满足条件的第二个数据至最后一个数据。 示例1，满足查询条件的结果共10条数据，limit取值为10，offset取值为1，则返回的数据为2~10，第一条数据不返回。 示例2，查询总数20条，期望每页返回10条数据，则获取第一页数据，入参offset填写0，limit填写10；获取第二页数据，入参offset填写10，limit填写10。 |
|
limit |
否 |
Integer |
[1-100] |
查询的优惠券数量，默认值为10。 |
|
source_id |
否 |
String |
最大长度：255 |
发券来源，如果是合作伙伴发送的券，此处为伙伴ID。 如果需要查询某个伙伴发放的券，可以在此处输入该伙伴ID。 此参数不携带或携带值为空或携带值为null时，不作为筛选条件；携带值为空串时，作为筛选条件。 |
请求消息
请求参数
无。
请求示例
GET https://bss-intl.myhuaweicloud.com/v2/promotions/benefits/coupons HTTP/1.1 Content-Type: application/json X-Auth-Token：MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ
响应消息
响应参数
|
参数 |
参数类型 |
取值范围 |
描述 |
|---|---|---|---|
|
error_code |
String |
最大长度：16 |
状态码。 具体请参见状态码。 |
|
error_msg |
String |
最大长度：1024 |
错误描述信息。 |
|
count |
Integer |
- |
符合查询条件的总条数。 |
|
user_coupons |
List<IQueryUserCouponsResult> |
- |
优惠券记录。 具体请参见表2。 |
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
coupon_id |
String |
优惠券实例ID。 |
|
coupon_code |
String |
优惠券编码。 |
|
status |
Integer |
优惠券状态：
|
|
customer_id |
String |
客户账号ID。 |
|
coupon_type |
Integer |
优惠券类型：
|
|
measure_id |
Integer |
度量单位。 1：元 |
|
face_value |
Double |
优惠券金额。 |
|
valid_time |
String |
生效时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。 |
|
expire_time |
String |
失效时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。 |
|
order_id |
String |
订单ID。 说明：
优惠券被多次交易抵扣场景下，返回每次抵扣订单号用英文分号分割，同一次交易抵扣场景下，如果是合并支付，会存在多个订单号，用英文逗号分割。举例：CS1904011928GIBHC1,CS1904011928GIBHC2,CS1904011928GIBHC3;CS1904011928GIBHCB。 存在多个订单号时，不表示全部订单号都使用了该优惠券。 |
|
promotion_plan_id |
String |
促销计划ID。 |
|
plan_name |
String |
促销计划名称。 |
|
plan_desc |
String |
促销计划描述。 |
|
media_type |
Integer |
介质类型。
|
|
fetch_method |
Integer |
获取方式：
|
|
use_limits |
List<ICouponUseLimitInfoV2> |
优惠券使用限制。 具体请参见表3。 |
|
active_time |
String |
激活时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。 |
|
reserve_time |
String |
使用时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。 |
|
promotion_id |
String |
促销ID。 |
|
create_time |
String |
创建时间。 UTC时间，格式：yyyy-MM-dd'T'HH:mm:ss'Z'，如“2019-05-06T08:05:01Z”。 |
|
coupon_version |
Integer |
优惠券版本：
|
|
balance |
Double |
优惠券余额。单位：元。 |
|
lock_order_id |
String |
锁定优惠券的订单ID。 |
|
coupon_usage |
String |
优惠券用途。 |
|
is_frozen |
String |
优惠券是否冻结：
|
|
currency |
String |
币种。 USD：美元 |
|
extend_param1 |
String |
扩展字段。 |
|
source_id |
String |
发券来源。
|
|
参数 |
参数类型 |
描述 |
|---|---|---|
|
use_limiti_info_id |
String |
使用限制ID，主键。 |
|
limit_key |
String |
折扣限制，key的取值请参考表4。 |
|
value1 |
String |
value1。 |
|
value2 |
String |
value2。 |
|
value_unit |
String |
value单位。 |
|
limit_type |
String |
限制类型。 |
|
promotion_plan_id |
String |
促销计划ID。 |
|
key值 |
含义 |
说明 |
备注 |
|---|---|---|---|
|
baseValue |
订单金额 |
value1中保存订单金额下限，value2中保存订单金额上限。 |
支持代金券，现金券，折扣券 |
|
serviceType |
云服务类型 |
只有value1有效，具体的云服务类型请调用查询云服务类型列表接口获取。 |
支持代金券，现金券，折扣券 |
|
regionCode |
区域编码 |
value2中保存区域名称，value1中保存区域编码。 |
支持代金券，现金券，折扣券 |
|
productId |
产品ID |
可以包含多个产品ID，英文逗号分隔。 |
支持代金券，现金券，折扣券 |
|
subscribeType |
订购类型 |
只有value1有效。取值为：
|
支持代金券，现金券，折扣券 |
|
firstOrderInService |
首次购买限制 |
只有value1有效。 |
支持代金券，现金券，折扣券 |
|
cycleNum |
周期数量 |
只有value1有效。 |
支持代金券，现金券，折扣券 |
|
cycleType |
适用周期类型 |
|
支持代金券，现金券，折扣券，折扣券仅支持包年/包月 |
|
simultaneousUseWithEmpowerDiscount |
代金券是否可以和授权折扣同享 |
代金券是否可以和授权折扣（包括商务折扣和伙伴授予折扣）同享。
|
支持代金券，现金券，折扣券，折扣券只能使用0。 |
|
usageTimes |
是否支持多次使用 |
是否支持多次使用，值保存在value1中。取值为：
|
|
|
isOnlyForStrictSelected |
是否只能用于云商店严选产品 |
是否只能用于云商店严选产品，值保存在value1中。取值为：
如果没有这个限制，等同于0；该限制只是用于现金券。 |
支持现金券 |
|
isRebate |
是否参与伙伴激励返点 |
是否参与伙伴激励返点，值保存在value1中。取值为：
该限制只是用于现金券。 |
支持现金券 |
|
serviceTypeBlackList |
服务类型黑名单 |
服务类型黑名单，value1中保存服务类型编码；该限制只是用于现金券。 |
支持现金券 |
|
minConsumeDiscount |
最低客户消费折扣 |
最低客户消费折扣，值保存在value1中。取值为0-1之间（不包括0和1）。 |
支持代金券、现金券 |
|
isForAnnualContracts |
是否只能用于包年/包月1年的订单 |
是否只能用于包年/包月1年的订单。取值为：
|
支持代金券、折扣券 |
|
simultaneousUseWithPromotionProduct |
是否可以和促销产品同享 |
代金券是否可以和促销产品同享，值保存在value1中。取值为：
|
支持代金券/折扣券 |
|
simultaneousUseWithPromotionDiscount |
是否可以和促销折扣同享 |
代金券是否可以和促销折扣同享，值保存在value1中。取值为：
|
支持代金券 |
|
simultaneousUseWithDiscountCoupon |
是否可以和折扣券同享 |
代金券是否可以和折扣券同享，值保存在value1中。取值为：
|
支持代金券 |
响应示例
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: length
Date: response time
{
"count": "1",
"user_coupons": [
{
"coupon_id": "CP19092406014086E3",
"coupon_code": "CP19092406014086E3",
"status": "2",
"customer_id": "c9e731c4663646988ef4cdb3122837b6",
"coupon_type": "1",
"measure_id": "1",
"face_value": "100",
"valid_time": "2019-09-16T16:00:00Z",
"expire_time": "2019-09-16T16:00:00Z",
"order_id": "CS1904011928GIBHC",
"promotion_plan_id": "promotionPlanId5322584",
"plan_name": "532美元优惠券name",
"plan_desc": "532美元优惠券desc",
"media_type": "1",
"fetch_method": "1",
"use_limits": [
{
"use_limiti_info_id": "CP19092406014086E3",
"limit_key": "simultaneousUseWithDiscountCoupon",
"value1": "1",
"value2": "",
"value_unit": "",
"limit_type": "=",
"promotion_plan_id": "promotionPlanId5322584"
}
],
"active_time": "2019-09-16T16:00:00Z",
"reserve_time": "2019-09-16T16:00:00Z",
"promotion_id": "promotionPlanId5322584",
"create_time": "2019-09-16T16:00:00Z",
"coupon_version": "2",
"balance": "100",
"lock_order_id": "CS1904011928GIBHC",
"coupon_usage": "170719190603338056FEH60VIRWEP",
"is_frozen": "0",
"currency": "USD",
"extend_param1": "2019091702368200",
"source_id": "c9e731c4663646988ef4cdb3122837b6"
}
]
}
