查询营销算价扩展点
开发环境
http://dev-cn.your-api-server.com
开发环境
http://dev-cn.your-api-server.com
POST
/api/v2/xxxx
交易系统通过本接口从开发者的服务获取可用的相关营销信息和对应的算价结果展示给用户。调用场景来源：模版组件提单页、营销算价 openAPI
下单时，抖音开平交易系统会携带用户选择营销信息，通过本接口从开发者的服务获取对应的算价结果。
基本信息
| 基本信息 | |
|---|---|
| HTTP URL | 回调地址的设置请参考行业模版使用指南-实现扩展点 query_and_calculate |
| HTTP Method | POST |
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 | 否 | 商品维度用户选用的营销信息 | [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" | 非空 |
| 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 | 否 | 用户身份信息(如会员) | [membership1, membership2] | |
| coupon_info | list | 否 | 优惠券信息 | [coupon1, coupon2] | |
| activity_info | list | 否 | 活动信息 | [activity1, activity2] | |
| score_info | list | 否 | 积分信息 | [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 | 否 | 不可用原因。当优惠券不可用时，开发者可传入不可用原因。 | 未达到满减门槛 | 原因不超过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分，请返回这笔订单可用的优惠信息以及默认最佳优惠的算价结果
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
}
data 字段
说明：
- 如果响应中无data字段，系统认为无可用营销信息
- 如果请求中用户所选的营销不可用（包含1中情况），即用户之前的选择失效，此时外部服务应该报错（err_no不为0）并给出有效的说明信息（err_tips）
- 如果data中无calculation_result字段，系统认为无算价信息，会用商品原价作为算价结果参与后续校验
- goods_marketing_result和order_marketing_result下都有available_marketing和unavailable_marketing字段，它们的区别是优惠适用的维度不同：
-
- goods_marketing_info下的available和unavailable优惠是针对商品的。举个例子，对于商品星冰乐，星冰乐单品优惠券属于available，蛋糕单品优惠券属于unavailable
- order_marketing_info下的available和unavailable优惠是针对订单的。举个例子，总价150的订单，满100-5的优惠券属于available，满200-20优惠券属于unavailable
- 对于一个具体的优惠券，不能同时出现在goods_marketing_result和order_marketing_result中，它适用的优惠维度是明确的
5、order_marketing_result.total_amount = sum(goods_marketing_result.total_amount)
calculation_result 元素结构说明
说明：
1、订单原价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表示单份商品。
2、calculation_type表示优惠分摊的类型，开发者可选择将优惠分摊到商品(goods层)或者每一份商品(item层)
-
- calculation_type=1，开发者将优惠分摊到goods层，需返回goods_calculation_result_info，交易系统会按均摊逻辑帮开发者计算到item层
- calculation_type=2，开发者将优惠分摊到item层，需返回item_calculation_result_info
3、举个例子，一笔订单购买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)
item_calculation_result_info 元素结构说明
说明：
-
是列表，列表的每一项，表示单份商品
-
item total_discount_amount 和营销明细聚合结果必须一致。
-
- total_discount_amount = sum(marketing_detail.discount_amount)
MarketingDetail 结构说明
说明：当 value 不为 0 的时候，discount_amount 不能为 0（即不允许消耗积分却没有折扣）。
-
discount_range，表示优惠的维度，举个例子
-
- 星冰乐单品5折券属于商品维度优惠，discount_range=2
- 订单满200-20属于订单维度优惠，discount_range=1
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST 'http://dev-cn.your-api-server.com/api/v2/xxxx?timestamp=1345678901234&nonce=iuy987q4htafreqw' \
--header 'Signature: irqy39487t092h3fiqufheiufhqyt9q' \
--header 'Content-Type: application/json' \
--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}"
}'响应示例响应示例
200 - 成功示例
{
"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
}
}
}请求参数
Query 参数
timestamp
string
必需
示例值:
1345678901234
nonce
string
必需
示例值:
iuy987q4htafreqw
Header 参数
Content-Type
string
必需
示例值:
application/json
Signature
string
必需
示例值:
irqy39487t092h3fiqufheiufhqyt9q
Body 参数application/json