联盟带货机构推客带货商品实时同步研究v2

• 引用 1 篇资料作为参考

1. 推客商品实时同步
2. 之前的研究文章

基本信息

• 研究目的：探讨如何更优效率同步推客业务的可推广商品数据
• 创建时间：2025 - 07 - 08
• 最近更新：2026 - 02 - 10

可推广商品

API接口

可推广商品相关API接口：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/API/promotion/product/getpromoteproductlist.html

商品的计划类型 plan_type

1. 商家在微信小店优选联盟中创建的公开|定向推广计划

• 定向计划（plan_type = 1）：会触发机构商品变更通知。
• 公开计划（plan_type = 2）

1. 供货机构在联盟带货机构后台创建的公开|定向推广计划（机构创建计划的商品必须是小店商家定向给此机构并在选品中操作添加）

• 机构定向计划（plan_type = 3）：无通知，帮卖机构后台如果不在选品中操作添加此商品，需要主动API拉取。需要通过商品列表接口拉取第一次，然后主动订阅商品信息，之后供货机构修改就有计划变更回调内容；期望官方也提供被动订阅，第一时间告诉机构，减少机构拉取平台列表接口。存在bug：https://developers.weixin.qq.com/community/develop/doc/00022651624840e01da4c7aba66000
• 机构普通计划（plan_type =4）

实践得知

1. 不需要在联盟带货机构后台选品中去添加商品，也会计算佣金。
2. 一个机构有一个商品的所有计划，计划的佣金设置都不一样时，计算优先级：定向＞公开，这里指同一身份创建的计划（如商家定向和商家公开计划对比，机构定向和机构公开计划对比）。例如机构同时有商家的plan_type = 1和plan_type = 2的商品，用户通过不同推广链接下单，最终佣金计算按照定向计划（plan_type = 1）设置来。
3. 计划不存在了，用这个不存在计划的推广链接下单是无法归因计算佣金的。

机构商品变更通知

API地址

机构商品变更通知API地址：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/API/callback/head_supplier_item_update.html

事件

事件：head_supplier_item_update

触发回调的情况

1. 小店操作

• 小店添加定向推广计划：未提及具体字段。
• 小店修改定向推广计划时间：["active_time"]
• 小店修改定向推广计划服务费：["service_ratio", "active_time"]
• 小店结束定向推广计划：["status"]
• 小店删除定向推广计划：["service_ratio", "status", "active_time"]
• 小店下架商品：【status】计划也结束

1. 机构操作

• 机构添加商品：["status"]，添加后会被动订阅商品信息。
• 机构结束推广：["status"]
• 机构删除商品：未提及具体字段。

建议

官方在回调的时候直接返回更新字段的内容，方便机构不需要再去调用接口获取更新字段内容，减少机构拉取平台接口。

机构订阅商品通知

订阅类型

1. 主动

• 机构通过接口订阅商品：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/API/hs_subscribe.html

1. 被动

• 机构通过后台选品中操作添加某个推广商品，会同时订阅该商品。

两种事件

1. 计划信息变更：head_supplier_subscribe_product_planinfo_update，计划变更（新增，修改）。
2. 商品信息变更：head_supplier_subscribe_product_baseinfo_update，商品信息变更，测试过修改价格、规格、标题、上下架。

注意点

取消订阅，如果商品没有订阅过，取消报错：https://developers.weixin.qq.com/community/develop/doc/00088c09a085d0ede5836ef9361400

其他补充

联盟带货机构获取已添加的商品数据

API：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/api/opentalent/getshop/api_getcooperativeitemlist.html

联盟带货机构获取商品推广参数

API：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/api/opentalent/getshop/api_getitempromotiondetail.html

通过上述的两个接口可以判断是

商家创建的定向计划（spu_source = 1并且plan_type = 1）、

商家创建的公开计划（spu_source = 1并且plan_type = 2）、

机构创建的定向计划（spu_source = 2并且plan_type = 1）、

机构创建的公开计划（spu_source = 2并且plan_type = 2）。

commission_type（佣金分配类型 0：商家指定达人佣金，1：机构指定达人佣金），机构指定达人佣金才适合做推客业务。参考：https://developers.weixin.qq.com/doc/store/leagueheadsupplier/api/sharer/getshop/api_getpromoteproductlist.html

联盟带货机构事件通知对接

https://developers.weixin.qq.com/doc/store/leagueheadsupplier/callback/API_change_log_callback.html

案例

1. 我们需要将联盟机构后台中选品添加的商品在我的的小程序中展示并推广，需要及时准实时同步商品计划的变化（佣金率、是否推广结束）商品信息的变化（价格、主图、下架）。

结合上述了解的官方API以及通知，我们可以初始化一次所有的合作商品（参考其他补充接口），将所有机构指定达人佣金的商品，全部同步到小程序。然后有通过机构订阅商品得知，添加商品会默认订阅，所以再接入回调事件--计划信息变更：head_supplier_subscribe_product_planinfo_update，计划变更（新增，修改）--商品信息变更：head_supplier_subscribe_product_baseinfo_update，商品信息变更，即可完成这个诉求。