用户核销券

开发环境

POST

/api/promotion/v1/coupon/batch_consume_coupon

该接口用于同步用户核销券状态到开放平台。

使用限制

接口会校验open_id对应的用户在24小时内是否登录过小程序，确保开发者核销的真实性。

接口说明

使用场景：用户支付成功、用户预约成功等已使用优惠券场景。
用户核销券后，将券状态同步到开放平台，抖音卡包中券状态由“待核销”改为“已核销”。
权限要求

需要申请权限。路径：

小程序：抖音开放平台控制台 > 应用详情 > 能力 > 能力实验室 > 小程序券

错误码

HTTP 状态码	错误码	描述	排查建议
200	0	success	接口请求成功，无需排查
200	28001005	系统内部错误，请重试	请求重试，若依然无解请向平台提交反馈
200	28001007	参数不合法	检查请求参数是否填写正常
200	29005013	券模板不存在	请检查券id是否填写正确
200	29005028	用户24h内未登录小程序	核销同步太晚，需要用户近24小时内登录过小程序
200	29005043	order_id为空	满减券和立减券，必须传订单id
200	29005065	重复核销	该券已经提交过核销记录，无需再提交
200	29005064	更新券记录状态失败	重试

请求示例

Shell

JavaScript

Java

Swift

curl --location --request POST 'http://dev-cn.your-api-server.com/api/promotion/v1/coupon/batch_consume_coupon' \
--header 'access-token: clt.xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "open_id":"ba253642-0590-40bc-xxx",
    "consume_out_no": "123",
    "app_id": "ttec789ac573xxxxxx01",
    "coupon_id_list": [
        "702345xxxxxx",
        "702345xxxxxx"
    ],
    "order_id": 614167279916,
    "consume_time": 1676966474
}'

响应示例

200 - 成功示例

{
  "err_no": 0,
  "err_msg": "",
  "log_id": "202008121419360101980821035705926A",
  "data": {
    "results": [
      {
        "coupon_id": "702345xxxxxx",
        "err_no": 0,
        "err_msg": "验券成功"
      }
    ]
  }
}

请求参数

Header 参数

Content-Type

string

必需

示例值:

application/json

access-token

string

必需

示例值:

clt.xxx

Body 参数application/json

open_id

string

必需

核销用户在小程序的open_id

consume_out_no

string

必需

开发者核销单号（开发者内部系统的券核销记录自增id或uuid），由开发者系统生成，平台留底，用于后续产生撤销核销，平台定位之前的核销记录

app_id

string

必需

开发者小程序appid

coupon_id_list

array[string]

必需

抖音开平券id列表（开发者通过平台的领券回调获得券id），一次最多核销10张券

order_id

integer

可选

抖音开平侧生成的支付订单号，立减券和满减券必填，权益券选填。来源于交易系统或担保支付：交易系统预下单回调、担保支付预下单接口

consume_time

integer

券核销时间，单位秒

必需

示例

返回响应

🟢200成功

application/json

Body

err_no

integer

0表示成功

必需

err_msg

string

必需

err_no非0时对应的错误信息文案提示，成功时为空字符串

log_id

string

标识请求的唯一id

必需

data

object

必需

results

array [object {3}]

必需

🟠400请求有误

修改于 2023-11-30 06:19:42

用户手机号授权结果回调通知

查询主播发券配置信息

用户核销券

使用限制#

接口说明#

错误码#

请求参数

返回响应

使用限制

接口说明

错误码