抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • OpenAPI 简介
  • 通用参数
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 运营
  • 生活服务
  • 通用能力
  • 生活服务交易系统(全融合版)
  • 生活服务交易系统(账号融合版)
  • 错误码和返回码
  • 通用参数
  • 预约
  • 查询接口
  • 预下单
  • 营销算价
  • 支付
  • 核销
  • 抖音码
  • 三方码
  • 推送核销状态
  • 核销工具
  • 分账
  • 退货退款
  • CPS佣金设置与查询
  • 即送(原随心团)解决方案
  • 核销工具解决方案
  • 历史版本(不推荐使用)
  • 垂直行业
  • 其它
  • 该接口用于同步订单的核销状态到开放平台。

    使用限制

    无

    接口说明

      •只有三方码订单,开发者才能使用此接口同步订单的核销状态(三方码权限核对:开放平台 - 控制台 - 小程序应用 - 解决方案 - 生活服务 - 按照接入行业选择 - 【KA】三方码接入能力)。
      •交易系统的订单,在开发者系统完成核销后,开发者可通过此接口同步核销状态,完成订单在开放平台交易系统内的状态流转。
      •此接口支持推送整个订单的核销完成状态,也支持指定订单中的某个或者几个 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
    是
    开发者系统内的交易单号,称为外部单号(需与预下单回调中的out_order_no保持一致)。
    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 的所有商品单都为待使用状态才能成功核销,到综预约品拆单或整单核销都需要传true。
    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,取值时请参考预下单回调中的item_order_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

    请求示例

    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

    响应示例

    正常示例

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

    异常示例

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