本地生活商品
商户调用该接口，通过订单号及三方码进行本地商品凭证核销，接口同步返回核销结果。
公共请求参数
业务请求参数
out_biz_no｜外部业务单号必选string(64)
【描述】业务请求单号，用作幂等控制。 超时重试等幂等请求场景保持该值不变，且确保其它所有请求参数不变，再次请求返回上次执行结果。其它场景请更换该值，确保每次不同的请求该值不相同。
【示例值】20170101000001654bb46ba
biz_dt｜核销时间必选date(20)
【描述】核销时间。格式为：yyyy-mm-dd hh:mm:ss
【注意事项】支付宝的核销时间以外部核销的时间为准，防止极限情况导致凭证无法核销。商家需保证核销时间的准确性
【示例值】2023-01-01 00:00:00
shop_id｜核销门店id必选string(32)
【描述】核销门店id
【示例值】202104232200142626143676
certificate_use_info_list｜凭证核销详情必选certificateuseinfo[]
【描述】凭证核销详情
以下参数 二选一 传入必选
encrypted_code｜支付宝平台加密券码string(256)
【描述】核销准备返回的支付宝平台加密券码
【注意事项】encrypted_code与code必须且只能二选一
【示例值】llyabkaeslgosrsh/oafu5
code｜三方码string(256)
【描述】三方码。取值为支付宝调用凭证发放spi时商户返回的三方码
【注意事项】encrypted_code与code必须且只能二选一
【示例值】123ab
use_count可选number(32)
【描述】凭证核销次数。不传默认为1
【注意事项】传入次数必须小于或等于剩余可核销次数
【示例值】1
以下参数 二选一 传入
user_id｜凭证归属支付宝用户idstring(32)
【描述】凭证归属支付宝用户id。平台码模式从核销准备接口获取
新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。
【示例值】2088xxxxx
open_id｜凭证归属支付宝用户openidstring(128)
【描述】凭证归属支付宝用户openid 详情可查看 openid简介
【示例值】074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5
order_id｜购买商品的订单id条件必选string(128)
【描述】购买商品的订单id。平台码模式从核销准备接口获取
【注意事项】三方码核销时该值必传
【必选条件】当certificate_use_info传入code时必选
【示例值】2021042322001426261436764012
out_order_id｜商家侧核销对应的交易订单id可选string(128)
【描述】商家侧核销对应的交易订单id
【示例值】2023080101
常见请求示例
平台码核销
三方码核销
默认示例
curl 'https://openapi.alipay.com/gateway.do?charset=utf-8&method=alipay.marketing.certificate.certification.use&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=rsa2×tamp=${now}' \
-f 'app_auth_token=${app_auth_token}' \
-f 'biz_content={
"biz_dt":"2023-01-01 00:00:00",
"certificate_use_info_list":[
{
"encrypted_code":"llyabkaeslgosrsh/oafu5"
}
],
"order_id":"2021042322001426261436764012",
"out_biz_no":"20170101000001654bb46ba",
"shop_id":"202104232200142626143676",
"user_id":"2088xxxxx",
"open_id":"074a1cctg1lelxke4xqc0zgndid0nxi95b5lsnpazwyoco5"
}' 说明：本示例仅供参考。
公共响应参数
业务响应参数
certificate_use_result_list｜凭证核销结果必选certificateuseresult[]
【描述】凭证核销结果
certificate_id｜凭证id必选string(32)
【描述】凭证id
【示例值】2021042322001426261436764012
result｜结果枚举必选string(32)
【描述】核销结果枚举
【枚举值】
核销成功: success
凭证不是可核销状态: certificate_cannot_use
商品不在可用商品范围内: not_in_available_item
【示例值】success
msg｜结果说明必选string(1024)
【描述】结果说明
【示例值】核销成功
order_id｜购买商品的订单id必选string(64)
【描述】购买商品的订单id。
【示例值】1997081101502300000001290055702988
以下参数 二选一 必选
code｜三方码string(256)
【描述】三方码
【示例值】124ab
encrypted_code｜支付宝平台加密券码string(256)
【描述】核销准备返回的支付宝平台加密券码
【示例值】llyabkaeslgosrsh/oafu5
use_order_no｜核销操作单号条件必选string(32)
【描述】核销操作单号,核销成功必填,撤销核销使用
【必选条件】核销成功必填,撤销核销使用
【示例值】2023052100445005835800000045
out_order_id｜商家侧核销对应的交易订单id可选string(128)
【描述】商家侧核销对应的交易订单id
【示例值】2023073101
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(10)
【描述】商品模版类型：
1. 团购套餐
2. 代金券
此字段与使用alipay.open.app.localitem.create接口创建本地生活商品时传入的item_type字段值保持一致。
1. 团购套餐
2. 代金券
此字段与使用alipay.open.app.localitem.create接口创建本地生活商品时传入的item_type字段值保持一致。
【枚举值】
团购套餐: 1
代金券: 2
次卡: 3
【示例值】1
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
serial_info_list｜本次核销的次序号信息可选certificateserialinfo[]
【描述】本次核销的次序号信息
serial_no｜次序号必选string(32)
【描述】次序号
【示例值】11111
status｜次序号状态必选string(32)
【描述】次序号状态
【枚举值】
未使用: unuse
已使用: used
已过期: expired
【示例值】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_certification_use_response": {
"code": "10000",
"msg": "success",
"certificate_use_result_list": [
{
"certificate_id": "2021042322001426261436764012",
"code": "124ab",
"encrypted_code": "llyabkaeslgosrsh/oafu5",
"use_order_no": "2023052100445005835800000045",
"result": "success",
"msg": "核销成功",
"out_order_id": "2023073101",
"order_id": "1997081101502300000001290055702988",
"sku_info": {
"sku_id": "2018091300502200001600103072",
"out_sku_id": "2018091300502200001600103072",
"item_id": "2018091300502200004400104166",
"out_item_id": "2018091300502200004400104166",
"title": "测试商品名称",
"item_type": "1"
},
"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"
},
"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"
}
}
]
}
]
},
"sign": "eritjkeijkjhkkkkkkkhjereeeeeeeeeee"
}说明：本示例仅供参考。
公共错误码
业务错误码
| 错误码 | 错误描述 | 凯发app官方网站的解决方案 |
|---|---|---|
| system_error | 系统繁忙 | 可能发生了网络或者系统异常，导致服务调用失败，商户可以用同样的请求发起重试 |
| invalid_parameter | 参数有误 | 请根据接口返回的参数非法的具体错误信息，修改参数后进行重试 |
| certificate_cannot_use | 凭证不可核销 | 凭证当前不是可核销状态，请检查并修改参数后重试 |
| certificate_is_invalid | 凭证已作废 | 对应的凭证已经作废，不能再核销，修改入参后进行重试。 |
| certificate_is_used | 凭证已核销 | 对应的凭证已经被核销，不能再次核销，修改入参后进行重试。 |
| certificate_not_exist | 凭证不存在或未发放 | 对应的凭证不存在，修改入参后进行重试。 |
| time_out_exception | 调用超时 | 调用超时，请求可能成功也可能失败，请以相同的请求发起重试，重试请确保外部业务单号(out_biz_no)不变 |