推送核销状态
收藏
该接口用于同步订单的核销状态到交易系统。
使用限制
无
接口说明
- 只有三方码订单，开发者才能使用此接口同步订单的核销状态。
- 交易系统的订单，在开发者系统完成核销后，开发者可通过此接口同步核销状态，完成订单在开放平台交易系统内的状态流转。
- 此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 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 订单所对应的子单。 |
|
use_all | bool | 否 | 是否将整个订单核销。此参数设为 true 则将此订单的所有子单核销。 | false |
poi_info | string | 否 | 核销的商铺 POI 信息，最多 1024 个字节。 |
|
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://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 |
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 | 商品单状态不支持核销 | 子单状态不符合可核销要求。 |
200 | 21116 | 预约商品不允许推送核销状态 | 预约类商品不能通过此接口推送核销状态。 |
