验券

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

使用限制​

无​

接口说明​

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

基本信息​

基本信息
HTTP URL
HTTP Method
POST
Scope
industry_open.trade.certificate_delivery
权限要求
不需要用户授权

请求头​

参考通用参数

请求参数​

名称​
类型​
是否必填​
描述​
示例值​
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​
否​
核销店铺名称,团购类商品库商品下单的订单必填。​
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 信息​

名称​
类型​
是否必填​
描述​
示例值​
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​

result_code 不同值的含义​

值​
result_msg​
含义​
0​
验券成功​
成功​
1208​
券码已核销​
代表券码已核销。短时间内的重试请求可能会返回1208,可当做成功处理。​
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 } ] }, "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 参数是否正确,例如order_id错误,或者order_id和请求的小程序不匹配。​
200​
21001​
商品单状态不支持核销​
订单状态不符合可核销预期,检查是否处于退款中、已退款等状态。​