推送核销状态
收藏
我的收藏

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

使用限制

无

接口说明

•

只有三方码订单和泛知识同步履约状态，开发者才能使用此接口同步订单状态。

•

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

•

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

•

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

•

所有订单需要按照业务实际情况，向抖音平台推送正确的订单核销状态。若有特殊情况，无法向平台推送数据或遇到系统故障情况，开发者需要增加报警监控机制，及时感知系统异常，重试之后再次推送给抖音。

基本信息

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

请求头

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

请求参数

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

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

请求示例

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

响应参数

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

data 信息

名称	类型	是否必填	描述	示例值
delivery_id	string	否	核销记录id，签证交易下用于调用tt.confirm	ots72469746338730662849975

响应示例

正常示例

{
  "err_no": 0,
  "err_tips": "success"
}

异常示例

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

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	11001	访问未授权	请求的小程序和订单的小程序不匹配。
200	21111	此订单不允许推送核销状态，请使用闭环核销方案核销	抖音码核销订单不能使用此接口推送核销状态。
200	21000	商品单与商户单不匹配	item_order_list 中的商品单 id 非 out_order_no 关联的子单。
200	21001	商品单状态不支持核销	子单状态不符合可核销要求，请查询商品单信息，只有商品单状态为待使用状态才可核销。
200	21116	预约商品不允许推送核销状态	预约类商品不能通过此接口推送核销状态。

推送核销状态收藏我的收藏

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​item_order_list 信息​

​poi_info 信息。​

​请求示例​

​响应参数​

​data 信息​

​响应示例​

​正常示例​

​异常示例​

​错误码​