视频号
取消
中文
中文
EN
取消
  • 介绍

    • # 核销用户的团购优惠

    接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南

    接口英文名：consumevoucher

    接口使用说明： 1、单商户限频200QPS。 2、请在收到系统失败时，不要换单重试，避免系统原单超时成功后，换单无法成功，导致商家侧与平台侧券状态不同。建议核销失败后，以幂等方式重试 或 先反查券（调用接口14、查询用户的团购优惠详情）确认当前券状态和最新的核销单号，明确核销是否成功后再决策。 3、每张券最多可反复操作核销-撤销核销10次

    核销资金说明： 1、券核销成功后，到达资金结算时间点未发生撤销核销，平台将发起分账结算，从订单资金扣除平台技术服务费、达人带货佣金（如有）、团长带货服务费（如有）后，解冻剩余订单资金。分账结算批处理有额外耗时，通常在24小时内全部完成，分账结算后商家即可提现至小店绑定的银行账户。 2、如一个订单有多张券，每一张券核销后都会独立发起一次分账结算

    # 1. 调用方式

    # HTTPS 调用

    POST https://api.weixin.qq.com/channels/ec/voucher/consume?access_token=ACCESS_TOKEN

    # 云调用

    • 本接口不支持云调用

    # 第三方调用

    • 本接口支持第三方平台代商家调用。

    • 该接口所属的权限集 id 为：164

    • 服务商获得其中之一权限集授权后，可通过使用 authorizer_access_token 代商家进行调用，具体可查看 第三方调用 说明文档。

    # 2. 请求参数

    # 查询参数 Query String parameters

    参数名类型必填示例说明
    access_tokenstring是ACCESS_TOKEN接口调用凭证，可使用 access_token、authorizer_access_token

    # 请求体 Request Payload

    参数名类型必填说明枚举
    consume_request_nostring是核销操作幂等串，商户自定义，请保证在小店下唯一 size最长128字节-
    encrypted_codesArray否用户订单详情页跳转商家上小程序时可以从path上获取。codes + sku_id组合和encrypted_codes二者选其一。对于次卡类型商品，如果传多次相同的encrypted_code，代表核销多次。核销多次/多张同时成功或同时失败，不会部分成功。array_size最大为10-
    codesArray否用户的券code，用户订单详情页面的二维码扫码后获得，查询用户的团购优惠详情接口返回的code。codes+ sku_id组合和encrypted_codes二者选其一。对于次卡类型商品，如果传多次相同的code，代表核销多次。核销多次/多张同时成功或同时失败，不会部分成功。array_size最大为10-
    sku_idstring否如果不是使用encrypted_code核销，sku_id必传-
    consume_store_namestring否如果需要在C端展示券的核销门店名称，可以选填（仅作为展示）size最长128字节-
    consume_channelnumber是核销渠道。仅供商家用于标记用户核销的途径是通过小程序核销/线下识别二维码核销，平台侧无额外校验规则。枚举值
    out_store_idstring否核销门店id，商家自定义的门店id（仅作为商家门店标记）-

    # 3. 返回参数

    # 返回体 Response Payload

    参数名类型说明
    errcodenumber错误码
    errmsgstring错误信息
    voucher_listArray用户券详情
    fail_voucher_listobjarray无法操作的券，在明确有券无法核销时返回，含无法核销原因,当API返回10027061时返回

    # Res.fail_voucher_list(Array) Object Payload

    无法操作的券，在明确有券无法核销时返回，含无法核销原因,当API返回10027061时返回

    参数名类型说明
    codestring操作的券code，核销时传code时或者传了有效的加密code时返回
    sku_idstring操作的券sku_id，核销时传code时或者传了有效的加密code时返回
    encrypted_codestring核销时传的加密code非法返回
    ret_codestring操作结果
    ret_msgstring操作结果说明

    # 4. 枚举信息

    # Body.consume_channel Enum

    核销渠道。仅供商家用于标记用户核销的途径是通过小程序核销/线下识别二维码核销，平台侧无额外校验规则。

    枚举值描述
    1CONSUME_CHANNEL_MINI_APP 小程序
    2CONSUME_CHANNEL_IN_STORE 到店

    # 5. 注意事项

    注意： 1、此核销方式需前往视频号小店网页端-「订单与核销」-「核销管理」- 「管理核销方式」开通。 2、此核销方式仅面向中高品牌力商家开放，如开通时提示“暂不支持”，请使用“小程序核销组件：核销用户的团购优惠”接口。 3、需通过「API核销接口」核销成功一张券，才能完成开通。 4、开通前，该方式只能核销店铺成员的团购优惠券，不能核销非店铺成员的团购优惠券

    # 6. 代码示例

    请求示例

    // 示例：加密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
}

    返回示例

    {
   "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. 错误码

    以下是本接口的错误码列表，其他错误码可参考 通用错误码；调用接口遇到报错，可使用官方提供的 API 诊断工具 辅助定位和分析问题。

    错误码错误描述解决方案
    10027017encrypted_code错误，请确认填写的encrypted_code是否正确
    10027018code错误，请确认填写的code是否正确
    10027019consume_request_no超过最写大长度
    10027020product_id错误，请确认填写的product_id是否正确
    10027021store_name超过最大长度
    10027022consume_channel不合法，没设置或者没填写规定的值
    10027023encrypted_code超过最大数量
    10027024code超过最大数量
    10027061券已经被其他操作凭证操作锁定

    # 8. 适用范围

    本接口支持「微信小店」账号类型调用。其他账号类型如无特殊说明，均不可调用。