# 优选联盟 ## 开发前准备 - **功能了解**：开发前建议先阅读以下运营文档了解完整业务流程 - [微信小店「优选联盟」使用指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/1671/fd52d98dab79a925/growth_center_manual_for_store/2) - [商家使用「推客带货」操作手册](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7608/d072b46ed9821c5d/growth_center_manual_for_store) - [商家使用「推客带货」经营指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7737/9427b4a5e07b32a8/growth_center_ec_operation) - [《微信小店优选联盟准入及清退规则》](https://store.weixin.qq.com/chengzhang/webdoc/wiki/2091/dbce962d58fbd6ac/growth_center_rule_for_store) - **权限与凭证**：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对权限集 ID：141 的授权，使用 authorizer_access_token - **消息推送配置**：本模块无事件通知，无需配置 - **前置条件**：商家需先在[微信小店管理后台](https://store.weixin.qq.com/shop/home)开通优选联盟功能，未开通时调用接口会返回错误码 10023007 ## 推广体系说明 优选联盟是微信小店的商品推广分销平台，商家通过接口管理带货者合作关系和商品推广计划。整体分为**带货者管理**和**商品推广**两大模块。 **推广类型对比：** | 对比项 | 普通推广 | 定向推广 | 专属推广 | |-------|---------|---------|---------| | 适用场景 | 面向全平台带货者的公开推广 | 面向指定带货者的定向合作 | 为特定带货者定制的独家推广 | | 带货者范围 | 所有带货者均可推广 | 需指定带货者列表 | 需指定带货者列表 | | 佣金设置 | 统一佣金比例 | 按计划设置佣金 | 按计划设置佣金 | | 互斥规则 | 与专属推广互斥 | 依赖普通推广先上架 | 与普通/定向推广互斥 | | type 枚举值 | 1 | 2 | 3 | > 多个接口同时支持 `finder_id` 和 `promoter_id` 两个参数，`finder_id` 已标注待废弃，开发者应优先使用 `promoter_id`（带货者 ID） ## 接入流程 ### 一、带货者管理流程 商家通过接口查询带货者信息，并对合作关系进行管理： ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A["[API] 获取带货者列表
getpromoterlist"] --> B["[API] 获取带货者详情信息
getpromoter"] B --> C{需要操作?} C -- 管理合作关系 --> D["[API] 编辑带货者
updpromoter"] C -- 查看商品数据 --> E["[API] 获取带货者商品数据列表
getproductdatalist"] D --> A style C fill:#ffffff,stroke:#0ab8a6,color:#666666 ``` **带货者管理要点：** - [API] [获取带货者列表 / getpromoterlist](/doc/store/shop/API/league/promoter/api_getpromoterlist) 分页获取商家已合作的带货者列表 - [API] [获取带货者详情信息 / getpromoter](/doc/store/shop/API/league/promoter/api_getpromoter) 获取带货者基础信息、销售数据和等级 - [API] [编辑带货者 / updpromoter](../../API/league/promoter/api_updpromoter) 支持两种操作：`type=1` 取消邀请、`type=2` 结束合作 - [API] [获取带货者商品数据列表 / getproductdatalist](1000300promoter/api_getproductdatalist.html) 查询带货者推广商品的销售和佣金数据 ### 二、商品推广管理流程 商家将商品添加到优选联盟进行推广，支持批量操作： ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR P["获取 product_id
（商品管理接口）"] --> A Q["[API] 获取带货者列表
getpromoterlist
（获取 promoter_ids）"] --> A A["[API] 批量新增联盟商品
batchadditem"] --> B["[API] 获取联盟商品推广列表
getitemlist"] B --> C["[API] 获取联盟商品详情
getitem"] C --> D{调整推广?} D -- 修改佣金/上下架 --> E["[API] 更新联盟商品信息
upditem"] D -- 删除推广 --> F["[API] 删除联盟商品
deleteitem"] E --> B F --> B style D fill:#ffffff,stroke:#0ab8a6,color:#666666 style P fill:#ffffff,stroke:#0ab8a6,color:#666666 ``` **商品推广管理要点：** - 调用 [API] [批量新增联盟商品 / batchadditem](/doc/store/shop/API/league/item/api_batchadditem) 前需准备两类参数： - **`product_id`**：通过商品管理接口获取商品 ID - **`promoter_ids`**（定向/专属推广时必填）：通过 [API] [获取带货者列表 / getpromoterlist](/doc/store/shop/API/league/promoter/api_getpromoterlist) 获取带货者的 `talent_appid` → `promoter_id` - [API] [批量新增联盟商品 / batchadditem](/doc/store/shop/API/league/item/api_batchadditem) 每次最多添加 20 个商品，佣金比例范围为 0~90% - 推广类型通过 `type` 字段区分：1-普通推广、2-定向推广、3-专属推广 - 定向推广和专属推广需指定带货者列表（`promoter_ids`），每次不超过 30 个带货者 - 普通/定向推广与专属推广互斥（错误码 10023105），定向推广要求普通推广先上架（错误码 10023106） - [API] [更新联盟商品信息 / upditem](/doc/store/shop/API/league/item/api_upditem) 的 `operate_type` 支持：1-编辑并上架、2-下架、4-上架 - 商品需为已上架状态才可添加推广（错误码 10023104），被运营处罚或类目禁售的商品无法上架推广 ### 三、联盟机构推广流程（按需接入） 联盟带货机构（headsupplier）可通过商家授权，为商家批量设置机构推广计划： ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A[商家授权机构] --> B["[API] 批量新增联盟机构推广
batchaddheadsupplieritem"] B --> C[机构推广生效] style A fill:#ffffff,stroke:#0ab8a6,color:#666666 style C fill:#ffffff,stroke:#0ab8a6,color:#666666 ``` - [API] [批量新增联盟机构推广 / batchaddheadsupplieritem](/doc/store/shop/API/league/item/api_batchaddheadsupplieritem) 需传入 `headsupplier_appid`（机构开放唯一凭证） - 机构计划类型通过 `commission_type` 区分：0-商家指定带货者佣金、1-机构指定带货者佣金（总包计划） - 需同时设置推广佣金（`ratio`）和推广服务费（`service_ratio`），范围均为 0~90% ### 四、商品推广状态流转 ```mermaid %%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0ab8a6', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#089e8d', 'lineColor': '#0ab8a6', 'secondaryColor': '#07827a', 'secondaryTextColor': '#ffffff', 'secondaryBorderColor': '#055f59', 'tertiaryColor': '#0ab8a6', 'tertiaryTextColor': '#ffffff', 'tertiaryBorderColor': '#089e8d', 'edgeLabelBackground': '#888888', 'fontColor': '#888888'}}}%% flowchart LR A["待生效(10)"] --> B["已上架推广(1)"] B --> C["已下架推广(2)"] C --> B B --> D["已删除(4)"] C --> D E["未达到准入标准(5)"] --> B ``` > 状态码说明：10-待生效、1-已上架推广、2-已下架推广、4-已删除、5-未达到准入标准 ## 接口全览 ### 带货者操作 | 中文名 / 英文名 | 请求方式 | 功能说明 | |----------------|---------|---------| | [获取带货者详情信息](/doc/store/shop/API/league/promoter/api_getpromoter) / getpromoter | `POST /channels/ec/league/promoter/get` | 获取带货者基础信息、销售数据和等级 | | [获取带货者列表](/doc/store/shop/API/league/promoter/api_getpromoterlist) / getpromoterlist | `POST /channels/ec/league/promoter/list/get` | 分页获取商家合作的带货者列表 | | [获取带货者商品数据列表](1000300promoter/api_getproductdatalist.html) / getproductdatalist | `POST /channels/ec/league/promoter/product/datalist/get` | 查询带货者推广商品的销售和佣金数据 | | [编辑带货者](../../API/league/promoter/api_updpromoter) / updpromoter | `POST /channels/ec/league/promoter/upd` | 取消邀请或结束合作 | ### 商品操作 | 中文名 / 英文名 | 请求方式 | 功能说明 | |----------------|---------|---------| | [批量新增联盟商品](/doc/store/shop/API/league/item/api_batchadditem) / batchadditem | `POST /channels/ec/league/item/batchadd` | 批量添加商品到联盟推广，最多 20 个 | | [删除联盟商品](../../API/league/item/api_deleteitem) / deleteitem | `POST /channels/ec/league/item/delete` | 删除联盟推广商品 | | [获取联盟商品详情](/doc/store/shop/API/league/item/api_getitem) / getitem | `POST /channels/ec/league/item/get` | 获取推广状态、佣金、绑定带货者列表 | | [批量新增联盟机构推广](/doc/store/shop/API/league/item/api_batchaddheadsupplieritem) / batchaddheadsupplieritem | `POST /channels/ec/league/item/headsupplier/batchadd` | 机构为商家批量设置推广计划 | | [获取联盟商品推广列表](/doc/store/shop/API/league/item/api_getitemlist) / getitemlist | `POST /channels/ec/league/item/list/get` | 分页获取联盟推广商品列表 | | [更新联盟商品信息](/doc/store/shop/API/league/item/api_upditem) / upditem | `POST /channels/ec/league/item/upd` | 修改佣金、上下架推广商品 | > 官方完整接口列表：[优选联盟 接口列表](/doc/store/shop/API/league/) ## 常见问题 FAQ **Q：普通推广和定向推广可以同时存在吗？** A：可以。普通推广面向全平台带货者，定向推广是在普通推广基础上为指定带货者设置差异化佣金。但定向推广要求普通推广已上架（否则返回错误码 10023106）。普通/定向推广与专属推广互斥。 **Q：`finder_id` 和 `promoter_id` 应该用哪个？** A：优先使用 `promoter_id`（带货者 ID）。`finder_id`（视频号 finder_id）已标注待废弃，后续将不再支持。两个参数二选一传入即可。 **Q：批量操作的数量限制是多少？** A：[API] [批量新增联盟商品 / batchadditem](/doc/store/shop/API/league/item/api_batchadditem) 每次最多 20 个商品；定向/专属推广绑定带货者每次不超过 30 个；[API] [获取联盟商品推广列表 / getitemlist](/doc/store/shop/API/league/item/api_getitemlist) 单页最多 100 条，`page_size × page_index` 不超过 5000，超出时建议使用 `last_buffer` 顺序翻页。 **Q：联盟带货机构接入优选联盟有独立文档吗？** A：有。带货机构（headsupplier）有独立的文档站，与本文商家端接口为不同体系。机构端接入请参阅：[联盟带货机构开发指南](/doc/store/leagueheadsupplier/README.md) ![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（1条） 2026 年 05 月 06 日新增 优选联盟 开发指南