查询营销信息扩展点

我的收藏

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

使用限制

无

接口说明

无

基本信息

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

请求头

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

请求参数

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

名称

类型

是否必填

描述

示例值

msg

string

是

营销信息查询请求细节 JSON 字符串。

注意：

msg 本身是 string
msg string 的内容是 JSON 格式的，JSON 转 string 需要转义
如遇问题，请仔细请求示例

参见请求示例的 msg 部分

type

string

是

枚举值：

pre_create_order 预下单回调

pre_create_refund 预退款回调

query_marketing_info 查询营销信息

calculate_price 算价回调

"query_marketing_info"

version

string

是

固定值： 2.0。

callback 版本，用于开发者识别回调参数的变更

"2.0"

msg 字段

名称	类型	是否必填	描述	示例值
open_id	string	是	用户 open_id	"123rq0gjhdfoqierug"
goods_info	list<object>	是	商品信息列表	[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)，请返回可用和不可用的优惠信息

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

msg 内部结构：

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

响应参数

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

扩展服务会校验开发者服务返回的营销信息，校验整体分为 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	list<object>	否	用户身份信息(如会员)	[membership1, membership2]
coupon_info	list<object>	否	优惠券信息	[coupon1, coupon2]
activity_info	list<object>	否	活动信息	[activity1, activity2]
score_info	list<object>	否	积分信息	[score1, score2]
goods_valid_marketing_info	object	否	商品可用营销方案信息
order_valid_marketing_info	object	否	订单可用营销方案信息

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

名称

类型

是否必填

描述

示例值

检验逻辑

value

number

是

可用积分值

9527

>= 0

string

是

积分 id，如“JingDong-vip”表示京东 VIP 会员积分，再比如可能会有具体某个店铺的积分，很多大店铺是有自己的积分系统的

"390dknvi0o4"

非空，<= 64 字节

name

string

是

积分名字：如：京东 VIP 会员积分

同上

非空，<= 64 字节

goods_valid_marketing_info 结构说明

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

名称

类型

是否必填

描述

示例值

检验逻辑

valid_marketing_info

list<object>

（GoodsValidMarketing）

是

商品维度的可用营销

包含的商品信息需要和 req 一致

default_marketing_info

list<object>

（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中个类型营销列表中的第一个作为默认展示		默认营销是可用营销的子集

名称

类型

是否必填

描述

示例值

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<object>	否	可用积分信息	[score1, score2]	参考 score_info 元素结构校验
activity_ids	list	否	可参与活动 id 列表	["388niv0oe", "1948fh"]	每个 id 非空，长度 <= 64 字节

响应示例

正常示例

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

异常示例

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

错误码

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

下一篇：小程序文档指引