验券准备

更新时间 2024-07-24 02:58:49

我的收藏

抖音码订单的核销，需要调用两个接口。先调用验券准备接口，获得加密券码等信息后，再调用验券实现核销。验券准备接口会返回可用券列表。开发者自行选择需要核销的券数据传入验券接口进行核销。

使用限制

•

使用抖音码核销能力请先和对接运营申请开通权限，否则会默认走三方码核销

•

使用抖音码核销，需要通过JSAPI下单或者模板组件下单

◦

JSAPI下单需要在tt.createOrder的callbackData字段中增加{"use_trade_delivery": 1}

◦

模板组件下单需要在pay-button的bind:getgoodsinfo的extra字段中增加{"use_trade_delivery": 1}

接口说明

•

验券准备接口可传入两种类型的券码：

◦

code：即用户券码。用户券码是在订单详情页使用核销组件展示的券码，通常为 12 位数字。

◦

encrypted_data：此参数的获取方式为，扫描核销组件展示的二维码，获取二维码对应的字符串信息。此二维码对应的字符串信息是如下的一个 URL 链接

text复制
https://developer.toutiao.com/api/apps/trade/v2/share?encrypted_data=17104CFF079C9FDA51D14DD48E12876C&app_id=tt123456&out_order_no=out123456

取出此长链接 query 参数中的 encrypted_data 参数即可。

•

请只感知上面的 URL 链接中的 query 参数， URL 的域名、路径等信息请不要感知，以后都有调整的可能。

•

当二维码刷新不出来时可将用户券码保存作为 code 参数调用此接口。

•

encrypted_data 和 code 必须有一个有效值，当两个都传入时，会优先使用 encrypted_data 参数。

注意：一个二维码对应的是整个订单。如果此订单中的任一子单产生了状态变化，比如发起退款、退款完成、核销完成等操作，会导致二维码数据产生更新。此时如果继续传入变更前的二维码 encrypted_data 数据，会报错提示二维码已失效。如果订单没有任何子单状态变化，最短有 3 天有效期。用户每次打开/刷新二维码都会延长 3 天有效期。

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/apps/trade/v2/fulfillment/delivery_prepare
HTTP Method	POST
Scope	industry_open.trade.certificate_delivery
权限要求	•需要Scope权限 •不需要用户授权

请求头

参考通用参数

请求参数

注意：encrypted_data 和 code 二选一，有一个必填。

名称	类型	是否必填	描述	示例值
encrypted_data	string	否	从二维码解析出的 encrypted_data	17104CFF079C9FDA51D14DD48E12876C
code	string	否	用户券码	888888888888

请求示例

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/fulfillment/delivery_prepare' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
"encrypted_data":"17104CFF079C9FDA51D14DD48E12876C",
"code": ""
}'

响应参数

名称	类型	是否必填	描述	示例值
data	object	是	返回数据
extra	object	是	额外信息

data 信息

名称	类型	是否必填	描述	示例值
verify_token	string	是	一次验券的标识，在验券接口传入	xxx
out_order_no	string	是	外部单号，开发者系统的交易单号	out123456
order_id	string	是	交易系统单号	ot123456
certificates	array(object)	是	可用券列表	success

certificates 信息

名称	类型	是否必填	描述	示例值
encrypted_code	string	是	加密券码。在验券接口传入	xxx
certificate_id	string	是	券 id，在验券接口传入	123456
item_order_id	string	是	交易系统里对应的商品单 id	ot123

extra 信息

名称	类型	是否必填	描述	示例值
error_code	int	是	错误码，0为成功	0
description	string	是	错误码描述	success
sub_error_code	int	是	子错误码	0
sub_description	string	是	子错误码描述	success
logid	string	是	请求id	2022092115392201020812109511046
now	int	是	毫秒级时间戳	1663745962686

响应示例

正常示例

json复制
{
  "data": {
    "error_code": 0,
    "description": "success",
    "verify_token": "xxx",
    "out_order_no": "out123456",
    "order_id": "ot123456",
    "certificates": [
      {
        "encrypted_code": "xxx",
        "certificate_id": "123456",
        "item_order_id": "ot123"
      }
    ]
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  } 
}

异常示例

json复制
{
  "data": {
    "error_code": 2190004,
    "description": "应用未获得该能力, 请去https://open.douyin.com/申请"
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686, 
    "error_code": 2190004,
    "description": "应用未获得该能力, 请去https://open.douyin.com/申请"
  }
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	13000	参数错误，请刷新二维码	encrypted_data 参数无效。检查 encrypted_data 是否正确。
200	13000	二维码数据已失效。	任一子单的状态变化都会导致现有的二维码数据失效。
200	13000	无券信息	code 参数无效。不属于开平交易系统的订单 code。请注意与抖音原生码区分。
200	13000	非生活服务券码	非有效 code 或者 code 已被核销或退款，不能使用时则会提示。