- 小程序 OpenAPI SDK 总览
- OpenAPI 简介
- 用户登录态签名
- 签名算法
- 联合授权
- 接口调用凭证
- 登录
- 小程序码与小程序链接
- Web 化接入
- 私信和群聊
- 解决方案
- 线索组件
- 隐私协议
- 视频能力
- 搜索能力
- 任务能力
- 电商
- 生活服务
- 短剧行业
- 用户信息
- 分享
- 客服
- 交易工具
- 小程序券
- 交易系统
- 素材库
- 内容安全
- 泛知识
- 担保支付
- 评价
- 其它
- 订阅消息
- 小程序推广计划
- 挂载
- 分发
- 数据分析
- 服务类目
- 直播间能力
- 抖音开放能力
- 能力申请
- 页面结构自定义
- 普通二维码绑定
- 抖音号绑定
- 流量主
- 抖店绑定
预下单回调收藏我的收藏
收藏
我的收藏通过模板组件发起下单时,抖音开平交易系统会请求开发者服务,将下单信息传递给开发者服务。
使用限制
无
接口说明
无
基本信息
基本信息 | ||||
HTTP URL | ||||
HTTP Method | POST |
请求头
请求参数
msg 字段
名称 | 类型 | 是否必填 | 描述 |
order_id | string | 是 | 抖音开平侧生成的订单号 |
goods | Array<object> | 是 | |
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 | 是 | 核销类型,开平告知此订单是否可走闭环核销判断结果。
|
price_calculation_detail | object | 否 |
price_calculation_detail 字段
名称 | 类型 | 是否必填 | 描述 |
calculation_type | int32 | 是 | 算价维度类型
|
goods_discount_detail | Array<object> | 否 | |
order_discount_detail | object | 否 | |
item_discount_detail | Array<object> | 否 | |
ext_calculation_no | string | 否 | 外部算价结果号 |
说明:
- 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 字段
说明:
- •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 | 是 | 营销类型,
|
discount_amount | number | 是 | 该营销策略优惠金额,单位分 |
title | string | 是 | 营销名称 |
note | string | 否 | 营销备注 |
discount_range | number | 是 | 营销适用维度:
|
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 类别,
|
item_order_info_list | Array<object> | 是 | |
goods_book_info | object | 否 |
goods_book_info 字段
名称 | 类型 | 是否必填 | 描述 |
book_type | string | 是 | 预约类型,
|
cancel_policy | string | 否 | 取消政策,
|
item_order_info 字段
名称 | 类型 | 是否必填 | 描述 |
item_order_id | string | 是 | item 单 ID |
price | int64 | 是 | 商品优惠后价格 |
请求示例
Shell复制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 内部结构:
JSON复制/* 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> | 否 | 券的有效期,注意:
|
order_goods_info | Array<object> | 否 | 订单的商品相关信息 |
pay_notify_url | string | 否 | 支付结果通知地址,必须是 HTTPS 类型,若不填,默认使用在 https://developer.open-douyin.com/microapp/ttf4d2826f6becc24001/pay 页面设置的支付回调地址。ttf4d2826f6becc24001 为小程序的 AppID 。 |
cp_delivery_type | int | 否 | 开发者指定核销类型。如有三方码场景,可通过此参数指定。请注意指定三方码参数需要申请白名单,不在白名单内的此订单会做下单失败处理。 有效值:
|
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 | 否 |
例如: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 | 是 |
响应示例
json复制{
"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" // 收款商户号
}
]
}
}
点击纠错