验券
收藏
我的收藏

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

使用限制

无

接口说明

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

基本信息

基本信息
HTTP URL	https://developer.toutiao.com/api/apps/trade/v2/delivery_verify
HTTP Method	POST
权限要求	无

请求头

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

请求参数

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

请求示例

js复制
curl --location --request POST 'https://developer.toutiao.com/api/apps/trade/v2/delivery_verify' \
--header 'Content-Type: application/json' \
--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\"}"
}'

响应参数

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

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	其他错误	检查券码有效期。如果券码不在有效期范围内，将会返回此错误。不在有效期内不能核销。

响应示例

正常示例

json复制
{
  "err_no": 0,
  "err_tips": "success",
  "data": {
    "verify_results": [
      {
        "item_order_id": "ot123",
        "certificate_code": "888888888888",
        "result_code": 0,
        "result_msg": "验券成功",
        "verify_time": 1658300479000
      }
    ]
  }
}

异常示例

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

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	11001	访问未授权	请求的小程序和订单的小程序不匹配。
200	20000	订单不存在	检查传入的 order_id 参数是否正确。
200	21001	商品单状态不支持核销	商品单状态不符合可核销要求，请查询商品单信息，只有商品单状态为待使用状态才可核销。