抖音开放平台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 字段若存在值,即表示订单已加锁。
    字段名
    类型
    是否必填
    描述
    示例值
    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端详情页中用户点击按钮后跳转的页面