上传短剧权益事件
收藏接口说明
适用于短剧行业小程序，将用户在短剧小程序内发生的权益相关事件进行上报。以提升小程序推广广告投放效率。
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/api/apps/v1/playlet_business/upload/ |
| HTTP Method | POST |
| Scope | apps.playlet_business.upload |
| 权限要求 |
短剧小程序权益事件回传 |
请求参数
请求头
access-token必填String
示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
示例：application/json
固定值"application/json"
Body展开全部子属性
context必填Struct
小程序/用户上下文信息
展开子属性
event_type必填String
示例：premium_member(购买权益事件)、coin_change(余额变动事件)
事件类型
properties必填String
示例："{\"benefit_type\": 2,\"benefit_start_time\": 1701360000,\"benefit_duration\": 365,\"playlet_name\": \"短剧名称\",\"album_id\": \"开放平台内容库-短剧ID\",\"order_id\": \"motbxxxxx\"}"
事件参数，详见事件参数定义（此处应传JSON格式序列化后的字符串）
timestamp必填Int64
示例：1712807795
事件发生时间
请求示例
curl --location 'https://open.douyin.com/api/apps/v1/playlet_business/upload/' \ --header 'Content-Type: application/json' \ --header 'access-token: clt.88d8fc30c04909fbfd074b0162ad0b6280RFwwbHTWtqkVPfpMXvjHr8B2LY' \ --data '{ "event_type": "premium_member", "context": { "device": { "open_id": "_000lGk5fU_oab8xxxxxxxxxx" }, "ad": { "callback": "xxxxxxx" } }, "timestamp": 1712807795, "properties": "{\"benefit_type\": 2,\"benefit_start_time\": 1701360000,\"benefit_duration\": 365,\"playlet_name\": \"短剧名称\",\"album_id\": \"开放平台内容库-短剧ID\",\"order_id\": \"motbxxxxx\"}" }'
响应参数
Body
err_msgString
示例：""（错误码为0，错误信息为空，表示请求成功）
错误信息
err_noInt32
示例：0
错误码
log_idString
示例："2027************"D3r1"
字节内部log_id，用于问题快速定位
响应示例
正常响应示例异常响应示例
{ "err_no": 0, "log_id": "2024022914353559F7FFC158707B0049FD", "err_msg": "" }
切换单列布局错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 28001005 | 系统内部错误，请重试 | 请求重试，若依然无解请向平台提交反馈 |
| 200 | 28001003 | access_token无效 | 重新请求生成access_token |
| 200 | 28001008 | access_token过期,请刷新或重新授权 | 重新请求生成access_token |
| 200 | 28001016 | 当前应用已被封禁或下线 | clientKey被封禁或者下线 |
| 200 | 28001006 | 网络调用错误，请重试 | 重试即可 |
| 200 | 28001014 | 应用未授权任何能力 | 确认应用是否授权能力 |
| 200 | 28001018 | 应用未获得该能力 | 开通相关能力 |
| 200 | 28003017 | quota已用完 | 联系平台处理 |
| 200 | 28001019 | 应用该能力已被封禁 | 该能力被封禁，联系平台处理 |
| 200 | 28001007 | 参数不合法 | 根据错误信息检查请求参数是否填写正常 |
事件参数定义
注意：最终properties应传JSON序列化后的字符串，具体case见请求实例。
购买权益事件
说明
在以下场景发生时回传：
- 1.用户购买一部短剧（解锁全集）
- 2.用户购买小程序时长会员（会员状态下小程序内全部短剧免费看）
参数定义
event_type：
premium_memberproperties：
参数 | 类型 | 说明 |
benefit_type | enum | 权益生效维度类型：
|
benefit_start_time | timestamp | 权益开始时间 |
benefit_duration | number | 权益生效时长（天） -1表示永久 30天，365天等 |
order_id | string | 订单ID（motb开头的） |
playlet_name | string | 巨量商品库-短剧名称，当权益生效维度为剧且广告来源客户必传 |
album_id | string | 开放平台内容库-短剧ID，当权益生效维度为剧时传 |
- •如用户一次性购买了一部短剧，有效期为永久，则回传
benefit_type=2，benefit_duration=-1，以及对应的短剧信息playlet_id / album_id- •如用户购买了小程序会员，有效期为365天，则回传
benefit_type=1，benefit_duration=365
