抖音开放平台Logo
开发者文档
小程序
控制台
  • OpenAPI 简介
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 评价
  • 交易工具
  • 交易系统
  • 通用交易系统
  • 行业交易系统
  • API 调用
  • 回调设置
  • 预下单
  • 营销算价
  • 支付
  • 核销
  • 抖音码
  • 三方码
  • 推送核销状态
  • 分账
  • 退货退款
  • 担保支付（即将下线）
  • 抖店绑定
  • 运营
  • 生活服务
  • 垂直行业
  • 其它
    • 该接口用于同步订单的核销状态到开放平台。

    使用限制

    无

    接口说明

      •只有三方码订单和泛知识同步履约状态，开发者才能使用此接口同步订单状态。
      •交易系统的订单，在开发者系统完成核销或课程学习后，开发者可通过此接口同步核销状态，完成订单在开放平台交易系统内的状态流转。
      •此接口支持推送整个订单的核销完成状态，也支持指定订单中的某个或者几个 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
    预约商品不允许推送核销状态
    预约类商品不能通过此接口推送核销状态。
    ​