推广数据接口 | 微信开放文档

# 推广数据接口

# 一、生成推广素材

# 接口说明

商户通过对接该接口，推广员可以通过以下两种方式推广所绑定的商家小程序： a）小程序卡片：进入小程序后，直接转发商品/活动页面至单聊/群聊，以小程序卡片的形式推广； b）小程序素材：转发通过平台转链接口生成的小程序码、tag等小程序素材，以小程序图片/链接素材的形式推广。注：推广素材的有效期为30天，素材失效后请重新获取。

# 请求地址

POST https://api.weixin.qq.com/promoter/getsharematerial?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
path	string	是	小程序页面path
openid	string	是	推广员的openid或unionid
extra_info	string	否	自定义参数，长度不能超过80个字符
title	string	否	页面名称，长度不能超过20个字符，默认为“推广活动页”
share_type	uint32	否	0：三种分享素材全返回 1、短链 2、带参path 3：小程序码（默认全部返回）
env_version	string	否	默认正式版，develop: 开发版， trial: 体验版，仅短链支持跳转开发版/体验版

注1：只有商家已声明且推广员已授权才可生成分享素材，否则会返回103006（数据不存在）。注2：分享素材的有效期为30天，素材失效后请重新获取。注3：只有短链（share_type=1）支持跳转到开发版/体验版。

# 请求示例

{
  "path": "xxxxx",
  "openid": "xxxxx",
  "extra_info": "xxxxx",
  "title": "xxxxx",
  "share_type": 0,
  "env_version": "trial"
}

# 返回值

属性	类型	说明
share_path	string	带参path
qrcode	string	小程序码（图片base64）
tag	string	短链
errcode	int32	错误码
errmsg	string	错误信息

# 返回数据示例

{
  "share_path": "xxxxx",
  "qrcode": "xxxxx",
  "tag": "xxxxx",
  "errcode": 0,
  "errmsg": "OK"
}

# 二、分析触达效果

# 接口说明

商家可通过接口查询特定推广员在特定时间内带来的访问用户情况。

# 请求地址

POST https://api.weixin.qq.com/promoter/getrelation?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
openid	string	是	推广员的openid或unionid
begin_time	uint32	否	触达时间开始秒级时间戳
end_time	uint32	否	触达时间结束秒级时间戳
scene	uint32	否	触达场景值，枚举值参考场景值列表
path	string	否	触达path，原生分享path里参数可能乱序导致搜不到
start_id	string	否	用于分页时透传，单次拉取上限为1000，超过1000须分页
need_unionid	uint32	否	默认返回openid，填1：返回unionid

# 请求示例

{
  "openid": "xxxxx",
  "begin_time": 1668614400,
  "end_time": 1668666429,
  "scene": 1077,
  "path": "pages/xxxxx",
  "start_id": "123",
  "need_unionid": 1
}

# 返回值

属性	类型	说明
promoter_openid	string	推广员的openid或unionid
role_id	uint32	角色id
retail_id	string	门店id
extra_info	string	推广员参数
openid	string	触达后访问小程序的用户openid或unionid
create_time	uint32	触达时间秒级时间戳
path	string	触达path
scene	uint32	触达场景值，枚举值参考场景值列表
share_extra_info	string	生成分享素材时的自定义参数
total_cnt	uint32	拉取的推广员总数
start_id	string	用于分页时透传
errcode	int32	错误码
errmsg	string	错误信息

注：需要分页时把返回的start_id塞到请求里，如果total_cnt小于1000或者返回为空（错误码：103006，数据不存在）表明数据拉取完成。

# 返回数据示例

{
  "relation_list":
  [
    {
      "promoter_openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "openid": "xxxxx",
      "create_time": 1668667349,
      "path": "pages/xxxxx",
      "scene": 1077,
      "share_extra_info": "xxxxx"
    },
    {
      "promoter_openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "openid": "xxxxx",
      "create_time": 1668667349,
      "path": "pages/xxxxx",
      "scene": 1077,
      "share_extra_info": "xxxxx"
    }
  ],
  "total_cnt": 2,
  "start_id": "2",
  "errcode": 0,
  "errmsg": "OK"
}

# 三、查询推广订单

# 接口说明

本接口所查询的订单将归因给订单产生前最后触达用户（触达：用户通过推广素材进入小程序）的推广员，若商家有其他诉求（比如订单应当归属于用户所绑定的推广员，而与推广员触达用户的先后无关），可以考虑基于推广员对用户的触达效果（参考「第二节」）、结合自身的订单数据做推广订单的归因。

# 请求地址

POST https://api.weixin.qq.com/promoter/getorder?access_token=ACCESS_TOKEN

# 请求参数

参数	类型	是否必填	说明
openid	string	是	推广员的openid或unionid
mch_id	string	否	商户号
trade_no	string	否	微信支付订单号
out_trade_no	string	否	商户订单号
status uint32	否	订单状态 1：支付完成 2：退款受理
start_id	string	否	用于分页时透传，单次拉取上限为1000，超过1000须分页
need_unionid	uint32	否	默认返回openid，填1：返回unionid
date	uint32	否	订单支付日期，格式为yyyyMMdd，例如20230801

# 请求示例

{
  "openid": "xxxxx",
  "mch_id": "xxxxx",
  "trade_no": "xxxxx",
  "out_trade_no": "xxxxx",
  "status": 1,
  "start_id": "123",
  "need_unionid": 1
}

# 返回值

属性	类型	说明
promoter_openid	string	推广员的openid或unionid
role_id	uint32	角色id
retail_id	string	门店id
extra_info	string	推广员参数
openid	string	付款用户的openid或unionid
create_time	uint32	触达时间秒级时间戳
path	string	触达path
scene	uint32	触达场景值，枚举值参考场景值列表
share_extra_info	string	生成分享素材时的自定义参数
mch_id	string	商户号
trade_no	string	微信支付订单号
out_trade_no	string	商户订单号
status	uint32	订单状态 1：支付完成 2：退款受理
paid_amount	uint32	用户支付金额，单位为分
paid_time	uint32	支付完成时间
refunded_time	uint32	退款创建时间
total_cnt	uint32	拉取的推广员总数
start_id	string	用于分页时透传
errcode	int32	错误码
errmsg	string	错误信息

注：需要分页时把返回的start_id塞到请求里，如果total_cnt小于1000或者返回为空（错误码：103006，数据不存在）表明数据拉取完成。

# 返回数据示例

{
  "order_list":
  [
    {
      "promoter_openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "openid": "xxxxx",
      "create_time": 1668667349,
      "path": "pages/xxxxx",
      "scene": 1077,
      "share_extra_info": "xxxxx",
      "mch_id": "xxxxx",
      "trade_no": "xxxxx",
      "out_trade_no": "xxxxx",
      "status": 1,
      "paid_amount": 150,
      "paid_time": 1668667360
    },
    {
      "promoter_openid": "xxxxx",
      "role_id": 1,
      "retail_id": "xxxxx",
      "extra_info": "xxxxx",
      "openid": "xxxxx",
      "create_time": 1668667349,
      "path": "pages/xxxxx",
      "scene": 1077,
      "share_extra_info": "xxxxx",
      "mch_id": "xxxxx",
      "trade_no": "xxxxx",
      "out_trade_no": "xxxxx",
      "status": 2,
      "paid_amount": 150,
      "paid_time": 1668667360,
      "paid_time": 1668668000
    }
  ],
  "total_cnt": 2,
  "start_id": "2",
  "errcode": 0,
  "errmsg": "OK"
}