预下单回调
收藏
我的收藏

通过模板组件发起下单时，抖音开平交易系统会请求开发者服务，将下单信息传递给开发者服务。

使用限制

无

接口说明

无

基本信息

基本信息
HTTP URL	开发者通过设置回调地址设置的 create_order_callback 路径
HTTP Method	POST

请求头

参见通用参数。

请求参数

名称	类型	是否必填	描述	示例值
msg	string	是	预下单相关信息的 json 字符串，详情参见 msg 字段	详情参见请求示例
type	string	是	枚举值： •pre_create_order：预下单回调 •pre_create_refund：退款审核回调 •query_marketing_info：营销信息查询回调 •calculate_price：营销算价回调	"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	否	营销算价结果信息，详情见 price_calculation_detail 字段

price_calculation_detail 字段

名称	类型	是否必填	描述
calculation_type	int32	是	算价维度类型 •1：计算到goods层 •2：计算到item层
goods_discount_detail	Array<object>	否	商品算价结果，详情见 goods_discount_detail 字段
order_discount_detail	object	否	订单算价结果，详情见 order_discount_detail 字段
item_discount_detail	Array<object>	否	单商品算价结果详情见 item_discount_detail 字段
ext_calculation_no	string	否	外部算价结果号

说明：

订单原价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，订单总优惠金额=商品维度的优惠金额+订单维度的优惠金额

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

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层的优惠聚合

举个例子，一笔订单购买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>	否	营销明细，详情见 marketing_detail 字段

goods_discount_detail 字段

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

item_discount_detail 字段

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

marketing_detail 字段

说明：

•

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为3时表示积分值

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 字段
goods_book_info	object	否	预约信息，详情见 goods_book_info 字段

goods_book_info 字段

名称	类型	是否必填	描述
book_type	string	是	预约类型， •1：不需要预约 •2：在线预约
cancel_policy	string	否	取消政策， •1：预约后不可取消 •2：预约后可取消

item_order_info 字段

名称	类型	是否必填	描述
item_order_id	string	是	item 单 ID
price	int64	是	商品优惠后价格

请求示例

curl --location --request POST 'https://xxxxxxx.net/api/v2/create_order?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' \
--header 'Signature: irqy39487t092h3fiqufheiufhqyt9q'
--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":"商家侧子营销类型默认值"
                },
                {
                    "id":"activity_id_1_fen_MOCK_",
                    "type":4,
                    "discount_amount":1,
                    "title":"[活动] 满 0.10 减 0.01 元",
                    "note":"活动优惠",
                    "discount_range":2,
                    "subtype":"商家侧子营销类型默认值"
                },
                {
                    "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_"
                }
            ]
        },
        "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":"商家侧子营销类型默认值"
                    },
                    {
                        "id":"activity_id_1_fen_MOCK_",
                        "type":4,
                        "discount_amount":1,
                        "title":"[活动] 满 0.10 减 0.01 元",
                        "note":"活动优惠",
                        "discount_range":2,
                        "subtype":"商家侧子营销类型默认值"
                    },
                    {
                        "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_"
                    }
                ],
                "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，最大不能超过48小时。
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 类型，若不填，默认使用在`https://developer.open-douyin.com/microapp/ttf4d2826f6becc24001/pay`页面设置的支付回调地址。 `ttf4d2826f6becc24001`为小程序的 `AppID`。
cp_delivery_type	int	否	开发者指定核销类型。如有三方码场景，可通过此参数指定。请注意指定三方码参数需要申请白名单，不在白名单内的此订单会做下单失败处理。有效值： •0：无特殊处理 •1：三方码方案 •其他：其他值都会按照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 字段

•

本字段可不填

•

指定商户号下单需要开白名单，不开白名单会导致下单失败，有需要的请提oncall

•

对每个商品，请填写正确的收款商户号；如果未填写，将默认使用小程序进件商户号。响应里的商品id需要与请求的商品id保持一致。

•

目前的下单场景里只包含一种商品，未来可能会支持多个商品，所以结构是列表由于目前不支持购物车模式，只能用1个商户号收款。所以如果存在多商品的情况，对于每个商品请填写相同的商户号。

字段名	类型	是否必传	字段描述
goods_id	string	是	商品id，注意这里需要传string类型
merchant_uid	string	是	收款商户号，请填写正确的完成进件的商户号。如果未填写，将默认使用小程序进件商户号。指定商户号下单需要开白名单，不开白名单会导致下单失败，有需要的请提oncall。

响应示例

{ 
  "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 //毫秒
      }
    ],
    "order_goods_info": [
      {
        "goods_id": "xxx",
        "merchant_uid": "12345" // 收款商户号
      }
    ]
  }
}

预下单回调收藏我的收藏

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​msg 字段​

​price_calculation_detail 字段​

​order_discount_detail 字段​

​goods_discount_detail 字段​

​item_discount_detail 字段​

​marketing_detail 字段​

​goods 字段​

​goods_book_info 字段​

​item_order_info 字段​

​请求示例​

​响应参数​

​data 字段​

​order_entry_schema 字段​

​order_valid_time 字段​

​order_goods_info 字段​

​响应示例​