抖音开放平台Logo
开发者文档
小程序
控制台
  • OpenAPI 简介
  • 小程序 OpenAPI SDK 总览
  • 签名算法
  • 基础能力
  • 触达与营销
  • 支付
  • 运营
  • 生活服务
  • 核销工具解决方案
  • 通用能力
  • poi基础能力
  • CPS佣金设置与查询
  • 生活服务交易系统（全融合版）
  • 通用参数
  • 错误码和返回码
  • 查询接口
  • 预下单
  • 预下单扩展点
  • 开发者发起下单
  • 营销算价
  • 支付
  • 核销
  • 分账
  • 退货退款
  • 生活服务交易系统（账号融合版）
  • 历史版本（不推荐使用）
  • 垂直行业
  • 其它
    • 通过模板组件发起下单时，抖音开平交易系统会请求开发者服务，将下单信息传递给开发者服务。详见交易系统接入流程。

    使用限制

    无

    接口说明

    无

    基本信息

    基本信息
    HTTP URL
    预下单回调地址的设置请参考行业模板配置文档-实现扩展点 create_order_callback。
    HTTP Method
    POST

    请求头

    参见通用参数。

    请求参数

    名称
    类型
    是否必填
    描述
    示例值
    msg
    string
    是
    预下单相关信息的 json 字符串，详情参见msg字段描述。
    详情参见msg请求示例
    type
    ​
    string
    ​
    是
    ​
    固定值：
      •pre_create_order：预下单回调
    "pre_create_order"
    version
    ​
    string
    是
    ​
    固定值："2.0"，即回调版本，用于开发者识别回调参数的变更
    "2.0"

    msg 字段

    名称
    类型
    是否必填
    描述
    order_id
    string
    是
    抖音开平侧生成的订单号
    goods
    Array<object>
    是
    商品信息，详情见goods字段
    total_amount
    int64
    ​
    是
    订单总价格，单位分
    用户实付金额 = total_amount - discount
    discount
    int64
    是
    订单折扣，单位分
    cp_extra
    string
    否
    预下单时开发者定义的透传信息
    create_order_time
    int64
    是
    订单创建时间，13 位时间戳，单位毫秒
    open_id
    string
    是
    用户 OpenID
    phone_num
    string
    否
    用户手机号
    contact_name
    string
    否
    联系人姓名
    app_id
    string
    是
    小程序id
    union_id
    string
    否
    用户的 UnionID
    delivery_type
    int
    是
    抖音码/三方码类型：
      •0：三方码，开发者自行处理券码生成及展示，通过 push_delivery 接口推送核销状态。
      •1：抖音码，开平负责生券，开发者使用核销组件展示，使用验券准备和验券接口核销。
    price_calculation_detail
    object
    ​
    否
    营销算价结果信息，详情见字段描述

    goods 字段

    名称
    类型
    是否必填
    描述
    img_url
    string
    是
    商品图片链接
    title
    string
    是
    商品标题
    sub_title
    string
    否
    商品副标题
    labels
    ​
    string
    是
    ​
    商品标签，对应 POI 多门店 SPU 同步的 sub_title，例如：随时退｜免预约｜提前 3 日预约 （“｜”是中文类型)
    date_rule
    string
    是
    券的可用时间（目前仅用于展示），例如：“周一至周五可用”、“非节假日可用”
    origin_price
    int64
    是
    商品原价，单位分
    price
    int64
    是
    商品去掉折扣后的单价，单位分
    quantity
    int64
    是
    购买的商品数量
    poi_id
    string
    否
    对应门店的 POI ID
    goods_id
    string
    是
    商品 ID
    item_order_id_list
    Array
    是
    item_order_id 列表，id 个数与 quantity 一致
    goods_id_type
    int32
    是
    商品 ID 类别，
      •1：POI 商品
      •2：非 POI 商品
    item_order_info_list
    Array<object>
    是
    item_order 相关信息，详情见item_order_info字段
    item_order_info 字段
    名称
    类型
    是否必填
    描述
    item_order_id
    string
    是
    item 单 ID
    price
    int64
    是
    商品优惠后价格

    price_calculation_detail 字段说明

    名称
    类型
    是否必填
    描述
    calculation_type
    int32
    是
    算价维度类型
      •1： 计算到goods层
      •2： 计算到item层
    goods_discount_detail
    ​
    Array<object>
    否
    goods层算价结果信息，详情见字段描述
    ​
    order_discount_detail
    object
    ​
    否
    order层算价结果信息，详情见字段描述
    item_discount_detail
    Array<object>
    否
    item层算价结果信息，详情见字段描述
    ​
    说明：
      1.订单原价total_amount，订单总优惠total_discount_amount
      ◦total_amount = sum(goods_calculation_result_info.total_amount) = sum(item_calculation_result_info.total_amount)
      ◦total_discount_amount=order_total_discount_amount + goods_total_discount_amount，订单总优惠金额=商品维度的优惠金额+订单维度的优惠金额
      2.calculation_type表示计算优惠分摊的类型
      ◦calculation_type=1，将优惠分摊到goods层，请求体包含order_calculation_result_info，goods_calculation_result_info，
      ◦calculation_type=2，将优惠分摊到item层，请求体包含order_calculation_result_info，goods_calculation_result_info，item_calculation_result_info
      3.order_calculation_result_info，goods_calculation_result_info，item_calculation_result_info表达的是优惠分摊逻辑。order, goods, item代表订单的三层结构，order有N个goods，每个goods有M个item(M表示份数)，item表示单份商品。订单总优惠金额 = order层的优惠聚合 = goods层的优惠聚合 = item层的优惠聚合
      4.举个例子，一笔订单购买2杯奶茶，总价100元，使用80-10活动和星冰乐单品立减5元优惠券，实付金额85元，表达分摊的逻辑如下
      ◦订单总优惠金额 total_discount_amount =1500，单位[分]
      ◦order层，order_calculation_result_info，order_total_discount_amount=1000，goods_total_discount_amount=500
      ◦goods层，goods_calculation_result_info数组长度为1，goods[0].total_discount_amount=1500
      ◦item层，item_calculation_result_info数组长度为2，items[0].total_discount_amount=750，items[1].total_discount_amount=750

    order_discount_detail 字段说明

    名称
    类型
    是否必填
    描述
    order_total_discount_amount
    number
    是
    订单维度总优惠金额，单位分
    goods_total_discount_amount
    number
    是
    商品（sku）维度总优惠金额，单位分
    marketing_detail_info
    Array<object>
    ​
    否
    营销明细，详情见字段描述

    goods_discount_detail 字段说明

    名称
    类型
    是否必填
    描述
    goods_id
    string
    是
    商品 id
    ​
    quantity
    number
    是
    购买数量
    total_amount
    number
    是
    商品总价，单位分
    discount_amount
    number
    是
    该商品总优惠金额
    该商品的实付金额 = total_amount - discount_amount
    marketing_detail_info
    Array<object>
    否
    营销明细，详情见字段描述

    item_discount_detail 字段说明

    名称
    类型
    是否必填
    描述
    goods_id
    string
    是
    商品 id
    total_amount
    number
    是
    商品总价，单位分
    discount_amount
    number
    是
    单份商品总优惠金额
    单份商品的实付金额 = total_amount - discount_amount
    marketing_detail_info
    Array<object>
    否
    营销明细，详情见字段描述

    marketing_detail_info 字段说明

    说明：
      •marketing_detail_info在order,goods,item三个层级都有，区别是它表示某个营销项在这一层级分摊的优惠金额。比如一笔订单购买2杯奶茶，总价100元，使用优惠券A满100-10元，实付90元。优惠券A会出现在3个层级的marketing_detail_info里
      ▪在order层，detailA.discount_amount=1000，单位[分]
      ▪在goods层，detailA.discount_amount=1000，
      ▪在item层，由于优惠分摊到两份商品上,detailA1.discount_amount=500，detailA1.discount_amount=500
      •discount_range，表示优惠的维度，举个例子
      ◦星冰乐单品5折券属于商品维度优惠，discount_range=2
      ◦订单满200-20属于订单维度优惠，discount_range=1
    名称
    类型
    是否必填
    描述
    id
    string
    是
    营销 ID（用户身份 ID、优惠券 ID、积分 ID 或者活动 ID）
    type
    number
    ​
    是
    ​
    营销类型，
      •1：用户身份
      •2：优惠券
      •3：积分
      •4：活动
    discount_amount
    number
    是
    该营销策略优惠金额，单位分
    title
    string
    否
    营销名称
    note
    ​
    string
    否
    营销备注
    discount_range
    number
    是
    营销适用维度：
      •1：订单维度
      •2：商品维度
    subtype
    string
    否
    营销子类型
    value
    ​
    i64
    否
    不同 type 含义不同，比如 type 为 4 时指积分值
    ​
    kind
    number
    是
    营销类别
    1：商家
    2：平台
    creator_type
    number
    是
    创建人类型
    1：抖音平台
    2：抖音来客—商家
    3：小程序商家
    merchant_funder_type
    number
    否
    商家营销出资方式。1-货款代扣，2-营销钱包。营销类别为平台时为空
    funder_account_id
    number
    否
    营销钱包id。商家营销出资方式=营销钱包时返回，货款代扣时为空

    请求示例

    curl --location --request POST 'https://xxxxxxx.net/api/v2/create_order?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' 
--data-raw='{
  "version": "2.0",
  "msg": "序列化后的json字符串",
  "type": "pre_create_order"
}'
    msg 内部结构：
    /* msg结构 */
{ 
  "order_id": "614167279916",
    "goods": [
        {
            "img_url": "http://xxx",
            "title": "xxx",
            "sub_title": "xxx",
            "labels": "过期退|随时退",
            "date_rule": "xxx",
            "origin_price": 800,
            "price": 750,
            "quantity": 2,
            "poi_id": "",
            "goods_id": "xxx",
            "item_order_id_list": [
                "1xxx",
                "2xxx"
            ]
        }
    ],
    "price_calculation_detail":{
        "calculation_type":1,
        "order_discount_detail":{
            "order_total_discount_amount":0,
            "goods_total_discount_amount":93,
            "marketing_detail_info":[
                {
                    "id":"activity_id_2_fen_MOCK_",
                    "type":4,
                    "discount_amount":2,
                    "title":"[活动] 满 0.20 减 0.02 元",
                    "note":"活动优惠",
                    "discount_range":2,
                    "subtype":"商家侧子营销类型默认值",
                    "kind": 1,
                    "creator_type": 3,
                    "merchant_funder_type":2,
                    "funder_account_id":12345
                },
                {
                    "id":"activity_id_1_fen_MOCK_",
                    "type":4,
                    "discount_amount":1,
                    "title":"[活动] 满 0.10 减 0.01 元",
                    "note":"活动优惠",
                    "discount_range":2,
                    "subtype":"商家侧子营销类型默认值",
                    "kind": 1,
                    "creator_type": 3,
                    "merchant_funder_type":2,
                    "funder_account_id":12345
                },
                {
                    "id":"coupon_id_90_fen_MOCK_",
                    "type":2,
                    "discount_amount":90,
                    "title":"[券] 满 0.91 减 0.90 元",
                    "note":"用券优惠",
                    "discount_range":2,
                    "subtype":"商家侧子营销类型默认值",
                    "code":"coupon_id_90_fen_MOCK_",
                    "kind": 1,
                    "creator_type": 3,
                    "merchant_funder_type":2,
                    "funder_account_id":12345
                }
            ]
        },
        "goods_discount_detail":[
            {
                "goods_id":"7116845279713691692",
                "quantity":1,
                "total_amount":100,
                "total_discount_amount":93,
                "marketing_detail_info":[
                    {
                        "id":"activity_id_2_fen_MOCK_",
                        "type":4,
                        "discount_amount":2,
                        "title":"[活动] 满 0.20 减 0.02 元",
                        "note":"活动优惠",
                        "discount_range":2,
                        "subtype":"商家侧子营销类型默认值",
                        "kind": 1,
                        "creator_type": 3,
                        "merchant_funder_type":2,
                        "funder_account_id":12345
                    },
                    {
                        "id":"activity_id_1_fen_MOCK_",
                        "type":4,
                        "discount_amount":1,
                        "title":"[活动] 满 0.10 减 0.01 元",
                        "note":"活动优惠",
                        "discount_range":2,
                        "subtype":"商家侧子营销类型默认值",
                        "kind": 1,
                        "creator_type": 3,
                        "merchant_funder_type":2,
                        "funder_account_id":12345
                    },
                    {
                        "id":"coupon_id_90_fen_MOCK_",
                        "type":2,
                        "discount_amount":90,
                        "title":"[券] 满 0.91 减 0.90 元",
                        "note":"用券优惠",
                        "discount_range":2,
                        "subtype":"商家侧子营销类型默认值",
                        "code":"coupon_id_90_fen_MOCK_",
                        "kind": 1,
                        "creator_type": 3,
                        "merchant_funder_type":2,
                        "funder_account_id":12345
                    }
                ],
                "sku_id":null
            }
        ],
        "item_discount_detail":[

        ]
    },
    "total_amount": 1600,
    "discount": 100,
    "cp_extra": "xxx",
    "create_order_time": 1642491214992,
    "open_id": "xxx",
    "phone_num": "xxx",
    "contact_name": "xxx",
    "app_id": "xxx",
    "union_id": "xxx"
}

/* 响应 */
{
    "err_no" : 0,
    "err_tips" : "success",
     "data": {
        "out_order_no" : "89876867867087", //开发者的单号
        "pay_expire_seconds": 300, //单位秒
        "order_entry_schema": {
            "path": "page/refundDetail/xxx", //订单详情页路径
            "params": "{\"id\": 1}" //订单详情页路径参数
        },
        "order_valid_time":[
           {
            "goods_id": "xxx",
            "valid_start_time": 1232312000, //毫秒
            "valid_end_time": 1231231000  //毫秒
            }
        ]
    }
}

    响应参数

    字段名
    类型
    是否必传
    字段描述
    err_no
    int
    是
    错误码，0 代表成功
    err_tips
    string
    是
    错误提示信息
    data
    object
    是
    预下单的信息

    data 字段

    名称
    类型
    是否必传
    描述
    out_order_no
    string
    是
    开发者的单号，长度小于等于 64 byte
    pay_expire_seconds
    int64
    否
    支付超时时间，单位秒，例如 300 表示 300 秒后过期；不传或传 0 会使用默认值 300。
    order_entry_schema
    object
    是
    订单详情页信息
    order_valid_time
    ​
    Array<object>
    ​
    否
    ​
    券的有效期，注意：
      1.非 POI 商品必传，POI 商品会从 POI 库里查询有效期信息，不会使用开发者传的数据。
      2.如果是非 POI 商品，每个 goods_id 都要传券的有效期信息，否则会下单失败。
    order_goods_info
    Array<object>
    否
    订单的商品相关信息
    pay_notify_url
    ​
    string
    ​
    否
    支付结果通知地址，必须是 HTTPS 类型。
    若不填，默认使用在行业模板配置-消息通知中设置的支付回调地址。
    cp_delivery_type
    ​
    int
    否
    ​
    开发者指定核销类型。如有三方码场景，可通过此参数指定。请注意指定三方码参数需要申请白名单，不在白名单内的此订单会做下单失败处理。
    有效值：
      •0：无特殊处理
      •1： 三方码无码方案
      •2: 三方码有码方案（需要开通三方码权限）
      •其他：其他值都会按照0值处理
    delivery_qrcode_redirect
    ​
    string
    ​
    否
    开发者可通过此参数指定此订单的核销二维码的跳转 URL。如果是闭环核销，开平的核销组件会使用此 URL 生成二维码，商家核销时即可实现跳转到指定 URL。如果传该参数，必须是 HTTPS 链接，长度小于等于 256 字节。不满足要求的会导致预下单失败。

    order_entry_schema 字段

    名称
    类型
    是否必传
    描述
    path
    string
    是
    订单详情页跳转路径，没有前导的“/”，长度 <= 512 byte
    params
    string
    否
    订单详情页路径参数，自定义的 json 结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问订单详情的 schema 能正确跳转到小程序内部的订单详情页，长度须 <= 512byte

    order_valid_time 字段

    名称
    类型
    是否必传
    描述
    goods_id
    string
    是
    商品 id
    valid_start_time
    int64
    否
    券的有效期开始时间，单位毫秒，须大于 0
    valid_end_time
    int64
    否
    券的有效期结束时间，单位毫秒，须大于 0，且须大于 valid_start_time 和当前时间
    valid_duration
    int64
    否
      1.券的相对有效时间，单位毫秒，须大于 0
      2.与 valid_start_time、valid_end_time 组合，至少回传一个，否则会下单失败
      3.都合法优先使用 valid_start_time、valid_end_time 组合
      4.当 valid_duration 有效时，
      ◦券的有效期开始时间 S = 订单支付完成时间
      ◦券的有效期结束时间 E = 1天 + 向下按天截断（S + valid_duration)）。
    例如：valid_duration = 86400000 ms（一天），S = 2021.1.1 6:00，E = 2021.1.2 23:59:59

    order_goods_info 字段

      •本字段可不填
    字段名
    类型
    是否必传
    字段描述
    goods_id
    string
    是
    商品id，注意这里需要传string类型

    响应示例

    { 
  "err_no": 0,
  "err_tips": "success",
  "data": {
    "out_order_no": "89876867867087", //开发者的单号
    "pay_expire_seconds": 300, //单位秒
    "order_entry_schema": {
      "path": "page/refundDetail/xxx", //订单详情页路径
      "params": "{\"id\": 1}" //订单详情页路径参数
    },
    "order_valid_time": [
      {
        "goods_id": "xxx",
        "valid_start_time": 1682407227000, //毫秒
        "valid_end_time": 1682407228000 //毫秒
      }
    ],
    "order_goods_info": [
      {
        "goods_id": "xxx"
      }
    ]
  }
}
    ​