抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 解决方案概述
  • 通用解决方案
  • 垂直行业解决方案
  • 生活服务解决方案
  • 生活服务开发对接方案
  • 核销工具(不加价版)
  • 历史版本文档(不推荐使用)
  • 核销工具(不加价版)

    文档更新记录

    变动详细内容
    2023.11.02
    1、核销原生券接口新增 orderEntrySchema 字段,需要必接
    2、新增“推送服务完成”接口,需要必接!!
    2024.01.08
      1.核销原生券接口增加certificateBookInfoList、lockKey
      2.增加加解锁接口
      3.原生券信息查询接口返回值增加lock_info_list
    2024.01.16
      1.增加核销原生券open api

    1、交互流程

      由于网络波动等原因,可能会产生重复的核销结果通知消息,接入方需要做好幂等,正确处理。
      核销结果通知可能存在延时,开发者可以通过主动请求查询原生券信息接口,确认券核销结果。
      核销后需要调用推送服务完成接口将已核销的券推送到结算状态,推送结算之后不支持撤销核销。(次卡会在 1 小时后自动推送结算,无需调用接口)
      到店综合上门服务场景必须先加锁后核销。

    用户选券及门店

    核销原生券

      2.接入准备

    配置核销通知地址

    需要开发者登录抖音开放平台后台,在「核销工具解决方案」中完成「券核销通知」配置并发布上线。详细操作见解决方案配置指引

    配置行业SDK

    使用 JS-API 前需要在代码中配置行业 SDK 的权限:行业 SDK 的权限配置,行业 SDK 的权限配置在基础库 2.74.0.0 抖音版本 23.0 以上支持,API 用法跟原来一致。
    当完成行业 SDK 的权限配置后,可通过 tt.canIUse 判断该 API 是否可用。

    3、相关接口

    3.1 券信息查询接口

    3.1.1 用户抖音券资产查询 (openapi)

    根据用户open_id和商户account_id查询该用户在该商户下可用的抖音团购券列表。
    注意:目前只会返回抖音团购券、次卡类型订单,其他商品类型不会返回。

    3.1.2适用门店查询接口(openapi)

    查询某一个订单在某个poi_id门店是否可用(暂未提供批量返回适用POIID list的能力)

    3.1.3原生券信息查询(openapi)

    接口说明
    查询原生券的状态以及核销信息
    基本信息
    基本信息
    HTTP URL
    HTTP Method
    POST
    Scope
    industry_open.trade.certificate_query
    权限要求
    不需要用户授权
    请求头
    请求参数
    certificate_id_list或order_id_list二选一
    名称
    类型
    是否必填
    描述
    示例值
    certificate_id_list
    array(string)
    券id列表,券id小于等于30个,certificate_id_list或order_id_list二选一
    order_id_list
    array(string)
    订单 ID 列表(最多 10 个)
    请求示例
    curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/toolkit/query_certificate_info' \ --header 'Content-Type: application/json' \ --header 'access-token: clt.xxx' \ --data-raw='{ "order_id_list": [ "13887582744094", "1504928664094" ] }'
    响应参数
    名称
    类型
    是否必填
    描述
    示例值
    err_no
    int
    错误码
    13000
    err_msg
    string
    错误信息
    174192226280xxxx
    log_id
    string
    log_id(日志 ID),建议在问题描述中提供该标识
    2023082117CC91C30Fxxxxxx
    data
    Object
    返回信息,结构见data字段
    data字段
    字段名
    类型
    是否必填
    描述
    示例值
    certificate_info_list
    array(object)
    券信息,结构见certificate_info
    certificate_info字段
    字段名
    类型
    是否必填
    描述
    示例值
    order_id
    string
    订单id
    ttxxxxx
    certificate_id
    string
    券id
    status
    int32
    券状态
    0 : 初始化
    1 : 待履约
    2 : 履约中
    3 : 已履约
    4 : 履约完结(已结算)
    50 : 售后中
    5 : 履约关闭
    2
    verify_info_list
    array(object)
    核销信息,结构见verify_info
    times_card_info
    object
    次卡信息,结构见times_card_info
    lock_info_list
    array(object)
    锁信息,结构见lock_info
    verify_info字段
    字段名
    类型
    是否必填
    描述
    示例值
    verify_id
    string
    核销记录id,可用于撤销核销
    2314234
    verify_time
    int64
    核销时间,秒级时间戳
    times_card_info字段
    字段名
    类型
    是否必填
    描述
    示例值
    total_times
    int64
    总次数
    3
    used_times
    int64
    已用次数
    0
    locked_times
    int64
    被锁次数
    1
    lock_info字段
    字段名
    类型
    是否必填
    描述
    示例值
    lock_key
    string
    锁的key
    2314234
    响应示例
    { "err_msg": "", "err_no": 0, "log_id": "0216951939638021055da5f", "data": { "certificate_info_list": [ { "certificate_id": "724375050697789", "order_id": "100238388744094", "status": 1 }, { "certificate_id": "723733187837987", "order_id": "1001761528664094", "status": 2, "times_card_info": { "locked_times": 0, "total_times": 5, "used_times": 2 }, "verify_info_list": [ { "verify_id": "72366255352188987", "verify_time": 1684925371 }, { "verify_id": "72366855352205371", "verify_time": 1684925371 } ] } ] } }

    3.2 核销相关接口

    3.2.1 核销原生券(jsapi)

    核销后需通过推送服务将券推送至结算状态
    使用限制
    仅在行业 SDK 上才支持,需要在代码中配置行业 SDK 的权限:行业 SDK 的权限配置
    语法
    tt.verifyCertificates(options)
    参数说明
    options 为 object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    verifyToken
    string
    相同 token 的请求结果保持幂等,开发者自行生成,长度需大于 4 字节小于 64 字节
    行业sdk
    poiId
    string
    核销门店信息,核销原生券时需要门店信息
    行业sdk
    orderList
    OrderInfo[]
    订单信息
    行业sdk
    orderEntrySchema
    OrderEntrySchema
    订单详情页链接
    行业sdk
    success
    Function
    接口调用成功的回调函数
    行业sdk
    fail
    Function
    接口调用失败的回调函数
    行业sdk
    complete
    Function
    接口调用结束的回调函数(调用成功、失败都会执行)
    行业sdk
    OrderInfo
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    orderId
    string
    要核销的券所属订单
    行业sdk
    certificateList
    (string|TimesCard)[]
    券信息
      团购券和代金券直接传certificate_id
      次卡券需要传TimesCard结构
    行业sdk
    certificateBookInfoList
    LocalCertificateInfo[]
    包含预约券信息
    行业sdk
    lockKey
    string
    锁的key(如果次卡在未加锁的情况下传入该值,无法核销)
    行业sdk
    TimesCard
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    code
    string
    抵扣券ID,对应抖音原生团购券的certificate_id
    行业sdk
    times
    number
    次卡券必填,代表要核销的次数
    行业sdk
    OrderEntrySchema
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    path
    string
    订单详情页跳转路径,没有前导的"/",例如 "tt/order/detail"
    行业sdk
    params
    string
    订单详情页路径参数,自定义的json结构,例如"{\"id\":124231}"。
    注意"app_id"、"verify_token"是默认参数,跳转链接里会自动带上这两个参数,请不要额外指定
    行业sdk
    LocalCertificateInfo
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    certificateId
    string
    对应抖音原生团购券的certificate_id
    bookInfo
    BookInfo
    预约信息
    BookInfo
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    bookStartTime
    number
    预约开始时间(毫秒时间戳),须小于等于当前时间
    bookEndTime
    number
    预约结束时间(毫秒时间戳)
    回调成功
    object类型
    属性名
    类型
    说明
    最低支持版本
    orderVerifyResults
    orderVerifyResult[]
    订单维度核销结果
    orderVerifyResult
    属性名
    类型
    说明
    最低支持版本
    orderId
    string
    订单号
    certificateVerifyResults
    CertificateVerifyResult[]
    券码维度核销结果
    CertificateVerifyResult
    属性名
    类型
    说明
    最低支持版本
    resultCode
    number
    原生券核销结果状态码,0为成功,非0为失败。
    resultMsg
    string
    原生券核销结果
    certificateId
    string
    原生券id
    verifyTime
    number
    核销时间
    verifyId
    string
    券码一次核销的唯一标识。开发者可用于撤销核销
    code
    string
    核销用户的券码 code,核销成功后返回,需要联系运营加白
    回调失败
    object类型
    属性名
    类型
    是否一定存在
    说明
    最低支持版本
    errNo
    string
    错误码,对应信息可查看errNo说明
      159701 服务端错误
      159702 开发者错误
      150703 未在点击事件中调用
    errMsg
    string
    错误信息提示
    errLogId
    string
    非次卡请求示例
    tt.verifyCertificates({ verifyToken: 'xxx', // 幂等token 必传 poiId: 'xxx', // 核销门店Id 必传 orderList: [ // 订单信息 必传 { orderId: 'xxx', // 核销的券所属订单Id 必传 certificateList: [ // 抵扣券id,对应抖音原生团购券的certificate_id 必传 "12345" ] } ], orderEntrySchema: { // 订单详情页链接 必传 path: 'tt/order/detail', params: "{\"id\":124231}", }, success: res => { const { orderVerifyResults } = res; console.log('success res', res); console.log('orderVerifyResults', orderVerifyResults); this.setData({ orderVerifyResults }); } });
    次卡请求示例
    tt.verifyCertificates({ verifyToken: 'xxx', // 幂等token 必传 poiId: 'xxx', // 核销门店Id 必传 orderList: [ // 订单信息 必传 { orderId: 'xxx', // 核销的券所属订单Id 必传 certificateList: [ // 核销的券信息 { code: 'code1', // 抵扣券Id,对应抖音原生团购券的certificate_id 必传 times: 2, // 次卡券必填,代表要核销的次数 } ], } ], orderEntrySchema: { // 订单详情页链接 必传 path: 'tt/order/detail', params: "{\"id\":124231}", }, success: res => { const { orderVerifyResults } = res; console.log('success res', res); console.log('orderVerifyResults', orderVerifyResults); this.setData({ orderVerifyResults }); } });
    Bug & Tip
      开发者需要在点击事件回调中调用该 API,否则会报错
      需要确保用户处于登录态

    3.2.2券核销结果通知

    接口说明
      由于网络波动等原因,可能会产生重复的通知消息,接入方需要做好幂等,正确处理。
      回调可能存在延时,开发者可以通过主动请求查询原生券信息接口,确认券核销结果。
      在开发者服务端收到回调且处理成功后,需要按以下正常返回示例返回结果,并且将 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
    poi_id
    string
    核销门店的 poi_id
    860709246
    coupon_verify_results
    array(object)
    券核销结果,结构见coupon_verify_result
    order_info
    object
    小程序交易系统订单信息,仅交易系统版本有该字段
    verify_token
    string
    核销token,仅简化版有该字段
    verify_mode
    int
    不传或0,是交易系统版本核销
    1 是简化版本核销
    order_info 字段
    字段名
    类型
    是否必填
    描述
    示例值
    order_id
    string
    核销工具在小程序交易系统产生的订单号
    ots7057435515980663049
    order_source
    string
    订单来源标识
      核销工具订单:fulfillment_tool
    fulfillment_tool
    coupon_verify_result 字段
    字段名
    类型
    是否必填
    描述
    示例值
    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,仅简化版有该字段
    157435515980663049
    请求示例
    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":"ttd612a0af4d27b501", "poi_id":"71461459665500447", "verify_token":"zxst1t6", "coupon_verify_results":[ { "result_code":0, "result_msg":"履约成功", "certificate_id":"72437605050697789", "verify_id":"72812422564191289", "verify_time":1695296341, "code":"1007784595450", "order_id":"10023887582744094" } ], "verify_mode":1 }
    响应参数
    参数名称
    类型
    描述
    示例值
    err_no
    int64
    错误码
    0
    err_tips
    string
    错误提示
    success
    响应示例
    //正常返回响应且HTTP状态码为200 //注意: //正常返回时一定要保证err_no和err_tips为下面标准返回方式,不然都认为失败,将会重试 { "err_no": 0, "err_tips": "success" }

    3.2.3撤销核销(openapi)

    针对抖音来客券码误核销之后的撤销操作(仅限核销后1H内)

    3.2.4推送服务完成(openapi)

    接口说明
    将已核销的券推送到结算状态

    3.2.5加解锁接口(openapi)

    接口说明
    更改券的锁定状态,仅“到综进家”的商家可使用,且需要额外添加白名单(联系运营同学)。

    3.2.6 核销原生券(openapi)

    接口说明
    核销原生券接口,仅“到综进家”的商家可使用。
    核销后需通过推送服务将券推送至结算状态

    3.3 详情页展示相关接口

    3.3.1设置商家展示信息(openapi)

    修改商家引导文案、按钮文案、二维码展示方式等配置

    3.3.2查询商家配置文案(openapi)

    查询文案信息

    3.3.3设置订单详情页按钮白名单接口(openapi)

    控制抖音c端订单详情页跳转“核销工具”小程序去使用按钮可见性

    3.3.4设置小程序跳转path(openapi)

    用于设置c端详情页中用户点击按钮后跳转的页面