核销工具(不加价版)
核销工具(不加价版)
文档更新记录
| 变动详细内容 |
2023.11.02 | 1、核销原生券接口新增 orderEntrySchema 字段,需要必接 2、新增“推送服务完成”接口,需要必接!! |
2024.01.08 |
|
2024.01.16 |
|
1、交互流程
- •由于网络波动等原因,可能会产生重复的核销结果通知消息,接入方需要做好幂等,正确处理。
- •核销结果通知可能存在延时,开发者可以通过主动请求查询原生券信息接口,确认券核销结果。
- •核销后需要调用推送服务完成接口将已核销的券推送到结算状态,推送结算之后不支持撤销核销。(次卡会在 1 小时后自动推送结算,无需调用接口)
- •到店综合上门服务场景必须先加锁后核销。
用户选券及门店
核销原生券
2.接入准备
配置核销通知地址
需要开发者登录抖音开放平台后台,在「核销工具解决方案」中完成「券核销通知」配置并发布上线。详细操作见解决方案配置指引
配置行业SDK
当完成行业 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)
核销后需通过推送服务将券推送至结算状态
使用限制
语法
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)[] | | 否 | 券信息
| 行业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说明
| |
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 |
