# 核销用户的团购优惠 > 接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考[接口调用指南](/doc/oplatform/developers/dev/guide.md)。 接口英文名：consumevoucher 接口使用说明： 1、单商户限频200QPS。 2、请在收到系统失败时，不要换单重试，避免系统原单超时成功后，换单无法成功，导致商家侧与平台侧券状态不同。建议核销失败后，以幂等方式重试 或 先反查券（调用接口14、查询用户的团购优惠详情）确认当前券状态和最新的核销单号，明确核销是否成功后再决策。 3、每张券最多可反复操作核销-撤销核销10次 核销资金说明： 1、券核销成功后，到达资金结算时间点未发生撤销核销，平台将发起分账结算，从订单资金扣除平台技术服务费、达人带货佣金（如有）、团长带货服务费（如有）后，解冻剩余订单资金。分账结算批处理有额外耗时，通常在24小时内全部完成，分账结算后商家即可提现至小店绑定的银行账户。 2、如一个订单有多张券，每一张券核销后都会独立发起一次分账结算 ## 1. 调用方式 ### HTTPS 调用 ```bash POST https://api.weixin.qq.com/channels/ec/voucher/consume?access_token=ACCESS_TOKEN ``` ### 云调用 - 本接口不支持云调用。 ### 第三方调用 - 本接口支持第三方平台代商家调用。 - 该接口所属的权限集 id 为：164 - 服务商获得其中之一权限集授权后，可通过使用 [authorizer_access_token](/doc/oplatform/developers/dev/AuthorizerAccessToken.md) 代商家进行调用，具体可查看 [第三方调用](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/call_interface.md) 说明文档。 ## 2. 请求参数 ### 查询参数 `Query String Parameters` ```json [ { "参数名": "access_token", "类型": "string", "必填": "是", "示例": "ACCESS_TOKEN", "说明": "接口调用凭证，可使用 [access_token](/doc/channels/api/basic/api_getaccesstoken)、[authorizer_access_token](/doc/oplatform/openApi/ticket-token/api_getauthorizeraccesstoken.md)" } ] ``` ### 请求体 `Request Payload` ```json [ { "参数名": "consume_request_no", "类型": "string", "必填": "是", "说明": "核销操作幂等串，商户自定义，请保证在小店下唯一 size最长128字节", "枚举": "-" }, { "参数名": "encrypted_codes", "类型": "Array", "必填": "否", "说明": "用户订单详情页跳转商家上小程序时可以从path上获取。codes + sku_id组合和encrypted_codes二者选其一。对于次卡类型商品，如果传多次相同的encrypted_code，代表核销多次。核销多次/多张同时成功或同时失败，不会部分成功。array_size最大为10", "枚举": "-" }, { "参数名": "codes", "类型": "Array", "必填": "否", "说明": "用户的券code，用户订单详情页面的二维码扫码后获得，查询用户的团购优惠详情接口返回的code。codes+ sku_id组合和encrypted_codes二者选其一。对于次卡类型商品，如果传多次相同的code，代表核销多次。核销多次/多张同时成功或同时失败，不会部分成功。array_size最大为10", "枚举": "-" }, { "参数名": "sku_id", "类型": "string", "必填": "否", "说明": "如果不是使用encrypted_code核销，sku_id必传", "枚举": "-" }, { "参数名": "consume_store_name", "类型": "string", "必填": "否", "说明": "如果需要在C端展示券的核销门店名称，可以选填（仅作为展示）size最长128字节", "枚举": "-" }, { "参数名": "consume_channel", "类型": "number", "必填": "是", "说明": "核销渠道。仅供商家用于标记用户核销的途径是通过小程序核销/线下识别二维码核销，平台侧无额外校验规则。", "枚举": "枚举值" }, { "参数名": "out_store_id", "类型": "string", "必填": "否", "说明": "核销门店id，商家自定义的门店id（仅作为商家门店标记）", "枚举": "-" }, { "参数名": "reserve_no", "类型": "string", "必填": "否", "说明": "如果商家在预约白名单内，且商品开启了预约，则一定要先预约才能核销。", "枚举": "-" } ] ``` ## 3. 返回参数 ### 返回体 `Response Payload` ```json [ { "参数名": "errcode", "类型": "number", "说明": "错误码" }, { "参数名": "errmsg", "类型": "string", "说明": "错误信息" }, { "参数名": "voucher_list", "类型": "Array", "说明": "用户券详情" }, { "参数名": "fail_voucher_list", "类型": "objarray", "说明": "无法操作的券，在明确有券无法核销时返回，含无法核销原因,当API返回10027061时返回" } ] ``` "> ### Res.fail_voucher_list(Array) `Object Payload` 无法操作的券，在明确有券无法核销时返回，含无法核销原因,当API返回10027061时返回 ```json [ { "参数名": "code", "类型": "string", "说明": "操作的券code，核销时传code时或者传了有效的加密code时返回" }, { "参数名": "sku_id", "类型": "string", "说明": "操作的券sku_id，核销时传code时或者传了有效的加密code时返回" }, { "参数名": "encrypted_code", "类型": "string", "说明": "核销时传的加密code非法返回" }, { "参数名": "ret_code", "类型": "string", "说明": "操作结果" }, { "参数名": "ret_msg", "类型": "string", "说明": "操作结果说明" } ] ``` ## 4. 枚举信息 ### Body.consume_channel `Enum` 核销渠道。仅供商家用于标记用户核销的途径是通过小程序核销/线下识别二维码核销，平台侧无额外校验规则。 ```json [ { "枚举值": "1", "描述": "CONSUME_CHANNEL_MINI_APP 小程序" }, { "枚举值": "2", "描述": "CONSUME_CHANNEL_IN_STORE 到店" } ] ``` ## 5. 注意事项 注意： 1、此核销方式需前往视频号小店网页端-「订单与核销」-「核销管理」- 「管理核销方式」开通。 2、此核销方式仅面向中高品牌力商家开放，如开通时提示“暂不支持”，请使用“小程序核销组件：核销用户的团购优惠”接口。 3、需通过「API核销接口」核销成功一张券，才能完成开通。 4、开通前，该方式只能核销店铺成员的团购优惠券，不能核销非店铺成员的团购优惠券 ## 6. 代码示例 请求示例 ``` json // 示例：加密code模式 { "consume_request_no": "233244dfgfdfgsdfgsdf", "encrypted_codes": ["243234dsfsdf", "24334dfgd", "345453dsf"], "store_name":"xxx旗舰店", "consume_channel" : 2 } // 示例：非加密code模式 { "consume_request_no": "233244dfgfdfgsdfgsdf", "codes": ["232323","23232323","32434454545"], "sku_id": "fdsfdf", "store_name": "xxx旗舰店", "consume_channel" : 1 } ``` 返回示例 ``` json { "errcode": 0, "errmsg": "成功", "voucher_list":[ { "code":"232323", "status": 2, "send_time": 1699856182, "update_time": 1699856182, "start_time": 1699856182, "end_time": 1699856182, "consume_time": 1699856182, "refund_time": 1699856182, "product_id": "kbfff", "consume_store_name": "xxx旗舰店", "voucher_type": 1, "voucher_buy_amount": 0, "voucher_actual_amount": 0, "telphone_no": "fasdf343df34545", "openid": "xsdfs4534543534534", "code_type": 1, "order_id": "23434sdfsdf34342", "sku_id": "fdsfdf" }, { "code":"23232323", "status": 2, "send_time": 1699856182, "update_time": 1699856182, "start_time": 1699856182, "end_time": 1699856182, "consume_time": 1699856182, "refund_time": 1699856182, "product_id": "kbfff", "consume_store_name": "xxx旗舰店", "voucher_type": 1, "voucher_buy_amount": 0, "voucher_actual_amount": 0, "telphone_no": "fasdf343df34545", "openid": "xsdfs4534543534534", "code_type": 1, "order_id": "23434sdfsdf34342", "sku_id": "fdsfdf" }, { "code":"32434454545", "status": 2, "send_time": 1699856182, "update_time": 1699856182, "start_time": 1699856182, "end_time": 1699856182, "consume_time": 1699856182, "refund_time": 1699856182, "product_id": "kbfff", "consume_store_name": "xxx旗舰店", "voucher_type": 1, "voucher_buy_amount": 0, "voucher_actual_amount": 0, "telphone_no": "fasdf343df34545", "openid": "xsdfs4534543534534", "code_type": 1, "order_id": "23434sdfsdf34342", "sku_id": "fdsfdf" } ] } ``` ## 7. 错误码 以下是本接口的错误码列表，其他错误码可参考 [通用错误码](/doc/oplatform/developers/errCode/README.md)；调用接口遇到报错，可使用官方提供的 [API 诊断工具](https://developers.weixin.qq.com/console/devtools/debug?utm_source=api_errcode) 辅助定位和分析问题。 ```json [ { "错误码": "10027017", "错误描述": "encrypted_code错误，请确认填写的encrypted_code是否正确" }, { "错误码": "10027018", "错误描述": "code错误，请确认填写的code是否正确" }, { "错误码": "10027019", "错误描述": "consume_request_no超过最写大长度" }, { "错误码": "10027020", "错误描述": "product_id错误，请确认填写的product_id是否正确" }, { "错误码": "10027021", "错误描述": "store_name超过最大长度" }, { "错误码": "10027022", "错误描述": "consume_channel不合法，没设置或者没填写规定的值" }, { "错误码": "10027023", "错误描述": "encrypted_code超过最大数量" }, { "错误码": "10027024", "错误描述": "code超过最大数量" }, { "错误码": "10027061", "错误描述": "券已经被其他操作凭证操作锁定" } ] ``` ## 8. 适用范围 本接口支持「微信小店」账号类型调用。其他账号类型如无特殊说明，均不可调用。 ![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)接口变更日志（1条） 2026 年 06 月 22 日新增reserve_no，支持开启了预约的商品的核销