券核销消息通知

我的收藏

使用限制

无

接口说明

•

由于网络波动等原因，可能会产生重复的通知消息，接入方需要做好幂等，正确处理。

•

回调可能存在延时，开发者可以通过主动请求查询券信息，确认券核销结果。

•

在开发者服务端收到回调且处理成功后，需要按以下正常返回示例返回并且 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

请求示例

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 字段内容示例

{
  "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

响应示例

正常示例

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

异常示例

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

券核销消息通知

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​msg 字段​

​order_info 字段​

​coupon_verify_results 字段​

​请求示例​

​msg 字段内容示例​

​响应参数​

​响应示例​

​正常示例​

​异常示例​

使用限制

接口说明

基本信息

请求头

请求参数

msg 字段

order_info 字段

coupon_verify_results 字段

请求示例

msg 字段内容示例

响应参数

响应示例

正常示例

异常示例