本地生活商品
商户调用该接口，可分页查询用户在指定商家下的所有凭证信息，并检查凭证当前是否可用。
注意：
如果未传入shopid，则会跳过shopid判断，只进行当前时间的校验。
公共请求参数
业务请求参数
page_num｜分页查询页码必选number[1,99999]
【描述】分页查询页码
【注意事项】必须为大于0的整数
【示例值】1
page_size｜分页查询单页数据条数必选number[1,20]
【描述】分页查询单页数据条数
【注意事项】1.必须为大于0的整数 2.每页最大值为20
【示例值】20
以下参数 二选一 传入
user_id｜支付宝用户idstring[1,32]
【描述】出资的支付宝用户id
新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088512417841101
open_id｜支付宝用户开放idstring[1,128]
【描述】支付宝用户openid 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
shop_id｜支付宝门店id可选string[0,28]
【描述】支付宝的门店id，用于判断凭证是否可在此门店进行核销。
【注意事项】如果未传入此字段，会对时间做判断，跳过门店的判断逻辑，可能会导致此接口查询凭证为可用状态，但是核销时失败。
【示例值】2023031600077000000046296806
belong_merchant_id｜凭证归属的商户id可选string[0,32]
【描述】凭证归属的商户id。该参数为空时取当前请求商户id
【示例值】2088202967380463
certificate_status｜凭证状态可选string[0,32]
【描述】凭证状态筛选
【枚举值】
未使用: unuse
已使用: used
已失效: invalid
【示例值】unuse
常见请求示例
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.marketing.certificate.user.batchquery&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'biz_content={
"shop_id":"2023031600077000000046296806",
"user_id":"2088512417841101",
"open_id":"074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5",
"belong_merchant_id":"2088202967380463",
"page_num":1,
"certificate_status":"unuse",
"page_size":20
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
total_size｜总数量必选number(10)
【描述】总数量
【示例值】100
page_num｜分页查询页码必选number(10)
【描述】分页查询页码
【示例值】1
page_size｜每页记录数必选number(10)
【描述】分页查询单页数据条数
【示例值】20
certificate_info_list｜凭证信息列表可选certificatequeryinfo[]
【描述】凭证信息列表
certificate_id｜用户凭证id必选string(32)
【描述】用户凭证id
【示例值】2023052800445005825800000196
status｜状态必选string(32)
【描述】状态
【枚举值】
未使用: unuse
已使用: used
已过期: expired
【示例值】unuse
valid_begin_time｜开始生效时间必选date(20)
【描述】开始生效时间
【示例值】2023-01-01 00:00:00
valid_end_time｜过期时间必选date(20)
【描述】过期时间
【示例值】2023-03-31 23:59:59
can_use｜是否可用必选string(8)
【描述】当前凭证是否可用，如传入门店id，则会判断当前门店、当前时间是否可使用此凭证；如未传入门店id，仅返回当前时间是否可使用。
【枚举值】
可用: true
不可用: false
【注意事项】在查询用户凭证场景下如果商家未传入门店id，则有可能会导致此字段返回可使用，但核销时由于传入门店id而导致不满足核销条件致使核销失败的情况。
【示例值】"true"
code｜三方码可选string(128)
【描述】三方码凭证券码。
【注意事项】支付宝平台码场景该值为空
【示例值】123ab
out_order_id｜商家侧核销对应的交易订单id可选string(128)
【描述】商家侧核销对应的交易订单id
【示例值】2023073101
amount_info｜凭证金额信息可选certificateinstanceamountinfo
【描述】凭证实例的金额信息，在异常场景下可能为空，需要判断是否有值才可进行使用。
【注意事项】在网络异常的场景下此字段可能为空，商家需要保证对此字段非强诉求。
original_price｜商品原价可选price(10)
【描述】商品标注的原价，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】10.00
sale_price｜商品售价可选price(10)
【描述】商品售卖的价格，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】5.00
pay_amount｜用户实付金额可选price(10)
【描述】用户实付金额，单位为元
【示例值】20.00
receipt_amount｜商家实收金额可选price(10)
【描述】商品售价去除商家订单优惠后的商家实收，未计算收单费率等，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】4.00
merchant_discount_amount｜商家优惠金额可选price(10)
【描述】核销生效后商家减收部分，单位为元
【示例值】20.00
platform_discount_amount｜支付宝优惠金额可选price(10)
【描述】核销生效后平台、商家等出资的优惠部分，单位为元
【示例值】1.00
sku_info｜商品信息可选certificateskuinfo
【描述】商品信息
sku_id｜支付宝平台侧skuid可选string(128)
【描述】支付宝平台侧商品sku的唯一标识，后续与平台交互，需要使用该 id，建议持久化。
【示例值】2018091300502200001600103072
out_sku_id｜商家侧skuid可选string(128)
【描述】商家侧sku id，appid 下全局唯一。
【示例值】2018091300502200001600103072
item_id｜支付宝平台侧商品id可选string(128)
【描述】支付宝平台侧商品id，是支付宝平台侧商品的唯一标识，后续与平台交互，需要使用该 id，建议持久化。
【示例值】2018091300502200004400104166
out_item_id｜商家侧商品id可选string(128)
【描述】商家侧商品id，要求 appid 下全局唯一。
【示例值】2018091300502200004400104166
title｜商品名称可选string(128)
【描述】商品名称。 商品名称，字符类型，最少不低于3，最长不超过60个字。注：1.商品名称只允许汉字、数字、英文字母、特殊字符集；2.商品名称不得仅为数字、字母、特殊字符集或上述三种的组合。
【示例值】测试商品名称
item_type｜商品模版类型可选string(2)
【描述】商品模版类型：
1. 团购套餐
2. 代金券
此字段与使用alipay.open.app.localitem.create接口创建本地生活商品时传入的item_type字段值保持一致。
1. 团购套餐
2. 代金券
此字段与使用alipay.open.app.localitem.create接口创建本地生活商品时传入的item_type字段值保持一致。
【枚举值】
团购套餐: 1
代金券: 2
【示例值】1
use_rule_info｜核销规则可选certificateuseruleinfo
【描述】核销规则
use_num_limit｜使用张数限制可选string(128)
【描述】对应本地生活商品模版属性中的使用张数限制(use_num_limit)，参考本地生活商品模板
【示例值】{"limit":"1","num":"3"}
use_limit｜时间限制可选string(4096)
【描述】对应本地生活商品模版属性中的时间限制(use_limit)，参考本地生活商品模板
【示例值】{"use_time_type":"2","use_date_list":[{"days_of_week":["1","7"],"start_time":"hh:mm:ss","end_time":"hh:mm:ss","end_time_type":"same_day"}],"can_no_use_date_list":[{"holidays":[{"start_time":"hh:mm:ss","end_time":"hh:mm:ss","end_time_type":"same_day"}]}]}
times_card_info｜次卡详情可选certificatetimescardinfo
【描述】次卡详情，商品类型为次卡时该值必填
total_count｜次卡总次数必选number(32)
【描述】次卡总次数
【示例值】10
used_count｜已使用次数必选number(32)
【描述】已使用次数
【示例值】0
serial_info_list｜次卡次序号信息必选certificateserialinfo[]
【描述】次卡次序号信息
serial_no｜次序号必选string(32)
【描述】次序号
【示例值】11111
status｜次序号状态必选string(32)
【描述】次序号状态
【示例值】used
amount_info｜次序号的金额信息必选certificateinstanceamountinfo
【描述】次序号的金额信息
original_price｜商品原价可选price(10)
【描述】商品标注的原价，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】10.00
sale_price｜商品售价可选price(10)
【描述】商品售卖的价格，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】5.00
pay_amount｜用户实付金额可选price(10)
【描述】用户实付金额，单位为元
【示例值】20.00
receipt_amount｜商家实收金额可选price(10)
【描述】商品售价去除商家订单优惠后的商家实收，未计算收单费率等，单位为元。
【注意事项】异常情况下可能为空，需要判断是否有值才可使用。
【示例值】4.00
merchant_discount_amount｜商家优惠金额可选price(10)
【描述】核销生效后商家减收部分，单位为元
【示例值】20.00
platform_discount_amount｜支付宝优惠金额可选price(10)
【描述】核销生效后平台、商家等出资的优惠部分，单位为元
【示例值】1.00
响应示例
正常示例
异常示例
{
"alipay_marketing_certificate_user_batchquery_response": {
"code": "10000",
"msg": "success",
"certificate_info_list": [
{
"certificate_id": "2023052800445005825800000196",
"code": "123ab",
"status": "unuse",
"valid_begin_time": "2023-01-01 00:00:00",
"valid_end_time": "2023-03-31 23:59:59",
"out_order_id": "2023073101",
"can_use": "\"true\"",
"amount_info": {
"original_price": "10.00",
"sale_price": "5.00",
"pay_amount": "20.00",
"receipt_amount": "4.00",
"merchant_discount_amount": "20.00",
"platform_discount_amount": "1.00"
},
"sku_info": {
"sku_id": "2018091300502200001600103072",
"out_sku_id": "2018091300502200001600103072",
"item_id": "2018091300502200004400104166",
"out_item_id": "2018091300502200004400104166",
"title": "测试商品名称",
"item_type": "1"
},
"use_rule_info": {
"use_num_limit": "{\"limit\":\"1\",\"num\":\"3\"}",
"use_limit": "{\"use_time_type\":\"2\",\"use_date_list\":[{\"days_of_week\":[\"1\",\"7\"],\"start_time\":\"hh:mm:ss\",\"end_time\":\"hh:mm:ss\",\"end_time_type\":\"same_day\"}],\"can_no_use_date_list\":[{\"holidays\":[{\"start_time\":\"hh:mm:ss\",\"end_time\":\"hh:mm:ss\",\"end_time_type\":\"same_day\"}]}]}"
},
"times_card_info": {
"total_count": 10,
"used_count": 0,
"serial_info_list": [
{
"serial_no": "11111",
"status": "used",
"amount_info": {
"original_price": "10.00",
"sale_price": "5.00",
"pay_amount": "20.00",
"receipt_amount": "4.00",
"merchant_discount_amount": "20.00",
"platform_discount_amount": "1.00"
}
}
]
}
}
],
"total_size": 100,
"page_num": 1,
"page_size": 20
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试。 |
| time_out_exception | 调用超时 | 调用超时，请求可能成功也可能失败，请以相同的请求发起重试 |