抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台

推送核销状态

收藏
我的收藏

接口说明

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

  • 只有三方码订单,开发者才能使用此接口同步订单的核销状态(三方码权限核对:开放平台 - 控制台 - 小程序应用 - 解决方案 - 生活服务 - 按照接入行业选择 - 【KA】三方码接入能力)。
    • 非三方码订单调用该接口会提示:此订单不允许推送核销状态,请使用闭环核销方案核销。请开发者通过预下单扩展点cp_delivery_type字段来控制订单走三方码链路。
  • 交易系统的订单,在开发者系统完成核销后,开发者可通过此接口同步核销状态,完成订单在开放平台交易系统内的状态流转。
  • 此接口支持推送整个订单的核销完成状态,也支持指定订单中的某个或者几个 item_order_id 核销,即子单核销。
  • 只有状态符合可核销预期的才能正常核销。 不同订单类型可能有不同的预期,比如,团购券订单,只有待使用状态才能核销,退款中或已退款的将返回错误。
  • 预约订单核销推送前提:预约单已接单;订单预约状态通过查询预约单信息接口查询判断
  • 调用该接口核销时不能早于创建预约单的book_start_time预约开始时间。
  • 待支付、退款中、退款完成订单不可推送核销,推送前调用过查询订单信息接口判断订单状态。

基本信息

名称描述
HTTP URL
https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery/
HTTP Method
POST
Scope
industry_open.trade.delivery

请求参数

请求头
access-token必填String
示例:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
固定值"application/json"
Rpc-Transit-Life-AccountString

来客商户根账户ID

Body展开全部子属性
book_idString

预约单id(预约订单推送核销时必传)

delivery_extraStruct
核销扩展信息
展开子属性
delivery_statusEnum

本次核销批量推送的状态

签证交易以及泛知识接入交易规则必传:

1:推送子单状态到“履约中”

2:推送子单状态到“履约完成”

​

签证交易中,字段含义为:

1:子单状态变为“签证结果已出 ”

2:子单状态变为“确认签证结果”

注意:

  • 状态变为“签证结果已出”后,可调用tt.confirm让用户发起签证结果确认
  • 状态变为“签证结果已出”14天后开发者可传入"2: 确认签证结果”帮助用户确认。tt.confirm不限制。
展开子属性
item_book_listList

指定需要核销的子单列表,此列表内的子单必须是上面 out_order_no 订单所对应的子单(次卡核销,该参数必填)

object 结构内的字段见下面介绍。

限制数组长度 <= 100

展开子属性
item_order_listList
out_order_no所关联的需要核销的商品单信息,详细结构见下表。可使用此参数指定核销整单中的特定商品单和核销次数。 长度<=100
展开子属性
out_order_noString
示例:xxxx

开发者系统内的交易单号,称为外部单号。

poi_infoString
示例:{"shop_name":"shop_name","ext_valid_shop_id":"01","valid_poi_id_str":"56"}

核销的商铺 POI 信息,最多 1024 个字节。

注意:

1.全融合场景下该结构体为必填,其中 shop_name、ext_valid_shop_id、valid_poi_id_str 全部不可为空,需传入商家系统对应门店数据,缺失或传空将触发接口报错。

2.该字段为 string 类型,按示例结构填入所需字段后序列化成 string。

tokenString

次卡场景请求幂等(次卡必填)

use_allBool
示例:false

是否整单核销。此参数设为 true 则将此订单的所有子单核销。

use_all 和 item_order_list 必须有一个有效值,要么指定 use_all=true 整单核销,要么使用 item_order_list 指定特定的商品单 id 核销。

注意:此参数设为 true 时只有 out_order_no 的所有商品单都为待使用状态才能成功核销,到综预约品拆单或整单核销都需要传true。

请求示例
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery/' \ --header 'access-token: 0801121846735352506a356a6' \ --header 'content-type: application/json' \ --data '{"delivery_status":1,"delivery_extra":{"out_shop_name":"TmHw1n09Rc","out_shop_id":"42pFbahuLE","server_name":"8ePv1kHUgO","server_phone_num":"cDLFbQPrn0"},"item_book_list":[{"item_book_id":"ot123","times_no_list":["C3v9c5u0U4"]}],"token":"QSX41gSyEN","out_order_no":"xxxx","book_id":"P3CEvj29V1","item_order_list":[{"times_no_list":["TTBalpc6ce"],"external_extra":[{"order_id":"2p7ngCutAu","cert_no":"gjcXLUwO21"}],"item_order_id":"xxx"}],"poi_info":"{\"shop_name\":\"shop_name\",\"ext_valid_shop_id\":\"01\",\"valid_poi_id_str\":\"56\"}","use_all":false}'

响应参数

Body展开全部子属性
extra必填Struct
扩展信息
展开子属性
dataStruct
返回数据信息
展开子属性
响应示例
正常响应示例异常响应示例
{ "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "202507141152545BB529A53D850FEA2994", "now": 1752465175 }, "data": { "verify_results": [ { "verify_time": 581317523721416300, "item_order_id": "ot123", "item_book_id": "ot123", "verify_id": "31736183", "certificate_id": "817392739" } ], "delivery_id": "ZqaIb7lA7J", "error_code": 0, "description": "" } }
切换单列布局

错误码

HTTP 状态码错误码错误码描述排查建议
2002100001
未知错误
重试接口,重试3次仍报错联系抖音生活服务技术支持
2002100004
系统繁忙,此时请开发者稍候再试
重试接口,重试3次仍报错联系抖音生活服务技术支持
2002100005
参数不合法
更换参数
2002119001
参数不合法
更换参数
2002119002
系统繁忙,请稍候再试
重试
2002119003
请求太过频繁,请稍后再试
重试
2002119005
应用未获商家授权
联系合作商家在商家后台发起授权,并在服务商后台同意授权
2002190002
access_token无效
调用接口重新生成access_token
2002190004
应用未获得该能力, 请去https://open.douyin.com/申请
应用申请接口权限
2002190008
access_token过期,请刷新或重新授权
规范token刷新机制,检查是否有测试环境在同步刷新token
2003000001
根据实际业务错误返回
对照接口文档规范参数并重试
2005000001
根据实际业务错误返回
联系抖音处理

补充多场景请求示例:

次卡核销示例:

--header 'Content-Type: application/json' \
--header 'Cookie: passport_csrf_token=9c78a4f1f28f47efeb969a2329080465; passport_csrf_token_default=9c78a4f1f28f47efeb969a2329080465' \
--header 'access-token: {{access_token}}' \
--data '{
"out_order_no": "ext_1090125315717144968",
"item_order_list": [
{
"item_order_id": "8000127046851960066138349681",
"times_no_list": [
"1090125315717144968" //次卡核销多次时,需传入多个times_no_list
]
}
],
"token": "ext_10901253157171449681",
"use_all": true,
"poi_info": "{\"shop_name\":\"0\",\"ext_valid_shop_id\":\"0\",\"valid_poi_id_str\":\"0\"}"
}'
​

非次卡核销示例:

--header 'Content-Type: application/json' \
--header 'Cookie: passport_csrf_token=9c78a4f1f28f47efeb969a2329080465; passport_csrf_token_default=9c78a4f1f28f47efeb969a2329080465' \
--header 'access-token: {{access_token}}' \
--data '{
"item_order_list": [
{
"item_order_id": "800012708919576192213154968"
}
],
"out_order_no": "ext_1090151814377944968",
"poi_info": "{\"valid_poi_id_str\":\"0\",\"shop_name\":\"0\",\"ext_valid_shop_id\":\"0\"}",
"use_all": true
}'
​

预约订单核销示例:

--header 'Content-Type: application/json' \
--header 'Cookie: passport_csrf_token=9c78a4f1f28f47efeb969a2329080465; passport_csrf_token_default=9c78a4f1f28f47efeb969a2329080465' \
--header 'access-token: {{access_token}}' \
--header 'x-janus-log: debug' \
--data '{
"book_id": "800012847194768256216964968", //预约单号/加价单号
"use_all": true,
"poi_info": "{\"shop_name\":\"123\",\"ext_valid_shop_id\":\"123\",\"valid_poi_id_str\":\"123\"}"
}'