接口说明

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

只有三方码订单，开发者才能使用此接口同步订单的核销状态（三方码权限核对：开放平台 - 控制台 - 小程序应用 - 解决方案 - 生活服务 - 按照接入行业选择 - 【KA】三方码接入能力）。
交易系统的订单，在开发者系统完成核销后，开发者可通过此接口同步核销状态，完成订单在开放平台交易系统内的状态流转。
此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 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

调用https://open.douyin.com/oauth/client_token/生成的token

content-type必填String

固定值"application/json"

Rpc-Transit-Life-AccountString

来客商户根账户ID

Body展开全部子属性

book_idString

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

若订单为即时预约，book_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 状态码	错误码	错误码描述	排查建议
200	2100001	未知错误	重试接口，重试3次仍报错联系抖音生活服务技术支持
200	2100004	系统繁忙，此时请开发者稍候再试	重试接口，重试3次仍报错联系抖音生活服务技术支持
200	2100005	参数不合法	更换参数
200	2119001	参数不合法	更换参数
200	2119002	系统繁忙，请稍候再试	重试
200	2119003	请求太过频繁，请稍后再试	重试
200	2119005	应用未获商家授权	联系合作商家在商家后台发起授权，并在服务商后台同意授权
200	2190002	access_token无效	调用接口重新生成access_token
200	2190004	应用未获得该能力, 请去https://open.douyin.com/申请	应用申请接口权限
200	2190008	access_token过期,请刷新或重新授权	规范token刷新机制，检查是否有测试环境在同步刷新token
200	3000001	根据实际业务错误返回	对照接口文档规范参数并重试
200	5000001	根据实际业务错误返回	联系抖音处理

补充多场景请求示例：

次卡核销示例：

curl --location 'https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery?=null' \

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

}'

非次卡核销示例：

curl --location 'https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery?=null' \

--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

}'

预约订单核销示例：

curl --location 'https://open.douyin.com/api/apps/trade/v2/fulfillment/push_delivery?=null' \

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

}'

开发者文档

推送核销状态

接口说明

基本信息

请求参数

响应参数

错误码

补充多场景请求示例：

次卡核销示例：

非次卡核销示例：

预约订单核销示例：

推送核销状态在线调试

接口说明

基本信息

请求参数

响应参数

错误码

补充多场景请求示例：

次卡核销示例：

非次卡核销示例：

预约订单核销示例：

推送核销状态