验券准备

收藏

我的收藏

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

使用限制

无

接口说明

• 验券准备接口可传入两种类型的券码：
• 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://developer.toutiao.com/api/apps/trade/v2/delivery_prepare
HTTP Method	POST
权限要求	无

请求头

名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"
Byte-Authorization	string	是	请参见签名算法

请求参数

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

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

请求示例

curl --location --request POST 'https://developer.toutiao.com/api/apps/trade/v2/delivery_prepare' \
--header 'Content-Type: application/json' \
--data-raw='{
"encrypted_data":"17104CFF079C9FDA51D14DD48E12876C",
"code": ""
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	number	是	错误码，0 为成功	0
err_tips	string	是	错误提示信息	success
data	object	是	返回数据	success

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

响应示例

正常示例

{
  "err_no": 0,
  "err_tips": "success",
  "data": {
    "verify_token": "xxx",
    "out_order_no": "out123456",
    "order_id": "ot123456",
    "certificates": [
      {
        "encrypted_code": "xxx",
        "certificate_id": "123456",
        "item_order_id": "ot123"
      }
    ]
  }
}

异常示例

{
  "err_no": 13000,
  "err_tips": "系统错误"
}

错误码

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