基础能力

触达与营销

支付

运营

生活服务

通用能力

生活服务交易系统（全融合版）

通用参数

错误码和返回码

查询接口

预下单

营销算价

支付

核销

抖音码

三方码

推送核销状态

撤销核销

分账

退货退款

生活服务交易系统（账号融合版）

CPS佣金设置与查询

随心团解决方案

核销工具解决方案

历史版本（不推荐使用）

垂直行业

其它

推送核销状态

我的收藏

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

使用限制

无

接口说明

•

只有三方码订单，开发者才能使用此接口同步订单的核销状态。

•

交易系统的订单，在开发者系统完成核销后，开发者可通过此接口同步核销状态，完成订单在开放平台交易系统内的状态流转。

•

此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 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"}]`
token	string	否	次卡必填：请求标识，幂等	easy123
use_all	bool	否	是否将整个订单核销。此参数设为 true 则将此订单的所有子单核销。 use_all 和 item_order_list 必须有一个有效值，要么指定 use_all=true 整单核销，要么使用 item_order_list 指定特定的商品单 id 核销。注意：此参数设为 true 时只有 out_order_no 的所有商品单都为待使用状态才能成功核销，到综预约品拆单或整单核销都需要传true。	false
poi_info	string	是	核销的商铺 POI 信息，最多 1024 个字节。注意：此字段为 string 类型，按下面结构填入所需字段后序列化成 string。全融合场景必填	`"{\"shop_name\":\"xx门店\",\"ext_valid_shop_id\":\"x0001\",\"valid_poi_id_str\":\"6601136930455291912\"}"`
book_id	string	否	预约单(预约订单推送核销时必传)

item_order_list 信息

名称	类型	是否必填	描述	示例值
item_order_id	string	是	需要核销的商品单 id	80123
times_no_list	array(string)	否	次卡必填：次卡请求流水号，list长度和核销次数相等，例如核销次卡2次需传两个流水号，该流水号是开发者通过发码通知接口(code_list)回传给抖音的。	[ "zj999", "zj999" ]

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/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\"}"
}'

次卡订单核销请求示例

curl --location 'https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data '{
"out_order_no":"12345",
"item_order_list":[
{
"item_order_id":"80012345678",
"times_no_list":[  //传入多个code，代表核销多次
    "123",
    "123"
]
}
],
"use_all":true,
"token" : "1084695816619868380",//开发者自定义，需保证幂等
"poi_info":"{\"shop_name\":\"测试门店\",\"ext_valid_shop_id\":\"001\",\"valid_poi_id_str\":\"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='{
"book_id":"123456",
"use_all":true,
"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	商品单状态不支持核销	子单状态不符合可核销要求。