查询营销信息扩展点

基本信息

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

msg 字段

名称	类型	是否必填	描述	示例值
open_id	string	是	用户 open_id	"123rq0gjhdfoqierug"
goods_info	list	是	商品信息列表	[goods1, goods2]
app_id	string	是	小程序 id	"ttcfdbb96650e33351"
union_id	string	否	用户的 UnionID	"123rq0gjhdfoqieee"
callback_data	string	否	透传参数

goods_info 字段

名称	类型	是否必填	描述	示例值
goods_id	string	是	商品 id	"09893085485dasdfa"
quantity	int	是	商品数量	2
price	int	是	商品单价，单位[分]	19900

请求示例

这个请求表达的含义是：用户(M3arp6xWNPyvKnHf)准备购买3份商品(7112741589566392364)，请返回可用和不可用的优惠信息

msg 内部结构：

{
"open_id": "123rq0gjhdfoqierug",
"app_id": "ttxxxxxx",
"goods_info": [
{
"goods_id": "7112741589566392364",
"quantity": 3,
"price": 100
}
]
}

响应参数

扩展服务会校验开发者服务返回的营销信息，校验整体分为 2 类：

字段级别：
- 比如：枚举类型限制，关键字段非空校验，string 类型长度校验等。
- 具体逻辑见下面各个结构说明表格。
业务级别，细化如下：
- 4 种营销方式、商品可用营销和订单可用营销信息需要一致。
- - 商品可用营销和订单可用营销信息需要是 4种营销方式的子集。
- Req/Resp 里商品信息必须保持一致。
- - 原则上，resp 里需要对 req 里的每个商品有回应。
  - 为了方便接入，
  - - goods_valid_marketing_info 和 order_valid_marketing_info 都为空，或者 data 为空表示无可用营销信息
    - 如果 goods_valid_marketing_info 不为空，则需要包含和 req 一致的商品信息，结构中可用营销置为空即可（扩展服务会保证 req 里商品不重复）。

data 字段

membership_info，coupon_info，activity_info，score_info是营销的元信息，是该用户所有的营销项合集。
goods_valid_marketing_info，order_valid_marketing_info分别是商品维度和订单维度可用的营销信息

举个例子，用户 Z 准备购买 2 杯星冰乐和 1 杯拿铁，总价 100 元；用户 Z 账户下一共有 4 张优惠券，A-星冰乐单品立减 5 元，B-抹茶蛋糕单品立减 3 元，C-订单满 100-10 元，D-订单满 200-30 元

coupon_info 的长度为 4，分别对应 ABCD 这 4 张优惠券

优惠券 A 对星冰乐可用，优惠券 A 需要在 goods_valid_marketing_info 中

优惠券 C 是订单维度的，满足 100-10 的条件，优惠券 C 需要在 order_valid_marketing_info 中

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 字节

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 字节

goods_valid_marketing_info 结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
valid_marketing_info	list（GoodsValidMarketing）	是	商品维度的可用营销		包含的商品信息需要和 req 一致
default_marketing_info	list（GoodsValidMarketing）	否	商品维度的默认营销策略。如果没有，默认选第一个作为默认展示。		默认营销是可用营销的子集

GoodsValidMarketing 结构说明

名称	类型	是否必填	描述	示例值	检验逻辑
goods_id	string	是	商品id	“83048"	非空
valid_marketing_info	object(marketing_brief)	否	营销策略信息

order_valid_marketing_info 结构说明

订单维度可用

名称	类型	是否必填	描述	示例值
valid_marketing_info	object(marketing_brief)	否	订单维度的可用营销策略
default_marketing_info	object(marketing_brief)	否	订单维度的默认营销策略，如果没有，默认选valid_marketing_info中个类型营销列表中的第一个作为默认展示		默认营销是可用营销的子集

marketing_brief 结构说明

名称	类型	是否必填	描述	参数示例	检验逻辑
membership_ids	list	否	可用身份 id 列表	["12idio3", "23884"]	每个 id 非空，长度 <= 64 字节
coupon_ids	list	否	可用优惠券 id 列表	["09feio", "38dioj4"]	每个 id 非空，长度 <= 64 字节
score_info	list	否	可用积分信息	[score1, score2]	参考 score_info 元素结构校验
activity_ids	list	否	可参与活动 id 列表	["388niv0oe", "1948fh"]	每个 id 非空，长度 <= 64 字节

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", "msg": "{\"open_id\":\"123rq0gjhdfoqierug\",\"app_id\":\"ttxxxxxx\",\"goods_info\":[{\"goods_id\":\"7112741589566392364\",\"quantity\":3,\"total_amount\":100}]}", "type": "query_marketing_info" }'

{ "err_no": 0, "err_tips": "success", "data": { "goods_valid_marketing_info": { "default_marketing_info": [ { "goods_id": "7112741589566392364", "valid_marketing_info": { "activity_ids": ["activity_id_life_12_fen_MOCK_"], "coupon_ids": ["coupon_id_life_270_fen_MOCK_"], "membership_ids": ["membership_id_life_3_fen_MOCK_"], "score_info": [ { "id": "score_id_life_12_fen_MOCK_", "name": "与本地生活融合专用积分-12分钱", "value": 1000 } ] } } ], "valid_marketing_info": [ { "goods_id": "7112741589566392364", "valid_marketing_info": { "activity_ids": ["activity_id_life_12_fen_MOCK_"], "coupon_ids": ["coupon_id_life_270_fen_MOCK_"], "membership_ids": ["membership_id_life_3_fen_MOCK_"], "score_info": [ { "id": "score_id_life_12_fen_MOCK_", "name": "与本地生活融合专用积分-12分钱", "value": 1000 } ] } } ] }, "order_valid_marketing_info": { "default_marketing_info": { "activity_ids": [], "coupon_ids": [], "membership_ids": [], "score_info": [] }, "valid_marketing_info": { "activity_ids": [], "coupon_ids": [], "membership_ids": [], "score_info": [] } }, "score_info": [ { "id": "score_id_life_12_fen_MOCK_", "name": "与本地生活融合专用积分-12分钱", "value": 1000 } ], "activity_info": [ { "end_time": 1666172800000, "id": "activity_id_life_12_fen_MOCK_", "name": "满 0.99 减 0.12 元的满减活动", "rule": "【规则】activity_id = activity_id_life_12_fen_MOCK_ ；活动名 = 满 0.99 减 0.12 元的满减活动", "start_time": 1665913600000 } ], "membership_info": [ { "desc": "与本地生活融合专用会员-3分钱", "id": "membership_id_life_3_fen_MOCK_" } ], "coupon_info": [ { "code": "coupon_id_life_270_fen_MOCK_", "detail_url": "优惠券详情跳转链接", "discount_amount": 270, "end_time": 1666172800000, "id": "coupon_id_life_270_fen_MOCK_", "name": "立减 2.70 元的立减优惠券", "receive_time": 1665913601000, "rule": "【规则】coupon_id 和 coupon_code = coupon_id_life_270_fen_MOCK_ ；券名 = 立减 2.70 元的立减优惠券", "start_time": 1665913600000, "type": 1 } ] } }

请求参数

Query 参数

timestamp

string

必需

示例值:

1345678901234

nonce

string

必需

示例值:

iuy987q4htafreqw

Header 参数

Content-Type

string

必需

示例值:

application/json

Signature

string

必需

示例值:

irqy39487t092h3fiqufheiufhqyt9q

Body 参数application/json

version

string

必需

固定值： 2.0。 callback 版本，用于开发者识别回调参数的变更

msg

string

必需

营销信息查询请求细节 JSON 字符串。注意： msg 本身是 string msg string 的内容是 JSON 格式的，JSON 转 string 需要转义如遇问题，请仔细请求示例

type

string

必需

枚举值： pre_create_order 预下单回调 pre_create_refund 预退款回调 query_marketing_info 查询营销信息 calculate_price 算价回调

示例

返回响应

🟢200成功

application/json

Body

err_no

integer

必需

错误码，0 代表成功

err_tips

string

错误提示信息

必需

data

object

必需

查询营销信息拓展点返回的信息

goods_valid_marketing_info

object

可选

商品可用营销方案信息

order_valid_marketing_info

object

可选

订单可用营销方案信息

score_info

array [object {3}]

积分信息

可选

activity_info

array [object {5}]

活动信息

可选

membership_info

array [object {2}]

可选

用户身份信息(如会员)

coupon_info

array [object {10}]

优惠券信息

可选