算价扩展点
收藏
我的收藏

当用户在模版组件提单页下单时，抖音开平交易系统会携带用户选择营销信息，向开发者的服务发起请求，获取基于用户所选营销信息的算价结果。

使用限制

无

接口说明

无

基本信息

基本信息
HTTP URL	开发者通过扩展点设置接口设置的 calculation_callback 路径
HTTP Method	POST

请求头

参见通用参数。

请求参数

名称	类型	是否必填	描述	示例值
msg	string	是	营销信息查询请求细节 JSON 字符串。注意： 1.msg 本身是 string 2.msg string 的内容是 JSON 格式的，JSON 转 string 需要转义 3.如遇问题，请仔细请求示例	参见请求示例的 msg 部分
type	string	是	枚举值： •pre_create_order 预下单回调 •pre_create_refund 预退款回调 •query_marketing_info 查询营销信息 •calculate_price 算价回调	"calculate_price"
version	string	是	固定值： 2.0。 callback 版本，用于开发者识别回调参数的变更	"2.0"

msg 字段

名称	类型	是否必填	描述	示例值
open_id	string	是	用户 open_id	"123rq0gjhdfoqierug"
goods_calculation_info	list<object>	否	商品算价信息，仅包含该商品使用的商品维度营销策略	[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_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_)；无订单维度优惠信息；请返回算价结果

curl -vv  --location --request POST 'https://xxxxxxx.net/api/v2/query_marketing_info?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' \
--header 'Signature: irqy39487t092h3fiqufheiufhqyt9q' \
--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\":[]}}}"
}'

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	int	是	错误码，0 代表成功	0
err_tips	string	是	错误提示信息	"success"
data	object	是	算价拓展点返回的信息	data

data 字段

名称	类型	是否必填	描述	示例值	校验逻辑
calculation_type	number	是	算价类型 •1：计算到goods层 •2：计算到item层	1
total_amount	number	是	订单总价格，单位: 分	30000	须大于 0
total_discount_amount	number	是	订单总优惠价格，单位分，订单最终价格 = total_amount - total_discount_amount	10000	须小于 total_amount
order_calculation_result_info	object	是	order层算价结果信息
goods_calculation_result_info	list<object>	是	goods层算价结果信息	[goods1, goods2]	请求中的 goods 都应该有对应 result object，其中 marketing_detail_info 可以为空，说明没有优惠
item_calculation_result_info	list<object>	否	item层算价结果信息		当 calculation_type=2 时，会采用开发者算价结果，此时 item result 不能为空

说明：

订单原价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)

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

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_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<object>	否	营销明细，包含该订单的订单维度和商品维度所有优惠信息	[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<MarketingDetail>	否	营销明细，包含该商品使用的订单维度和商品维度所有优惠信息	[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<MarketingDetail>	否	营销明细，包含该 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"	优惠券类型必填

响应示例

正常示例

{
  "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
  }
}

异常示例

{
  "err_no": 10000,
  "err_tips": "参数错误"
}

算价扩展点收藏我的收藏