验券

我的收藏

请求验券准备接口后，开发者自行选择需要核销的可用券信息传入此验券接口，完成核销操作。

使用限制

无

接口说明

本接口的传入参数，请参考验券准备的返回参数。

基本信息

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

请求头

参数名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"
access-token	string	是	调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.xxx

请求参数

名称	类型	是否必填	描述	示例值
verify_token	string	是	验券标识，从验券准备接口获取的，用于幂等。	xxx
order_id	string	是	交易系统单号，从验券准备接口获取。	ot123456
certificates	array(object)	是	验券准备接口返回的加密券码，传入几份表示核销几份。	[{"encrypted_code":"xxx", "certificate_id":"123456"}]
poi_info	string	否	核销的商铺 POI 信息，最多 1024 个字节。注意：商品库商品下单的订单必填。此字段为 json string，按下面结构填入所需字段后序列化成 string。	"{\"shop_name\":\"xx门店\",\"ext_valid_shop_id\":\"x0001\",\"valid_poi_id_str\":\"6601136930455291912\"}"

certificates 信息

名称	参数类型	是否必填	参数描述	示例值
encrypted_code	string	是	加密券码	xxx
certificate_id	string	是	券 id	123456

poi_info 信息

团购类商品库商品下单的订单必填所有字段（强校验）。请尽量传入真实的核销门店信息，这对订单后续的评价、内部转化等都有积极作用。

名称	类型	是否必填	描述	示例值
shop_name	string	否	核销店铺名称，参考商铺同步接口中的店铺名称（name）字段。团购类商品库商品下单的订单必填。	xx 门店
ext_valid_shop_id	string	否	核销门店的外部店铺 id，参考商铺同步接口中的接入方店铺 id（supplier_ext_id）字段团购类商品库商品下单的订单必填。	x0001
valid_poi_id_str	string	否	核销门店对应的抖音 poi_id，参考商铺同步接口中的抖音 poi_id 字段团购类商品库商品下单的订单必填。	6601136930455291912

请求示例

curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/fulfillment/delivery_verify' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
   "verify_token":"xxx",
   "order_id":"ot123456",
   "certificates":[
      {
         "encrypted_code":"xxx",
         "certificate_id":"123456"
      }
   ],
   "poi_info":"{\"shop_name\":\"xx门店\",\"ext_valid_shop_id\":\"x0001\",\"valid_poi_id_str\":\"6601136930455291912\"}"
}'

响应参数

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

data 信息

名称	类型	是否必填	描述	示例值
error_code	int	是	错误码，0为成功	0
description	string	是	错误码描述	success
verify_results	array(object)	是	数组，每个券的验券结果

verify_results 信息

名称	类型	是否必填	描述	示例值
result_code	number	是	验券结果码，0 表示成功	0
result_msg	string	是	验券结果 result_code 的说明	验券成功
verify_time	number	是	核销时间，13 位毫秒级时间戳	1658300479000
item_order_id	string	是	交易系统里对应的商品单 id	ot123
certificate_code	string	否	用户券码，核销成功时会将用户券码返回。开发者可用于对账。	888888888888
verify_id	string	是	代表券码一次核销的唯一标识。开发者可用于撤销核销	83717297362537

result_code 不同值的含义

值	result_msg	含义
0	验券成功 / 券码已核销	验券成功。或券码已经核销，返回券码已核销。
1211	其他错误	检查券码有效期。如果券码不在有效期范围内，将会返回此错误。不在有效期内不能核销。

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_results": [
      {
        "item_order_id": "ot123",
        "certificate_code": "888888888888",
        "result_code": 0,
        "result_msg": "验券成功",
        "verify_time": 1658300479000,
        "verify_id": "83717297362537"
      }
    ]
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	11001	访问未授权	请求的小程序和订单的小程序不匹配。
200	20000	订单不存在	检查传入的 order_id 参数是否正确。
200	21001	商品单状态不支持核销	订单状态不符合可核销预期，检查是否处于退款中、已退款等状态。

下一篇：小程序文档指引