抖音开放平台Logo
控制台

主播发券权限配置

更新时间 2024-07-24 02:58:49
收藏
我的收藏

接口说明

  • 该接口用于配置主播发券权限和初始化某个券模板给到主播的发放数量，如需调整发放数量，需要使用更新主播发券库存上限 接口操作。
  • 提供主播发券权限配置能力，可用于设置分配给主播的券模板是否生效。
  • 授权某个主播可以在直播间发放某张券模板，并设置主播发放的上限。假设某个券模板开发者设置的是1000总库存，开发者可以同时给多个主播授权发券权限，每个主播授权的个数不大于总库存即可。在配置的时候，平台不会校验已授权给主播的总库存是否小于券模板的总库存。

使用限制

  • 所授权的主播需要有当前挂载小程序的挂载权限，包括自挂载权限或通用挂载权限（注意不含达人挂载），权限介绍可参考：直播自主挂载能力、通用直播挂载能力。注意：该接口未进行挂载权限校验，在主播发券时会进行强校验，故在直播前需确保主播和小程序挂载权限已开启。
  • 配置主播发券权限时，不会锁定券模板库存；只有主播获得发放权限并创建发放计划（直播中或者开播前在主播端针对某个券设置发放数量）的时候才会锁定券模板库存。并且用户在主播直播间领取优惠券成功时，才会真正扣减券模板库存和扣减主播的发放上限。
  • 分配给单个主播的券库存的发放上限，不得超过券模板库存；但多个主播的券库存发放上限是独立的，平台不会将所有授权主播的上限累计求和，判断是否超过券模板库存。当券模板库存使用完后，主播即使有使用上限，也无法再创建发放计划。
  • 券模板-主播发放上限-发放计划的三者之间的库存关系，可查看文档 「小程序券」直播玩法接入指南 。

基本信息

名称描述
HTTP URL
https://open.douyin.com/api/promotion/v1/coupon/set_talent_coupon/
HTTP Method
POST
Scope
promotion.coupon.admin

请求头

名称字段类型是否必填示例描述
access-tokenString是clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
调用https://open.douyin.com/oauth/client_token/生成的token
content-typeString是application/json
固定值"application/json"

请求参数

Body

名称字段类型是否必填示例描述
account_typeInt32是1

账号类型：

  • 取值1时：talent_account 字段必填
  • 取值2是：open_id 字段必填
app_idString是ttec789ac573xxxxxx01

小程序appid

coupon_meta_idString是702345xxxxxxs

已创建的抖音开放平台券模板id，通过/api/promotion/v2/coupon/create_coupon_meta/接口返回的coupon_meta_id字段获取

stock_limitInt64是200

分配给主播的券库存的发放上限，不得超过券模板最大库存。平台不会校验已授权所有主播的库存之和是否大于券模板总库存，但主播真实可发券数量受总库存影响。例如券模板库存1000，开发者授权给了A、B、C三位主播每人1000，当A、B主播实际每人发放500后，A、B、C三人均不能再发券。

award_stock_limitInt64否20

分配给主播奖励券的库存数，仅券模板玩法含奖励券时必填，且不得超过券模板剩余库存数

open_idString否Cv4PoJXaTPn63rNu

用户open_id（达人在开发者小程序内的open_id），account_type为2时必填。该字段通过 /api/apps/v2/jscode2session 接口返回的 openid 字段获取

talent_accountString否7932234

主播抖音号，account_type为1时必填。该字段通过查看主播个人主页获得

请求示例

curl --location --request POST 'https://open.douyin.com/api/promotion/v1/coupon/set_talent_coupon' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw '{
    "account_type":1,
    "talent_account": "7932234",
    "open_id":"",
    "app_id": "ttec789ac573xxxxxx01",
    "coupon_meta_id": "702345xxxxxxs",
    "stock_limit": 200,
    "award_stock_limit": 20
}'

响应参数

Body

名称字段类型是否必填示例描述
err_msgString是""

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

err_noInt32是0

0表示成功

log_idString是202008121419360101980821035705926A

标识请求的唯一id

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "",
  "log_id": "202008121419360101980821035705926A"
}

异常响应示例

{
  "err_no": 29005004,
  "err_msg": "券记录不存在",
  "log_id": "202008121419360101980821035705926A"
}

错误码

http状态码错误码错误码描述排查建议
2000
success
接口请求成功，无需排查
20028001005
系统内部错误，请重试
请求重试，若依然无解请向平台提交反馈
20029005013
券模板不存在
检查券模板是否存在
20029005023
不可使用的券模板
券模板已作废
20029005024
设置库存超过当前券模板最大库存
减少设置库存值
20029005071
No Permission Operate
没有权限对券模板id进行操作,检查申请access-token的client_key是否与app_id一致
20029005072
券模板库存不存在
检查券模板创建是否配置库存
20028001007
参数不合法
检查请求参数
20029005033
主播发券权限配置已存在
主播发券权限配置已存在，不能重复调用接口进行配置