推送核销状态

更新时间 2024-07-24 02:58:49

我的收藏

该接口用于同步订单的核销状态到开放平台。

使用限制

无

接口说明

•

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

•

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

•

此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 item_order_id 核销，即子单核销。

•

只有状态符合可核销预期的才能正常核销。不同订单类型可能有不同的预期，比如，团购券订单，只有待使用状态才能核销，退款中或已退款的将返回错误。

基本信息

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

请求头

参考通用参数

请求参数

名称	类型	是否必填	描述	示例值
out_order_no	string	是	开发者系统内的交易单号，称为外部单号。	out123456
item_order_list	array(object)	否	指定需要核销的子单列表，此列表内的子单必须是上面 out_order_no 订单所对应的子单。 use_all 和 item_order_list 必须有一个有效值，要么指定 use_all=true 整单核销，要么使用 item_order_list 指定特定的商品单 id 核销。 object 结构内的字段见下面介绍。注意：1.限制数组长度 <= 10; 2.非次卡交易不需要传times_no_list; 3.签证交易当前仅支持传单个item_order。	`[` `{` `"item_order_id":"t1",` `"times_no_list":[` `"zj999",` `"zj998"` `]` `},` `{` `"item_order_id":"t2",` `"times_no_list":[` `"zj997",` `"zj996"` `]` `}` `]`
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\"}"`
delivery_status	int	否	签证交易以及泛知识接入交易规则必传： 1：推送子单状态到“履约中” 2：推送子单状态到“履约完成” 签证交易中，字段含义为： 1：子单状态变为“签证结果已出 ” 2：子单状态变为“确认签证结果” 注意： •状态变为“签证结果已出”后，可调用tt.confirm让用户发起签证结果确认 •状态变为“签证结果已出”14天后开发者可传入"2: 确认签证结果”帮助用户确认。tt.confirm不限制。

item_order_list 信息

名称	类型	是否必填	描述	示例值
item_order_id	string	是	需要核销的商品单 id。	ot123
times_no_list	array(string)	否	次卡必填：次卡请求流水号，list长度和核销次数相等，例如核销次卡2次需传两个流水号，该流水号做幂等使用。	[ "zj999", "zj998" ]

poi_info 信息。

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

名称	类型	是否必填	描述	示例值
shop_name	string	否	核销店铺名称，团购类商品库商品下单的订单必填。	xx 门店
ext_valid_shop_id	string	否	核销门店的外部店铺 id，团购类商品库商品下单的订单必填。	x0001
valid_poi_id_str	string	否	核销门店对应的抖音 poi_id，团购类商品库商品下单的订单必填。	6601136930455291912

请求示例

text复制
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
delivery_id	string	否	核销记录id，签证交易下用于调用tt.confirm	ots72469746338730662849975

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

响应示例

正常示例

json复制
{
  "data": {
    "error_code": 0,
    "description": "success",
    "delivery_id": "ots72469746338730662849975"
  },
  "extra": {
    "sub_error_code": 0, 
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

json复制
{
  "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	预约商品不允许推送核销状态	预约类商品不能通过此接口推送核销状态。