用户领券结果回调通知
收藏抖音开平通过券模板领券回调通知接口将用户领券成功的消息通知给开发者。
申请说明
- •出于用户在直播间领券的功能、性能体验效果考虑，用户在领券时能否成功发券只由抖音开平进行控制，领券结果回调通知默认只用于开发者进行消息订阅通知。开发者可参考「小程序券」直播玩法接入指南-第四步: 获取用户领券信息中「解析Query参数」、「查询用户可用券」功能在用户进入小程序时实时获取用户领取的券信息，也可以通过查询对账单接口T+1获取全量领券列表进行对账补齐。
- •若开发者有强诉求需要在领券链路控制是否给用户发券，请提供详细说明填写申请表进行申请。请注意，功能开通后，用户领券将等待开发者接口成功响应后才展示领券成功，因此用户领券体验强依赖开发者回调接口的性能、成功率、稳定性，这些需要开发者自行保证。对于直播间突发高QPS的领券场景也需要开发者提前对回调接口做好扩容、压测等保障措施，否则容易出现大面积客诉。
使用限制
- •抖音开平会尽可能的将用户领券结果通知给开发者，由于网络超时等情况，同样的通知可能会多次发送。开发者务必支持通知消息的幂等处理。 推荐的做法是，当开发者收到通知消息进行处理时，先判断该通知消息是否已经处理。如果未处理，再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，可采用锁进行并发控制，以避免函数重入造成的数据混乱。
- •开发者对于回调通知的内容一定要用平台公钥做签名验证，防止数据泄露导致出现“假通知”，造成损失。
接口说明
- •抖音开平通过回调通知接口将用户领券成功的消息通知给开发者，开发者需要接收处理该消息，并响应，响应时不需要签名。
如果抖音开平收到开发者的响应不符合规范或超时未收到，抖音开平会认为通知失败，后期会通过一定的重试策略再次发起通知，尽可能提高通知的成功率，但抖音开平不保证通知最终能成功。
回调信息
名称 | 描述 | |||
HTTP 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 | 是 |
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就是服务商的。详见创建券模板_小程序_抖音开放平台
