算价扩展点
当用户在模版组件提单页下单时，抖音开平交易系统会携带用户选择营销信息，向开发者的服务发起请求，获取基于用户所选营销信息的算价结果。
基本信息
| 基本信息 | |
|---|---|
| HTTP URL | 开发者通过扩展点设置接口设置的 calculation_callback 路径 |
| HTTP Method | POST |
msg 字段
| 名称 | 类型 | 是否必填 | 描述 | 示例值 |
|---|---|---|---|---|
| open_id | string | 是 | 用户 open_id | "123rq0gjhdfoqierug" |
| goods_calculation_info | list | 否 | 商品算价信息，仅包含该商品使用的商品维度营销策略 | [goods1, goods2] |
| order_calculation_info | object | 否 | 订单算价信息，仅包含该订单使用的订单维度营销策略 | |
| app_id | string | 是 | 小程序 id | "ttcfdb50e33351" |
| union_id | string | 否 | 用户的 UnionID | "123jhdfoqieee" |
| callback_data | string | 否 | 透传参数 |
说明：
order_calculation_info 和 goods_calculation_info 的区别是优惠维度不同，举个例子：
- 星冰乐单品5折券属于商品维度优惠，应该放在goods_calculation_info中
- 订单满200-20属于订单维度优惠，应该放在order_calculation_info中
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| goods_id | string | 是 | 商品id | "123rfoqierug" | 非空 |
| quantity | number | 是 | 购买数量 | 1 | 须>=0且<50 |
| total_amount | number | 是 | 商品总价，单位分 | 10000 | 须大于 0 |
| using_marketing | object(marketing_brief) | 否 | 营销策略使用信息，仅包含该商品的商品维度优惠信息 |
order_calculation_info 结构说明
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| using_marketing | object(marketing_brief) | 否 | 营销策略使用信息，仅包含该订单的订单维度优惠信息 | ||
| total_amount | number | 是 | 商品总价，单位分 | 10000 | 须大于 0 |
注意：marketing_brief 结构说明见查询营销信息拓展点接口中 marketing_brief 说明。
请求示例
- 这个请求表达的含义是：用户(123rq0gjhdfoqierug)准备购买1份商品(7116845279713691692)，订单原始金额100分，使用商品维度优惠信息有：活动(activity_id_2_fen_MOCK_和activity_id_1_fen_MOCK_)，优惠券(coupon_id_90_fen_MOCK_)；无订单维度优惠信息；请返回算价结果
{
"open_id": "123rq0gjhdfoqierug",
"app_id": "ttxxxxxxxx",
"goods_calculation_info": [
{
"goods_id": "7116845279713691692",
"quantity": 1,
"total_amount": 100,
"using_marketing": {
"activity_ids": ["activity_id_2_fen_MOCK_", "activity_id_1_fen_MOCK_"],
"coupon_ids": ["coupon_id_90_fen_MOCK_"],
"membership_ids": [],
"score_info": []
}
}
],
"order_calculation_info": {
"total_amount": 100,
"using_marketing": {
"activity_ids": [],
"coupon_ids": [],
"membership_ids": [],
"score_info": []
}
}
}
说明：
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，订单总优惠金额=商品维度的优惠金额+订单维度的优惠金额
- total_discount_amount = sum(goods_calculation_result_info.total_discount_amount) = sum(item_calculation_result_info.total_discount_amount)
2、calculation_type表示算价类型，即计算优惠分摊的类型
-
- calculation_type=1，开发者将优惠分摊到goods层，只需返回order_calculation_result_info，goods_calculation_result_info，交易系统会按均摊逻辑帮开发者计算到item层
- 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_calculation_result_info[0].total_discount_amount=1500
- item层，item_calculation_result_info数组长度为2，items[0].total_discount_amount=750，items[1].total_discount_amount=750
order_calculation_result 结构说明
说明：
-
整个订单实际优惠金 total_discount_amount = order_total_discount_amount + goods_total_discount_amount。
-
营销明细按照 discount_range 的聚合结果必须和 order_total_discount_amount/goods_total_discount_amount 一致。
-
- order_total_discount_amount = sum(discount_range=1的marketing_detail.discount_amount)
- goods_total_discount_amount = sum(discount_range=2的marketing_detail.discount_amount)
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| order_total_discount_amount | number | 是 | 订单维度总优惠金额，单位分，如订单满减 | 5000 | 须大于等于 0 |
| goods_total_discount_amount | number | 是 | 商品维度总优惠金额，单位分，如咖啡第二杯半价 | 1000 | 须大于等于 0 |
| marketing_detail_info | list | 否 | 营销明细，包含该订单的订单维度和商品维度所有优惠信息 | [detail1, detail2] | 有重复检验，id + type +subtype 必须唯一 |
goods_calculation_result 元素结构说明
说明：
-
商品 total_discount_amount 和营销明细聚合结果必须一致。
-
- total_discount_amount = sum(marketing_detail.discount_amount)
-
所有商品的 total_amount/total_discount_amount 聚合结果必须和订单总total_amount/total_discount_amount 一致。
-
- total_amount = sum(goods.total_amount)
- total_discount_amount = sum(goods.total_discount_amount)
-
所有商品营销明细的聚合结果必须和订单营销明细一致（主要聚合 total_discount_amount 和 value）
-
- 例如，对于优惠券A：order层的marketing_detailA.discount_amount = sum(goods层的marketing_detailA.discount_amount)
- order_total_discount_amount = sum(discount_range=1的marketing_detail.discount_amount)
- goods_total_discount_amount = sum(discount_range=2的marketing_detail.discount_amount)
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| goods_id | string | 是 | 商品id | "123jherug" | 非空 |
| quantity | number | 是 | 购买数量 | 1 | >0 且<= 50 |
| total_amount | number | 是 | 商品总价，单位分 | 10000 | > 0 |
| total_discount_amount | number | 是 | 该商品总优惠金额，该商品的实付金额 = total_amount - total_discount_amount | 5000 | >=0 且 <= total_amount |
| marketing_detail_info | list | 否 | 营销明细，包含该商品使用的订单维度和商品维度所有优惠信息 | [detail1, detail2] | 有重复检验，id + type + subtype 必须唯一 |
item_calculation_result 元素结构说明
说明：
-
item表示单份商品
-
仅当 calculation_type = 2 时会校验 item 算价结果。calculation_type=1时，系统会用默认均摊逻辑帮开发者计算item层的优惠分摊。
-
item total_discount_amount 和营销明细聚合结果必须一致。
-
- total_discount_amount = sum(marketing_detail.discount_amount)
-
某个商品下的所有 item 的 total_amount/total_discount_amount 聚合结果必须和商品总 total_amount/total_discount_amount 一致。
-
item营销明细的聚合结果必须和商品营销明细一致（主要聚合 total_discount_amount 和 value）
-
- 例如，对于优惠券A：goods层的marketing_detailA.discount_amount = sum(item层的marketing_detailA.discount_amount)
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| goods_id | string | 是 | 商品id | "123oerug" | 非空 |
| total_amount | number | 是 | item原价，单位分 | 10000 | >0 |
| total_discount_amount | number | 是 | item总优惠金额，该item的实付金额 = total_amount - total_discount_amount | 5000 | >= 0且<= total_amount |
| marketing_detail_info | list | 否 | 营销明细，包含该 item 订单维度和商品维度的所有优惠信息 | [detail1, detail2] | 有重复检验，id + type + subtype 必须唯一 |
MarketingDetail 结构说明
说明：
-
当 value 不为 0 的时候，discount_amount 不能为 0（即不允许消耗积分却没有折扣）。
-
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，detailA2.discount_amount=500
-
-
对于某个具体的优惠券，它出现在3个层级的优惠明细里，除了value和discount_amount由于分摊具体的值会不一样，其他属性值都是一样的
-
discount_range，表示优惠的维度，举个例子
-
- 星冰乐单品5折券属于商品维度优惠，discount_range=2
- 订单满200-20属于订单维度优惠，discount_range=1
| 名称 | 类型 | 是否必填 | 描述 | 示例值 | 校验逻辑 |
|---|---|---|---|---|---|
| id | string | 是 | 营销 id（用户身份 id，优惠券 id，积分 id 或者活动 id) | ”ioejfioa" | 非空, <=64字节 |
| type | number | 是 | 营销类型， 1：用户身份 2：优惠券 3：积分 4：活动 | 2 | |
| discount_amount | number | 是 | 该营销策略优惠金额，单位分 | 3000 | 须大于 0 |
| title | string | 是 | 营销名称 | "满 50 减 10 元优惠券" | 非空, <=64字节 |
| note | string | 是 | 营销备注 | "该优惠券仅在部分门店使用" | 非空，<=256字节 |
| subtype | string | 否 | 子营销类型 | 礼品卡、满减券 | 非空时须<=64字节 |
| value | number | 否 | 营销分值，某些类型的营销会有，积分和 discount_amount 有一定的关系 | 积分、卡的值 消耗一定积分，换取一定优惠 | 非空时须大于等于 0 |
| discount_range | number | 是 | 营销适用维度： 1：订单维度 2：商品维度 | 1 | |
| code | string | 否 | 优惠券编码 | "49dkjg04jf04kg" | 优惠券类型必填 |
curl --location --request POST 'http://dev-cn.your-api-server.com/api/v2/query_marketing_info?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Signature: irqy39487t092h3fiqufheiufhqyt9q' \
--header 'Content-Type: application/json' \
--data-raw '{
"version": 2.0,
"type": "calculate_price",
"msg": "{\"open_id\":\"123rq0gjhdfoqierug\",\"app_id\":\"ttxxxxxxxx\",\"goods_calculation_info\":[{\"goods_id\":\"7116845279713691692\",\"quantity\":1,\"total_amount\":100,\"using_marketing\":{\"activity_ids\":[\"activity_id_2_fen_MOCK_\",\"activity_id_1_fen_MOCK_\"],\"coupon_ids\":[\"coupon_id_90_fen_MOCK_\"],\"membership_ids\":[],\"score_info\":[]}}],\"order_calculation_info\":{\"total_amount\":100,\"using_marketing\":{\"activity_ids\":[],\"coupon_ids\":[],\"membership_ids\":[],\"score_info\":[]}}}"
}'{
"err_no": 0,
"err_tips": "success",
"data": {
"calculation_type": 1,
"goods_calculation_result_info": [
{
"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
}
],
"order_calculation_result_info": {
"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_"
}
]
},
"item_calculation_result_info": [],
"total_amount": 100,
"total_discount_amount": 93
}
}