推送核销状态

我的收藏

该接口用于同步订单的核销状态到交易系统。

使用限制

无

接口说明

只有三方码订单，开发者才能使用此接口同步订单的核销状态。
交易系统的订单，在开发者系统完成核销后，开发者可通过此接口同步核销状态，完成订单在开放平台交易系统内的状态流转。
此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 item_order_id 核销，即子单核销。
只有状态符合可核销预期的才能正常核销。不同订单类型可能有不同的预期，比如，团购券订单，只有待使用状态才能核销，退款中或已退款的将返回错误。

基本信息

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

请求头

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

请求参数

名称	类型	是否必填	描述	示例值
out_order_no	string	是	开发者系统内的交易单号，称为外部单号。	out123456
item_order_list	array(object)	否	指定需要核销的子单列表，此列表内的子单必须是上面 out_order_no 订单所对应的子单。 object 结构内的字段见下面介绍。限制数组长度 <= 100	`[{"item_order_id":"ot123"},{"item_order_id":"ot456"}]`
use_all	bool	否	是否将整个订单核销。此参数设为 true 则将此订单的所有子单核销。 use_all 和 item_order_list 必须有一个有效值，要么指定 use_all=true 整单核销，要么使用 item_order_list 指定特定的商品单 id 核销。注意：此参数设为 true 时只有 out_order_no 的所有商品单都为待使用状态才能成功核销。	false
poi_info	string	否	核销的商铺 POI 信息，最多 1024 个字节。注意：此字段为 string 类型，按下面结构填入所需字段后序列化成 string。	`"{\"shop_name\":\"xx门店\",\"ext_valid_shop_id\":\"x0001\",\"valid_poi_id_str\":\"6601136930455291912\"}"`

item_order_list 信息

名称	类型	是否必填	描述	示例值
item_order_id	string	是	需要核销的商品单 id	ot123

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

名称

类型

是否必填

描述

示例值

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/push_delivery' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
"out_order_no":"out123456",
"item_order_list":[
{
"item_order_id":"ot123"
},
{
"item_order_id":"ot456"
}
],
"use_all":false,
"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 信息

名称	类型	是否必填	描述	示例值
verify_time	number	是	核销时间，13 位毫秒级时间戳	1658300479000
item_order_id	string	是	交易系统里对应的商品单 id	ot1232342423
certificate_id	string	是	代表一张券码的标识	888888888888
verify_id	string	是	代表券码一次核销的唯一标识。开发者可用于撤销核销	83717297362537

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": [
      {
        "certificate_id": "7225579753535704",
        "item_order_id": "80000000613679534",
        "verify_id": "72255394060460",
        "verify_time": 1682341467000
      },
      {
        "certificate_id": "722557935766572",
        "item_order_id": "80000000026899213749534",
        "verify_id": "72255390118243228",
        "verify_time": 1682341467000
      }
    ]
  },
  "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	21111	此订单不允许推送核销状态，请使用闭环核销方案核销	抖音码核销订单不能使用此接口推送核销状态。
200	21000	商品单与商户单不匹配	item_order_list 中的商品单 id 非 out_order_no 关联的子单。
200	21001	商品单状态不支持核销	子单状态不符合可核销要求。
200	21116	预约商品不允许推送核销状态	预约类商品不能通过此接口推送核销状态。

下一篇：小程序文档指引