已更新更新时间：2024-10-23 18:09:39文档更新记录 >配置项检测工具收藏订阅更新我的文档设置接入检测（即可查看检测结果）若有未通过的接入检测项，接口将无法调通去登录返回文档完成 接入准备 后，商家和服务商可根据本文指引快速集成 小程序商品。说明：●小程序商品 仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用（传入 app_auth_token）方式，调用 api 接入。 ●小程序商品 支持沙箱调试。本地生活商品接入本地商品类目列表查询接口商家可通过alipay.open.app.localitem.allcategory.query（获取本地商品类目接口）获取支付宝小程序当前支持的所有本地商品类目信息，商家可以根据自己小程序的资质情况选择合适的类目进行商品提报。注意●不同商品类型返回的类目信息可能不一样。本地商品模板查询接口商家可通过 alipay.open.app.localitem.template.query（获取本地商品模板信息接口）获取不同类目下需要添加的个性化属性信息，接口里面的类目 id 编码是从类目列表查询接口中获取到的。注意●不同类目以及不同商品类型，对应的个性化属性及其校验规则是不一样的，这个地方需要动态实时查询。创建本地商品接口商家可通过 alipay.open.app.localitem.create（小程序本地商品创建接口）向支付宝提报小程序内的商品详情页url。创建成功后支付宝会返回支付宝平台侧商品id作为该商品的支付宝全局唯一商品编码供后续使用。注意●需保证商品的商家侧商品编码在该小程序下的唯一性。●商品创建接口里面的属性列表字段需要和该类目模板查询接口里面的属性列表字段对齐，所有的必填属性都需要存在，非必填属性可以不用填写。本地商品详情查询接口商家可通过 alipay.open.app.localitem.query（小程序本地商品详情查询接口）查询已同步到支付宝侧的商品数据详情，由于商品是多版本的，对于商家而言，可以根据接口中的参数控制查询当前生效版的商品详情数据，还是最新的编辑态待审核的商品数据。注意●商品查询需要传入创建时返回的支付宝侧商品id，或者商家侧商品id，两者不可同时为空。●商品创建完成后通过审核，所以首次提交的商品在审核结果未出前，需要设置 need_edit_spu=1 才能查询到。本地商品列表查询接口商家可通过 alipay.open.app.localitem.list.query（小程序本地商品分页查询接口）查询已同步到支付宝侧的商品数据。注意●商品查询需要传入创建时返回的平台侧商品id列表，或者商家侧id列表，两者不可同时为空，不可以混传。●该接口只能查询生效中的商品详情，不能根据不同的 id 返回不同版本的数据。本地商品更新接口商家可通过 alipay.open.app.localitem.modify（小程序本地商品修改接口）修改支付宝侧的商品数据。注意●商品首先需要同步到支付宝侧后才能支持修改，如果商品已经有一个版本是在审核中了，这时候商品是不支持修改的。本地商品免审更新接口正常情况下修改商品详情页的基础字段等信息都需要进行审核。为了方便商家及时的修改库存、状态等信息，商家可通过 alipay.open.app.localitem.direct.modify（小程序本地商品免审更新商品接口） 使用平台侧商品编码修改商品以及sku售卖状态、商品sku库存、价格（sku售价）。注意●商品首先需要同步到支付宝侧后才能支持状态修改，审核中的商品不支持修改。删除本地商品接口商家可通过 alipay.open.app.item.delete（小程序商品移除接口） ，通过上传商家侧商品id列表，或是返回的支付宝平台侧商品id删除不需要的商品信息。注意●商品首先需要同步到支付宝侧后才能支持删除。●商品删除会同时将生效中的版本和审核中的版本全部删除并从场景侧下线，并且删除是不可逆的，谨慎操作。商品状态变更消息通知接口商家/服务商可以监听 alipay.open.app.item.status.notify（商品状态变更消息同步接口），感知商品状态信息的变更。商品审核通过或驳回，以及后续商品售罄或冻结（违规/质量异常）均会通过本消息进行通知。注意1商品状态变更通知会在商品状态变更时发出，包括审核、售罄、冻结等操作生效之后发出。2变更推广计划通知仅包含简单的推广计划变更通知信息，更多商品信息需通过 alipay.open.app.localitem.query（小程序本地商品详情查询接口） 获取。消息示例：营销图片优化上传接口商家可以调用 alipay.marketing.image.enhance.upload（营销图片优化上传接口），指定上传场景对商品图进行规范校验、智能优化后再上传，将图片信息转存到支付宝侧进行使用，比如商品主子图等。凭证管理接入平台券码版接入步骤凭证核销准备平台码需要先调用核销准备接口，获取订单包含的凭证信息，选择要核销的凭证，再调用核销接口核销凭证。商家券码不需要调用此接口，直接进行凭证核销。商家根据扫码或输码信息调用 alipay.marketing.certificate.certification.prepareuse（凭证核销准备接口）进行核销准备，接口同步返回订单包含的凭证加密券码信息。●接口入参的 encrypted_data和 code 必须且只能二选一。○扫码核销：通过扫描二维码获取 encrypteddata 字段值，作为接口 encrypted_data 入参。二维码扫码结果示例：○输码核销：取二维码下方的 12 位券码作为接口 code 入参。○跳转小程序使用：跳转链接里会拼接 encrypteddata，从链接中获取 encrypteddata 字段值作为接口 encrypted_data 入参。链接示例：https://open.alipay.com/api?encrypteddata=1xx123456x12345678900xx1234x1234567。 更多请求参数说明及错误码详情，参见 alipay.marketing.certificate.certification.prepareuse（凭证核销准备接口） 接口文档。通过二维码解析标识获取加密券码通过原始券码获取加密券码凭证核销商家可通过 alipay.marketing.certificate.certification.use（同步凭证核销状态接口）进行本地生活商品凭证核销，接口同步返回核销结果。商家需保证 out_biz_no（外部业务单号）唯一，用作幂等控制。●biz_dt：业务发生时间，支付宝核销时间以外部业务时间为准，防止极限情况不能核销，商家需保证业务时间的准确性。●shop_id： 核销门店id。●user_id（open_id）、 order_id：值来源于核销准备接口返回结果。●certificate_use_info_list：核销券码信息列表，其中 certificate_use_info_list.encrypted_code 与 certificate_use_info_list.code 必须且只能二选一，分别对应平台券码和商家券码。○平台码使用 certificate_use_info_list.encrypted_code，值为核销准备接口返回的 encrypted_code 字段。○商家券码使用 certificate_use_info_list.code，值为用户下单时支付宝调用发码 spi 商家发放的券码。○返回结果中的 use_order_no 用于撤销核销。更多请求参数说明及错误码详情，可查看 alipay.marketing.certificate.certification.use（同步凭证核销状态接口）。平台码核销三方码核销凭证撤销核销商家可通过 alipay.marketing.certificate.certification.refund（撤销凭证核销状态接口）撤销本地生活商品凭证核销状态，接口同步返回取消核销结果。●user_id（open_id）：凭证归属支付宝用户 id。 新商户建议使用open_id替代该字段。对于新商户，user_id字段未来计划逐步回收，存量商户可继续使用。如使用open_id，请确认 应用-开发配置-openid配置管理 已启用。无该配置项，可查看openid配置申请。●use_order_no_list：需要撤销的核销单号，值为核销返回结果中的 use_order_no，该字段为列表，支持批量操作。注意：核销超过 1 小时就不可再撤销。更多请求参数说明及错误码详情，可查看 alipay.marketing.certificate.certification.refund（撤销凭证核销状态接口）。查询凭证信息更多请求参数说明及错误码详情，可查看 alipay.marketing.certificate.certification.batchquery（查询凭证信息接口）。条件查询用户凭证更多请求参数说明及错误码详情，可查看alipay.marketing.certificate.user.batchquery（条件查询用户凭证接口）。凭证核销准备jsapi商家可调用 my.ap.prepareusecertificate（凭证核销准备接口）进行凭证核销准备。示例代码退款确认spi说明：●result 只能是 同意/拒绝/等待，如果拒绝， 拒绝原因必填，拒绝原因不能超过 256 个字符，会进行敏感字校验。●退款咨询商户确认 spi：商户需同步返回确认结果 同意/拒绝/等待，等待 值下需 10 分钟内调用异步回调接口返回结果（同意/拒绝），未返回结果，则支付宝将自动退款给用户。●若退款咨询商户确认 spi 发送异常（商户侧未实现 spi、实现参数不正确、系统抖动等原因），支付宝侧会进行重试，若5分钟内重试失败，则支付宝将自动退款给用户。●退款咨询商户返回 拒绝 值：商户需在 24 小时内同步凭证核销消息，若未同步，支付宝将自动退款给用户。●更多请求参数说明及错误码详情，可查看spi.alipay.marketing.certificate.order.refundconfirm（退款前向商户确认是否可以退款接口）。退款确认回调openapi说明：●如果商户配置时未填写或者未设置是否由商家确认退款情况下，则不会向商户发起确认退款结果 spi。●如果商户未在指定时间范围内（10分钟）进行响应以及回复，则支付宝依旧会发起退款，商户需要自行处理退款事宜以及对应潜在的风险。●如果商户 10 分钟内回复了拒绝退款，请在 24 小时之内确认核销，否则 24 小时后支付宝依旧会发起退款。更多请求参数说明及错误码详情，可查看alipay.marketing.certificate.order.refundconfirmcommit（订单退款前商户回复确认退款结果接口）。凭证变更消息通知接口商家/服务商可以监听alipay.marketing.certificate.certification.notify（凭证消息通知接口），感知凭证信息的变更。具体为 核销，取消核销，发放，失效，过期。商家券码版说明：●小程序本地商品-凭证管理 仅支持自研商家/服务商通过 自研应用 或 第三方应用 代调用（传入 app_auth_token）方式，调用 api 接入。●小程序本地商品-凭证管理 支持沙箱调试。接入步骤凭证发放接口订单支付成功后，商家可通过实现 spi.alipay.marketing.certificate.certification.send（三方凭证发放接口）发放订单对应的凭证，发放的凭证可以包含券码、订单详情页等信息。注意：●如果发放异常，支付宝会进行重试发放。●如果 5 分钟内发放失败，支付宝将自动给用户进行退款。凭证发放回调接口如果商家需要异步处理发放，可以在 spi.alipay.marketing.certificate.certification.send(三方凭证发放) 中返回 result_code="processing"，然后调用 alipay.marketing.certificate.certificatetion.sendcallback（商家券码发放回调接口）返回发放券码结果。注意：●异步发码需要在 10 分钟内回调（包含发放接口已耗时）。退款确认spi更多请求参数说明及错误码详情，可查看 spi.alipay.marketing.certificate.order.refundconfirm（退款前向商户确认是否可以退款接口）。退款确认回调openapi更多请求参数说明及错误码详情，可查看alipay.marketing.certificate.order.refundconfirmcommit（订单退款前商户回复确认退款结果接口）。
