验券准备
收藏
抖音码订单的核销，需要调用两个接口。先调用验券准备接口，获得加密券码等信息后，再调用验券实现核销。 验券准备接口会返回可用券列表。开发者自行选择需要核销的券数据传入验券接口进行核销。
使用限制
无
接口说明
- 验券准备接口可传入两种类型的券码：
- code：即用户券码。用户券码是在订单详情页使用核销组件展示的券码，通常为 12 位数字。
- encrypted_data：此参数的获取方式为，扫描核销组件展示的二维码，获取二维码对应的字符串信息。此二维码对应的字符串信息是如下的一个 URL 链接
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 |
权限要求 |
|
请求头
名称 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
Content-Type | string | 是 | 固定值 "application/json" |
access-token | string | 是 | 调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.xxx |
请求参数
注意：encrypted_data 和 code 二选一，有一个必填。
名称 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|
encrypted_data | string | 否 | 从二维码解析出的 encrypted_data | 17104CFF079C9FDA51D14DD48E12876C |
code | string | 否 | 用户券码 | 888888888888 |
请求示例
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 信息
名称 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|
error_code | int | 是 | 错误码，0为成功 | 0 |
description | string | 是 | 错误码描述 | success |
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 |
响应示例
正常示例
{ "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" } }
异常示例
{ "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 状态码 | 错误码 sub_error_code | 描述 | 排查建议 |
|---|---|---|---|
200 | 10000 | 参数错误 | 参数不符合规范。请根据提示检查参数。 |
200 | 13000 | 系统错误，请重试 | 内部错误，重试可解决。 |
200 | 13000 | 非生活服务券码 | 非有效券码。 非法券码或者券码已被核销或退款，不能使用时则会提示。 |
