营销查询算价二合一

我的收藏

模版组件提单页通过本接口从开发者的服务获取可用的相关营销信息和对应的算价结果展示给用户。

下单时，抖音开平交易系统会携带用户选择营销信息，通过本接口从开发者的服务获取对应的算价结果。

使用限制

无

接口说明

无

基本信息

基本信息
HTTP URL	回调地址的设置请参考行业模版使用指南-实现扩展点 query_and_calculate
HTTP Method	POST

请求头

参见通用参数-平台请求开发者公共参数。

请求参数

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

msg 字段

说明：

need_default_marketing=true，开发者需返回默认最优的营销组合和算价结果

need_default_marketing=false，且用户选中具体的优惠信息时(商品/订单的selected_marketing不为空)，开发者需返回用户选中优惠的算价结果

goods_marketing_info和order_marketing_info结构体中selected_marketing的区别是优惠适用的维度不同：

◦

goods_marketing_info下的优惠是作用于具体商品的，比如星冰乐单品优惠立减5元

◦

order_marketing_info下的优惠是作用于整个订单的，比如订单满200-20

◦

对于一个具体的优惠券，不能同时出现在goods_marketing_info和order_marketing_info中，它适用的优惠维度是明确的

名称	类型	是否必填	描述	示例值
open_id	string	是	用户 open_id	"123rq0gjhdfoqierug"
goods_marketing_info	list<object>	否	商品维度用户选用的营销信息	[goods_calculation1, goods_calculation2]
order_marketing_info	object	否	订单维度用户选用的营销信息	order_calculation_info
app_id	string	是	小程序 id	"ttcfdbb96650e33351"
union_id	string	否	用户的 UnionID	"123rq0gjhdfoqieee"
callback_data	string	否	透传参数
need_default_marketing	bool	是	是否需要默认算价（首次获取营销信息时为true）	true

goods_marketing_info 元素结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
goods_id	string	是	商品id	"123rq0gjhdfoqierug"	非空
sku_id	string	否	skuid	"71273"
quantity	number	是	购买数量	1	须不为 0 且小于等于 50
total_amount	number	是	商品总价，单位分	10000	须大于 0
selected_marketing	object(MarketingBundle)	否	用户所选营销策略信息，仅包含该商品的商品层优惠信息	selected_marketing

order_marketing_info 结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
selected_marketing	object(MarketingBundle)	否	用户所选营销策略信息，仅包含该订单的订单层优惠信息	selected_marketing
total_amount	number	是	订单总价，单位分	10000	须大于 0

MarketingBundle 结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
membership_info	list<object>	否	用户身份信息(如会员)	[membership1, membership2]
coupon_info	list<object>	否	优惠券信息	[coupon1, coupon2]
activity_info	list<object>	否	活动信息	[activity1, activity2]
score_info	list<object>	否	积分信息	[score1, score2]

membership_info 元素结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
id	string	是	用户身份 id	"abcd33234"	非空，<=64 字节
desc	string	是	用户身份描述	"京东 plus 会员"	<= 128字节

coupon_info 元素结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
id	string	是	优惠券id	"abcd33234"	非空，<= 64 字节
code	string	是	优惠券编码	"49dkjg04jf04kg"	非空，<= 64 字节
type	number	是	优惠券类型： •1：立减券 •2：满减券 •3：折扣券	1
name	string	是	优惠券名称	"满100减20立减券"	非空，<= 64 字节
receive_time	number	否	优惠券领取时间戳，单位毫秒	1920423870232
start_time	number	是	有效起始时间戳，单位毫秒	1920423870232
end_time	number	是	有效结束时间戳，单位毫秒	1920423870232	晚于 start_time
discount_amount	number	否	优惠价格，单位分	20000	> 0（不允许没有折扣的优惠券）
deduct_percentage	number	否	折扣百分比，填 0~100，折扣抵 30% 则填 30	30	0～100
detail_url	string	否	优惠券详情跳转链接	"page/index/index"	<= 512 字节
rule	string	是	使用规则描述，包含适用范围描述，使用条件，退款时的处理说明等	"适用于该店铺所有商品，周一到周五可使用"	非空，<= 256 字节
deny_reasons	list<string>	否	不可用原因。当优惠券不可用时，开发者可传入不可用原因。	未达到满减门槛	原因不超过3个，单个原因不超过22个字符

activity_info 元素结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
id	string	是	活动 id	"abcd33234"	非空，<= 64 字节
name	string	是	活动名称	1	非空，<= 64 字节
start_time	number	否	有效起始时间戳	192042387023234
end_time	number	否	有效结束时间戳	192042387023235	晚于 start_time
rule	string	是	活动规则	"限时秒杀立减 100 元"	非空，<= 256 字节

score_info 元素结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
value	number	是	可用积分值	9527	>= 0
id	string	是	积分 id，如“JingDong-vip”表示京东 VIP 会员积分，再比如可能会有具体某个店铺的积分，很多大店铺是有自己的积分系统的	"390dknvi0o4"	非空，<= 64 字节
name	string	是	积分名字：如：京东 VIP 会员积分	同上	非空，<= 64 字节

请求示例

•

这个请求表达的含义是：用户(M3arp6xWNPyvKnHf)准备购买1份商品(7116845279713691692)，订单原始金额100分，请返回这笔订单可用的优惠信息以及默认最佳优惠的算价结果

curl -vv  --location --request POST 'https://xxxxxxx.net/api/v2/xxxx?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Content-Type: application/json' \
--header 'Signature: irqy39487t092h3fiqufheiufhqyt9q' \
--data-raw '{
    "version": 2.0,
    "type": "query_and_calculate",
    "msg": "{\"callback_data\":\"\",\"open_id\":\"gyRRZhwLUjZ.KMBI\",\"app_id\":\"ttcfdbb96650e33350\",\"union_id\":\"e37d4dff-febb-43f4-83a3-f4e9fee61d15\",\"goods_marketing_info\":[{\"goods_id\":\"7116845279713691692\",\"sku_id\":null,\"quantity\":1,\"total_amount\":100}],\"order_marketing_info\":{\"total_amount\":100},\"need_default_marketing\":true}"
}'

msg 具体内容：

{
  "callback_data": "",
  "open_id": "gyRRZhwLUjZ.KMBI",
  "app_id": "ttcfdbb96650e33350",
  "union_id": "e37d4dff-febb-43f4-83a3-f4e9fee61d15",
  "goods_marketing_info": [
    {
      "goods_id": "7116845279713691692",
      "quantity": 1,
      "total_amount": 100
    }
  ],
  "order_marketing_info": {
    "total_amount": 100
  },
  "need_default_marketing": true
}

响应参数

名称	类型	是否必填	描述	示例值
err_no	int	是	错误码，0 代表成功	0
err_tips	string	是	错误提示信息	"success"
data	object	否	查询营销信息拓展点返回的信息	data

data 字段

名称	类型	是否必填	描述	示例值	校验逻辑
goods_marketing_result	list<object>	是	商品维度营销查询结果，包含商品信息以及该商品维度用户可用/不可用营销信息		与请求中的商品信息一致
order_marketing_result	object	否	订单维度营销查询结果，包含订单总价以及订单维度用户可用/不可用营销
calculation_result	object	否	算价结果

说明：

如果响应中无data字段，系统认为无可用营销信息

如果请求中用户所选的营销不可用（包含1中情况），即用户之前的选择失效，此时外部服务应该报错（err_no不为0）并给出有效的说明信息（err_tips）

如果data中无calculation_result字段，系统认为无算价信息，会用商品原价作为算价结果参与后续校验

goods_marketing_result和order_marketing_result下都有available_marketing和unavailable_marketing字段，它们的区别是优惠适用的维度不同：

◦

goods_marketing_result下的available和unavailable优惠是针对商品的。举个例子，对于商品星冰乐，星冰乐单品优惠券属于available，蛋糕单品优惠券属于unavailable

◦

order_marketing_result下的available和unavailable优惠是针对订单的。举个例子，总价150的订单，满100-5的优惠券属于available，满200-20优惠券属于unavailable

◦

对于一个具体的优惠券，不能同时出现在goods_marketing_result和order_marketing_result中，它适用的优惠维度是明确的

order_marketing_result.total_amount = sum(goods_marketing_result.total_amount)

goods_marketing_result 元素结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
goods_id	string	是	商品id	"123oqierug"	非空
sku_id	string	否	sku_id	"71273"
quantity	number	是	购买数量	1	须不为 0 且小于等于 50
total_amount	number	是	商品总价，单位分	10000	须大于 0
available_marketing	object(MarketingBundle)	否	该商品下可用的优惠信息（商品维度）
unavailable_marketing	object(MarketingBundle)	否	该商品下不可用的优惠信息（商品维度）		与available_marketing不能有交集，即不能存在某个营销即可用又不可用

order_marketing_result 元素结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
total_amount	number	是	商品总价，单位分	10000	须大于 0
available_marketing	object(MarketingBundle)	否	订单维度可用的优惠信息
unavailable_marketing	object(MarketingBundle)	否	订单维度不可用的优惠信息		与available_marketing不能有交集，即不能存在某个营销即可用又不可用

calculation_result 元素结构说明

名称	类型	是否必填	描述	示例值	校验逻辑
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
goods_calculation_result_info	list<object>	否	goods层算价结果信息，calculation_type=1时必填	[goos1,goods2]	请求中的 goods 都应该有对应 result object，其中 marketing_detail_info 可以为空，说明没有优惠
item_calculation_result_info	list<object>	否	item层算价结果信息，calculation_type=2时必填	[item1,item2,item3]	当 calculation_type=2 时，会采用开发者算价结果，此时 item result 不能为空

说明：

订单原价total_amount，订单总优惠total_discount_amount = goods层的优惠聚合 = item层的优惠聚合

◦

total_amount = sum(goods_calculation_result_info.total_amount) = sum(item_calculation_result_info.total_amount)

◦

total_discount_amount=sum(goods_calculation_result_info.total_discount_amount)=sum(item_calculation_result_info.total_discount_amount)

◦

goods_calculation_result_info，item_calculation_result_info表达的是优惠分摊逻辑。例如，订单有N个goods，每个goods有M个item，item表示单份商品。

calculation_type表示优惠分摊的类型，开发者可选择将优惠分摊到商品(goods层)或者每一份商品(item层)

◦

calculation_type=1，开发者将优惠分摊到goods层，需返回goods_calculation_result_info，交易系统会按均摊逻辑帮开发者计算到item层

◦

calculation_type=2，开发者将优惠分摊到item层，需返回item_calculation_result_info

举个例子，一笔订单购买2杯奶茶，总价100元，使用80-10活动和星冰乐单品立减5元优惠券，实付金额85元，表达分摊的逻辑如下

◦

订单总优惠金额 total_discount_amount =1500，单位[分]

◦

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

goods_calculation_result_info 元素结构说明

说明：

•

是列表，列表的每一项表示一种商品

•

商品 total_discount_amount 和营销明细聚合结果必须一致。

◦

total_discount_amount = sum(marketing_detail.discount_amount)

名称	类型	是否必填	描述	示例值	校验逻辑
goods_id	string	是	商品id	"123rq0gjhdfoqierug"	非空
sku_id	string	否	sku_id	"71273"	若请求有sku_id,响应也要返回sku_id
quantity	number	是	购买数量	1	0quantity<=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_info 元素结构说明

说明：

•

是列表，列表的每一项，表示单份商品

•

item total_discount_amount 和营销明细聚合结果必须一致。

◦

total_discount_amount = sum(marketing_detail.discount_amount)

名称	类型	是否必填	描述	示例值	校验逻辑
goods_id	string	是	商品id	"1hdfoqierug"	非空
sku_id	string	否	sku_id	"71273"	若请求有sku_id,响应也要返回sku_id
total_amount	number	是	商品总价，单位分	10000	须大于 0
total_discount_amount	number	是	该商品总优惠金额，该商品的实付金额 = total_amount - total_discount_amount	5000	须>= 0且<= total_amount
marketing_detail_info	list<MarketingDetail>	否	营销明细，包含该 item 订单层和商品层所有优惠信息	[marketing_detail1, marketing_detail2]	有重复检验，id + type + subtype 必须唯一

MarketingDetail 结构说明

说明：

•

当 value 不为 0 的时候，discount_amount 不能为 0（即不允许消耗积分却没有折扣）。

•

discount_range，表示优惠的维度，举个例子

◦

星冰乐单品5折券属于商品维度优惠，discount_range=2

◦

订单满200-20属于订单维度优惠，discount_range=1

名称	类型	是否必填	描述	示例值	校验逻辑
id	string	是	营销 id（用户身份 id，优惠券 id，积分 id 或者活动 id)	”ioejfioa"	须大于 0 且小于等于 64
type	number	是	营销类型， •1：用户身份 •2：优惠券 •3：积分 •4：活动	2
discount_amount	number	是	该营销策略优惠金额，单位分	3000	须大于 0
title	string	是	营销名称	"满 50 减 10 元优惠券"	须大于 0 且小于等于 64
note	string	是	营销备注	"该优惠券仅在部分门店使用"	须小于 256
subtype	string	否	子营销类型	礼品卡、满减券	非空时须大于 0 且小于等于 64
value	number	否	营销分值，某些类型的营销会有，积分和 discount_amount 有一定的关系	积分、卡的值消耗一定积分，换取一定优惠	非空时须大于等于 0
discount_range	number	是	营销适用维度： •1：订单维度 •2：商品维度	1
code	string	是	优惠券编码	"49dkjg04jf04kg"

响应示例

正常示例

{
  "err_no": 0,
  "err_tips": "success",
  "data": {
    "err_no": 0,
    "err_tips": "",
    "goods_marketing_result": [
      {
        "goods_id": "7116845279713691692",
        "quantity": 1,
        "total_amount": 100,
        "available_marketing": {
          "coupon_info": [
            {
              "id": "coupon_id_90_fen_MOCK_",
              "code": "coupon_id_90_fen_MOCK_",
              "type": 2,
              "name": "满 0.91 减 0.90 元的满减优惠券",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "receive_time": 1665913601000,
              "discount_amount": 90,
              "detail_url": "优惠券详情跳转链接",
              "rule": "【规则】coupon_id 和 coupon_code = coupon_id_90_fen_MOCK_ ； 券名 = 满 0.91 减 0.90 元的满减优惠券"
            }
          ],
          "score_info": [
            {
              "id": "score_id_1_fen_MOCK_",
              "value": 10000,
              "name": "本店第 4 种积分类型"
            },
            {
              "id": "score_id_2_fen_MOCK_",
              "value": 10000,
              "name": "本店第 5 种积分类型"
            }
          ],
          "activity_info": [
            {
              "id": "activity_id_2_fen_MOCK_",
              "name": "满 0.20 减 0.02 元的满减活动",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "rule": "【规则】activity_id = activity_id_2_fen_MOCK_ ； 活动名 = 满 0.20 减 0.02 元的满减活动"
            },
            {
              "id": "activity_id_1_fen_MOCK_",
              "name": "满 0.10 减 0.01 元的满减活动",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "rule": "【规则】activity_id = activity_id_1_fen_MOCK_ ； 活动名 = 满 0.10 减 0.01 元的满减活动"
            }
          ]
        },
        "unavailable_marketing": {
          "coupon_info": [
            {
              "id": "coupon_id_399_90_yuan_MOCK_",
              "code": "coupon_id_399_90_yuan_MOCK_",
              "type": 1,
              "name": "立减 399.90 元的立减优惠券",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "receive_time": 1665913601000,
              "discount_amount": 39990,
              "detail_url": "优惠券详情跳转链接",
              "rule": "【规则】coupon_id 和 coupon_code = coupon_id_399_90_yuan_MOCK_ ； 券名 = 立减 399.90 元的立减优惠券"
            },
            {
              "id": "coupon_id_59_95_yuan_MOCK_",
              "code": "coupon_id_59_95_yuan_MOCK_",
              "type": 1,
              "name": "立减 59.95 元的立减优惠券",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "receive_time": 1665913601000,
              "discount_amount": 5995,
              "detail_url": "优惠券详情跳转链接",
              "rule": "【规则】coupon_id 和 coupon_code = coupon_id_59_95_yuan_MOCK_ ； 券名 = 立减 59.95 元的立减优惠券"
            }
          ],
          "score_info": [
            {
              "id": "score_id_life_100_yuan_MOCK_",
              "value": 8000,
              "name": "与本地生活融合专用积分-100元钱"
            },
            {
              "id": "score_id_life_200_yuan_MOCK_",
              "value": 8000,
              "name": "与本地生活融合专用积分-200元钱"
            }
          ],
          "activity_info": [
            {
              "id": "activity_id_198_yuan_MOCK_",
              "name": "满 199.00 减 198.00 元的满减活动",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "rule": "【规则】activity_id = activity_id_198_yuan_MOCK_ ； 活动名 = 满 199.00 减 198.00 元的满减活动"
            },
            {
              "id": "activity_id_man_200_50_fen_MOCK_",
              "name": "满 2.00 减 0.50 元的满减活动",
              "start_time": 1665913600000,
              "end_time": 1666172800000,
              "rule": "【规则】activity_id = activity_id_man_200_50_fen_MOCK_ ； 活动名 = 满 2.00 减 0.50 元的满减活动"
            }
          ]
        }
      }
    ],
    "order_marketing_result": {
      "total_amount": 100,
      "available_marketing": {},
      "unavailable_marketing": {}
    },
    "calculation_result": {
      "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": "参数错误"
}

错误码

响应错误码 0 代表成功，其他代表错误，具体的错误码由开发者服务确定。

营销查询算价二合一

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​msg 字段​

​goods_marketing_info 元素结构说明​

​order_marketing_info 结构说明​

​membership_info 元素结构说明​

​coupon_info 元素结构说明​

​activity_info 元素结构说明​

​score_info 元素结构说明​

​请求示例​

​响应参数​

​data 字段​

​goods_marketing_result 元素结构说明​

​order_marketing_result 元素结构说明​

​calculation_result 元素结构说明​

​goods_calculation_result_info 元素结构说明​

​item_calculation_result_info 元素结构说明​

​MarketingDetail 结构说明​

​响应示例​

​正常示例​

​异常示例​

​错误码​