抖音开放平台Logo
控制台

券核销消息通知

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

​使用限制​

无​

​接口说明​

    •​由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。​
    •​回调可能存在延时，开发者可以通过主动请求查询券信息，确认券核销结果。​
    •​在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 HTTP 响应状态码设为 200，否则会认为通知失败进行重试。​

​基本信息​

基本信息​
HTTP URL​
在抖音开放平台-核销工具小程序页面-开发-行业模板-券核销消息通知中订阅。​
HTTP Method​
POST​

​请求头​

参见通用参数。​

​请求参数​

参数名称​
类型​
是否必填​
描述​
示例值​
msg​
string​
是​
订单相关信息的 json 字符串​
见请求示例​
type​
​
string​
​
是​
​
固定值：coupon_verify​
coupon_verify​
version​
string​
是​
固定值："2.0"。​
回调版本，用于开发者识别回调参数的变更​
2.0​

​msg 字段​

字段名​
类型​
是否必填​
描述​
示例值​
app_id​
string​
是​
小程序 app_id​
ttxxxxx​
order_info​
object​
是​
小程序交易系统订单信息​
​
poi_id​
string​
是​
核销门店poi_id，核销工具订单由开发者下单时传入​
8607092469467730​
coupon_verify_results​
array(object)​
是​
核销工具订单下单时传入的原生券核销信息​
​

​order_info 字段​

字段名​
类型​
是否必填​
描述​
示例值​
order_id​
string​
是​
核销工具在小程序交易系统产生的订单号​
ots7057435515980663049​
order_source​
string​
是​
订单来源标识​
    •​核销工具订单：fulfillment_tool​
fulfillment_tool​

​coupon_verify_results 字段​

字段名​
类型​
是否必填​
描述​
示例值​
result_code​
int​
是​
验券结果，0为成功，非0失败​
0​
result_msg​
string​
是​
验券结果说明​
验券成功​
certificate_id​
string​
是​
抖音原生券ID，下单时传入的抵扣券ID​
71843339522862940​
verify_id​
string​
否​
此次核销行为的唯一标识，验券成功才会有。​
撤销核销接口需要用到​
71843339522862999​
verify_time​
int64​
否​
核销时间，验券成功才会有。​
1672748886​
code​
string​
否​
核销用户券码code，核销成功后返回，需要联系运营加白​
100090023546491​
order_id​
string​
是​
抖音原生订单ID​
10000234125634​

​请求示例​

js
复制
curl --location --request POST 'https://xxxxxxx.net/api/v2/result_callback' \
--header 'Content-Type: application/json' \
--data-raw='{
"version": "2.0", //本次固定为2.0, 通过版本信息识别，用不同的结构体去解析上述关键参数
"msg": "{\"app_id\":\"ttxxxxx\",\"poi_id\":\"8607092469467730\",\"order_info\":{\"order_id\":\"ots7057435515980663049\",\"order_source\":\"fulfillment_tool\"},\"coupon_verify_results\":[{\"certificate_id\":\"71843339522862940\",\"verify_id\":\"71843339522862999\",\"verify_time\":1672748886,\"result_code\":0,\"result_msg\":\"验券成功\"}]}",
"type": "coupon_verify"
}'

​msg 字段内容示例​

json
复制
{
"app_id": "ttxxxxx",
"poi_id": "8607092469467730",
"order_info": {
"order_id": "ots7057435515980663049",
"order_source": "fulfillment_tool"
},
"coupon_verify_results": [
{
"certificate_id": "71843339522862940",
"verify_id": "71843339522862999",
"verify_time": 1672748886,
"result_code": 0,
"result_msg": "验券成功",
"code":"100090023546491",
"order_id": "10000234125634"
}
]
}

​响应参数​

参数名称​
类型​
描述​
示例值​
err_no​
int64​
错误码​
0​
err_tips​
string​
错误提示​
success​

​响应示例​

​正常示例​

JSON
复制
//正常返回响应且http状态码为200
//注意：
//正常返回时一定要保证err_no和err_tips为下面标准返回方式，不然都认为失败，将会重试
{
"err_no": 0,
"err_tips": "success"
}

​异常示例​

JSON
复制
//异常响应或http状态码为非200，
//字节服务端会不断重试
{
"err_no": 1, //非0
"err_tips": "system error" //非success
}
​