基础能力

联合授权

视频能力

线索组件

接口调用凭证

Web 化接入

隐私协议

流量主

小程序码与小程序链接

用户信息

抖音号绑定

小程序推广计划

内容安全

任务能力

客服

小程序券

用户券管理

主播授权管理

营销活动管理

券模板管理

接口发放管理

触达与营销

支付

运营

生活服务

垂直行业

其它

用户领券结果回调通知

我的收藏

抖音开放平台通过券模板领券回调通知接口将用户领券成功的消息通知给开发者。

申请说明

•

出于用户在直播间领券的功能、性能体验效果考虑，用户在领券时能否成功发券只由抖音开放平台进行控制，领券结果回调通知默认只用于开发者进行消息订阅通知。开发者可参考「小程序券」直播玩法接入指南-第四步: 获取用户领券信息中「解析Query参数」、「查询用户可用券」功能在用户进入小程序时实时获取用户领取的券信息，也可以通过查询对账单接口T+1获取全量领券列表进行对账补齐。

•

若开发者有强诉求需要在领券链路控制是否给用户发券，请提供详细说明填写申请表进行申请。请注意，功能开通后，用户领券将等待开发者接口成功响应后才展示领券成功，因此用户领券体验强依赖开发者回调接口的性能、成功率、稳定性，这些需要开发者自行保证。对于直播间突发高QPS的领券场景也需要开发者提前对回调接口做好扩容、压测等保障措施，否则容易出现大面积客诉。

使用限制

•

抖音开放平台会尽可能的将用户领券结果通知给开发者，由于网络超时等情况，同样的通知可能会多次发送。开发者务必支持通知消息的幂等处理。推荐的做法是，当开发者收到通知消息进行处理时，先判断该通知消息是否已经处理。如果未处理，再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，可采用锁进行并发控制，以避免函数重入造成的数据混乱。

•

开发者对于回调通知的内容一定要用平台公钥做签名验证，防止数据泄露导致出现“假通知”，造成损失。

接口说明

•

抖音开放平台通过回调通知接口将用户领券成功的消息通知给开发者，开发者需要接收处理该消息，并响应，响应时不需要签名。

如果抖音开放平台收到开发者的响应不符合规范或超时未收到，抖音开放平台会认为通知失败，后期会通过一定的重试策略再次发起通知，尽可能提高通知的成功率，但抖音开放平台不保证通知最终能成功。

回调信息

名称	描述
HTTP URL	券模板配置的回调通知`callback_url`，详细可见券模板创建。要求必须为https地址。请确保回调通知URL是外部可正常访问的，且不能携带后缀参数，否则可能导致无法接收到回调通知。
HTTP Method	POST

请求头

属性	数据类型	必填	说明
content-type	string	是	`application/json`
Byte-Timestamp	string	是	签名时间戳
Byte-Nonce-Str	string	是	签名随机串
Byte-Signature	string	是	签名值

回调通知签名验证，可参考：签名算法，重点关注 “签名验证” 部分。如下图所示部分：

请求 Body

参数	类型	是否必填	描述	示例值
type	string	是	回调类型标记，领券成功回调固定为"send_coupon"。	send_coupon
msg	string	是	回调信息的 json 字符串。

当type=send_coupon时，msg 为如下结构：

参数	类型	是否必填	描述	示例值
coupon_id	string	是	•券id，由平台生成，全局唯一 •开发者可以用`coupon_id`作为幂等键，实现通知消息的幂等处理	709243586555366
app_id	string	是	小程序appid	ttxxxxxx
open_id	string	是	领券用户的小程序open id	95790093
coupon_status	int32	是	券状态，10：已领取	10
receive_time	int64	是	领券时间，单位秒	1686546782
merchant_meta_no	string	是	外部券模板编号，由开发者在创建券模板的接口上传，便于开发者定位属于自己业务的券	7090813568795790093
valid_begin_time	int64	是	券有效期开始时间，单位秒	1639643394
valid_end_time	int64	是	券有效期结束时间，单位秒	1639642948
talent_open_id	string	是	发券人的小程序open id，例如直播间渠道是主播openid，im渠道是员工openid	68795790093
talent_account	string	是	发券人的抖音号，例如直播间渠道是主播抖音号，im渠道是员工抖音号	221234234243
union_id	string	是	领券用户的union id	3d5f4913-xxxx-443d-b7ab-538db3f4e237

用户领券结果回调通知，开发者可以用coupon_id作为幂等键，实现通知消息的幂等处理。

回调示例

{
  "type": "send_coupon",
  "msg": "{\"coupon_id\":\"709243586555366\",\"app_id\":\"ttxxxxx\",\"open_id\":\"95790093\",\"coupon_status\":10,\"receive_time\":1686546782,\"merchant_meta_no\":\"7090813568795790093\",\"valid_begin_time\":1639643394,\"valid_end_time\":1639642948,\"talent_open_id\":\"68795790093\",\"talent_account\":\"221234234243\",\"union_id\":\"3d5f4913-xxxx-443d-b7ab-538db3f4e237\"}"
}

响应参数

名称	类型	是否必填	描述	示例值
err_no	int32	是	返回码，0代表成功，1代表拒绝发券	0
err_msg	string	是	返回码信息	""
notify_status	string	是	是否成功收到通知	"success"

应答时不需要签名。开发者成功处理回调时，http 应答状态码需为200，err_no务必返回0，notify_status务必返回success。
抖音开放平台预留了多个err_no错误码供开发者选择使用

err_no	err_msg	notify_status	描述	备注
0	""	"success"	收到通知并处理成功
1	"拒绝发券_{详细原因}"	"success"	收到通知但由于命中风控、用户黑名单等原因拒绝发放	只有通过「申请说明」进行功能申请后，拒绝发券能力才会生效。未通过申请前，回调接口仅用于开发者的消息订阅。

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "", 
  "notify_status": "success" // success 平台不会重试通知请求, fail 平台会重试通知请求
}

异常响应示例

{
  "err_no": 400,
  "err_msg": "business fail" // 开发者可返回可对外的报错信息
  "notify_status": "fail" 
}

Q&A

验签使用的平台公钥是服务商的还是授权小程序的？

•

创建券模板时secret_source传1或不传就使用授权小程序的，传2就是服务商的。详见创建券模板_小程序_抖音开放平台