查询营销信息扩展点
开发环境
http://dev-cn.your-api-server.com
开发环境
http://dev-cn.your-api-server.com
POST
/api/v2/query_marketing_info
基本信息
| 基本信息 | |
|---|---|
| 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 字节 |
请求示例请求示例
Shell
JavaScript
Java
Swift
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