定向计划接口 | 微信开放文档

# 定向计划接口

接口名称	说明
创建定向计划	支持开发者创建定向计划
查询计划列表和详情	支持开发者根据计划状态查询已创建的定向计划或特定计划的详情
查询计划商品列表	支持开发者查询特定计划的商品信息
查询计划推客列表	支持开发者查询特定计划的推客信息
更新定向计划	支持开发者更新已有计划的基本信息和新增计划商品
审批推客	支持开发者审批特定计划内的推客

# 1.创建定向计划

# 接口说明

创建定向计划

# 请求地址

POST https://api.weixin.qq.com/union/shop/target/add_plan?access_token=ACCESS_TOKEN

# 请求参数

注意：给商品设置定向佣金需先设置基础佣金，否则定向佣金将失效。

属性	类型	必填	说明
access_token	string	是	接口调用凭证
productList	Array.<object>	是	商品id列表
planItem	object	是	计划信息

productList 的结构

属性	类型	必填	说明
productId	string	是	商品SPUID，商品需提前设置基础佣金，否则定向佣金失效
rate	number	是	商品定向佣金比例，基准类目佣金<=佣金比例<=90%

planItem 的结构

属性	类型	必填	说明
planName	string	是	计划名称，最多20字
planDesc	string	是	计划描述，最多100字
planStartTime	number	是	计划开始时间戳，至少需在创建计划后一天
planEndTime	number	是	计划结束时间戳，8天<=结束时间-开始时间<=365天

# 请求参数示例

{
    "productList":[
        {"productId":"411664954","rate":1500}
    ],
    "planItem":{
        "planName": "新计划",
        "planDesc":"新计划",
        "planStartTime":1631203200,
        "planEndTime":1631894400
    }
}

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息
planId	string	计划id
planType	string	计划类型,参考枚举值 PROMOTION_TARGETED_PLAN_TYPE
inviteUrl	string	邀请链接

PROMOTION_TARGETED_PLAN_TYPE 的枚举

属性	说明
PROMOTION_TARGETED_PLAN_TYPE_OPEN	小程序定向计划

# 返回示例

var exceptResp = {
    "errcode": 0,
    "errmsg": "ok",
    "planId": "d3g1MzllMGI0ODcyZjE5NmQxLDIwMjUzMjg5NjY0MDc5NjI2MjQ=",
    "planType": "PROMOTION_TARGETED_PLAN_TYPE_OPEN",
    "inviteUrl": "https://union.weixin.qq.com/mp/promoter/target/addPlan?planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMjUzMjg5NjY0MDc5NjI2MjQ="
}

# 2.查询计划列表或详情

# 接口说明

查询计划列表

# 请求地址

GET https://api.weixin.qq.com/union/shop/target/plan_list?access_token=ACCESS_TOKEN

# 请求参数（查询计划列表）

属性	类型	必填	说明
access_token	string	是	接口调用凭证
offset	number	是	列表起始位置
limit	number	是	每页数量
planStatus	string	是	计划状态，参考PLAN_STATUS

# 请求参数（查询计划详情）

属性	类型	必填	说明
access_token	string	是	接口调用凭证
planId	string	是	查询单个计划详情

PLAN_STATUS 的枚举

属性	说明
VALID	有效
INVALID	失效

# 请求参数示例

查计划列表：
?access_token={{access_token}}&offset=0&limit=17&planStatus=VALID
查计划详情：
?access_token={{access_token}}&planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMzU1MzI3NzY3MTk5MjUyNDgsMQ==

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息
planList	Array.<object>	计划列表
total	number	总计
plan	object	计划详情

planList/plan 的结构

属性	类型	说明
planId	string	计划id
planName	string	计划名称
planStatus	string	计划状态，参考 PLAN_STATUS
planType	string	计划类型，参考 PROMOTION_TARGETED_PLAN_TYPE
planDesc	string	计划描述
planStartTime	number	计划开始时间戳
planEndTime	number	计划结束时间戳
acceptPromoterCnt	number	过审推客数
auditingPromoterCnt	number	待审批推客数
inviteUrl	string	邀请链接

# 返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "planList": [
        {
            "planId": "d3g1MzllMGI0ODcyZjE5NmQxLDIwMjU0MTQzOTUwMTg3NTYwOTYsMQ==",
            "planName": "参数加了plantype",
            "planStatus": "VALID",
            "planType": "PROMOTION_TARGETED_PLAN_TYPE_OPEN",
            "planDesc": "最后一个",
            "planStartTime": 1630339200,
            "planEndTime": 1631203200,
            "acceptPromoterCnt": 0,
            "auditingPromoterCnt": 0,
            "inviteUrl": "https://union.weixin.qq.com/mp/promoter/target/addPlan?planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMjU0MTQzOTUwMTg3NTYwOTYsMQ=="
        }
    ],
    "total": 17
}

# 3.查询计划商品列表

# 接口说明

查询计划商品列表

# 请求地址

GET https://api.weixin.qq.com/union/shop/target/product_list?access_token=ACCESS_TOKEN

# 请求参数

属性	类型	必填	说明
access_token	string	是	接口调用凭证
planId	string	是	计划id
offset	number	是	列表起始位置
limit	number	是	每页数量

# 请求参数示例

?access_token={{access_token}}&planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMjc5MDI2OTY3NzAzODc5NjgsdW5kZWZpbmVk&offset=0&limit=10

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息
productList	Array.<object>	商品列表

productList 的结构

属性	类型	说明
productId	string	商品id
outProductId	string	商家自定义商品id
title	string	商品标题
headImg	string	主图
cats	Array.<object>	类目
path	string	商品path
minPrice	number	最低价格，单位为分
totalStockNum	number	总库存
commissionRatio	number	佣金比例

cats 的结构

属性	类型	说明
catId	string	类目ID
name	string	类目名称
level	number	类目级别

# 返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "productList": [
        {
            "productId": "411664954",
            "outProductId": "1625193120000",
            "title": "封面设计图兑换封面使用权(1625193120000)",
            "headImg": "https://store.mp.video.tencent-cloud.com/161/20304/snscosdownload/SH/reserved/60cc6f6200022e3f0000000049ec7164000000a000004f50?imageView2/3/w/750",
            "cats": [
                {
                    "catId": "1495",
                    "level": 1,
                    "name": "家用电器"
                },
                {
                    "catId": "1559",
                    "level": 2,
                    "name": "商用电器"
                },
                {
                    "catId": "1600",
                    "level": 3,
                    "name": "香肠/热狗机"
                }
            ],
            "path": "pages/productDetail/productDetail?productId=1625193120000",
            "minPrice": 1,
            "totalStockNum": 100,
            "commissionRatio": 1500
        }
    ]
}

# 4.查询计划推客列表

# 接口说明

查询计划推客列表

# 请求地址

GET https://api.weixin.qq.com/union/shop/target/promoter_list?access_token=ACCESS_TOKEN

# 请求参数

属性	类型	必填	说明
access_token	string	是	接口调用凭证
planId	string	是	计划id
offset	number	是	列表起始位置
limit	number	是	每页数量

# 请求参数示例

?access_token={{access_token}}&planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMzU1MzI3NzY3MTk5MjUyNDgsMQ==&offset=0&limit=10

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息
promoterList	Array.<object>	推客列表

promoterList 的结构

属性	类型	说明
appid	string	appid
nickname	string	推客名称
promoterType	string	账号类型,参考 PROMOTER_YTYPE
applyTime	number	申请时间
promoterStatus	string	过审状态，参考 PROMOTER_STATUS
joinTime	number	通过时间
applyReason	string	申请理由

PROMOTER_YTYPE 的枚举

属性	说明
MERCHANT	企业
PERSONAL	个人

PROMOTER_STATUS 的枚举

属性	说明
INIT	可以报名
AUDITING	待审核
ACCEPTED	已同意
REJECTED	已拒绝

# 返回示例

{
    "errcode": 0,
    "errmsg": "ok",
    "promoterList": [
        {
            "appid": "wx216c2a6a0658b53e",
            "nickname": "这里也很重要",
            "promoterType": "MERCHANT",
            "applyTime": 1630465151,
            "promoterStatus": "AUDITING",
            "joinTime": 0,
            "applyReason": ""
        }
    ]
}

# 5.更新定向计划

# 接口说明

更新定向计划

# 请求地址

POST https://api.weixin.qq.com/union/shop/target/update_plan?access_token=ACCESS_TOKEN

# 请求参数

属性	类型	必填	说明
access_token	string	是	接口调用凭证
productList	Array.<object>	否	商品id列表
planItem	object	否	计划信息
planId	string	是	计划id

productList 的结构

属性	类型	必填	说明
productId	string	否	需要新增的商品id
rate	number	否	需要新增商品的定向佣金比例，基准类目佣金<=佣金比例<=90% 金

planItem 的结构

属性	类型	必填	说明
planName	string	否	计划名称
planDesc	string	否	计划描述
planStartTime	number	否	计划开始时间戳，到开始时间后不可传入此项
planEndTime	number	否	计划结束时间戳，到开始时间后不可传入此项
planStatus	string	否	是否结束计划，结束后计划即失效

PLAN_STATUS 的枚举

属性	说明
VALID	不结束计划
INVALID	结束计划

# 请求参数示例

{
    "planId": "d3g1MzllMGI0ODcyZjE5NmQxLDIwMzg2MDUyNDQxNzA5MTE3NDQsMQ==",
    "productList":[
        {"productId":"411664954","rate":1500}
    ],
    "planItem":{
        "planName": "新计划",
        "planDesc":"新计划",
        "planStartTime":1631203200,
        "planEndTime":1631894400,
        "planStatus": "INVALID"
    }
}

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息
planId	string	计划id
inviteUrl	string	邀请链接

# 返回示例

var exceptResp = {
    "errcode": 0,
    "errmsg": "ok",
    "planId": "d3g1MzllMGI0ODcyZjE5NmQxLDIwMjUzMjg5NjY0MDc5NjI2MjQ=",
    "inviteUrl": "https://union.weixin.qq.com/mp/promoter/target/addPlan?planId=d3g1MzllMGI0ODcyZjE5NmQxLDIwMjUzMjg5NjY0MDc5NjI2MjQ="
}

# 6.审批推客

# 接口说明

审批推客

# 请求地址

POST https://api.weixin.qq.com/union/shop/target/update_promoter?access_token=ACCESS_TOKEN

# 请求参数

属性	类型	必填	说明
access_token	string	是	接口调用凭证
appidList	Array.<string>	是	appid列表
promoterStatus	string	是	推客状态
planId	string	是	计划id

PROMOTER_STATUS 的枚举

属性	说明
ACCEPTED	已同意
REJECTED	已拒绝

# 请求参数示例

{
    "appidList" : ["wx216c2a6a0658b53e"],
    "promoterStatus": "ACCEPTED",
    "planId": "d3g1MzllMGI0ODcyZjE5NmQxLDIwMjc5NDE3MTE2ODI4Nzk0ODgsMQ=="
}

# 返回值

属性	类型	说明
errcode	number	错误码
errmsg	string	错误信息

# 返回示例

var exceptResp = {
    "errcode": 0,
    "errmsg": "ok",
}

# 返回码

值	说明
200002	参数错误
203001	计划达到上限
203002	计划不存在
203003	计划已失效