# 店铺管理

## 开发前准备

- **功能了解**：开发前建议先阅读以下运营文档了解店铺主页的完整功能和配置流程：
  - [微信小店「店铺主页」商家装修指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7300/b15024b2e6394ef3/growth_center_lesson_for_store/5)
- **权限与凭证**：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对`权限集 ID：129`或`权限集 ID：131`的授权（获得其中之一即可），使用 authorizer_access_token
- **消息推送配置**：需配置消息推送回调 URL，本模块涉及的事件：[事件] [小店状态变更回调事件 / channels_ec_change_status](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_change_status)、[事件] [小店最终注销回调事件 / channels_ec_close_store](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_close_store)、[事件] [小店修改名称回调事件 / set_shop_nickname](/doc/store/shop/notify/storebasics_callback/set_shop_nickname)。详见 [消息通知（回调）说明](/doc/store/shop/dev_before/message_push)

## 接入流程

按阶段分为：获取店铺信息 → 主页商品管理 → 主页装修（背景图 + 精选展示位）。

### 阶段一：获取店铺信息

通过 4 个基础接口获取店铺的名称、头像、状态等基本信息，以及店铺的 H5 链接、二维码和口令，用于分享和推广。

```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] 获取店铺基本信息<br/>mmecapi_basicinfo"] --> B[获取店铺基础信息]
  B --> C["[API] 获取店铺H5链接<br/>getshoph5url"]
  B --> D["[API] 获取店铺二维码<br/>getshopqrcode"]
  B --> E["[API] 获取店铺口令<br/>getshoptaglink"]
  style B fill:#ffffff,stroke:#0ab8a6,color:#666666
```

> 获取店铺基本信息为 GET 请求，其余接口均为 POST 请求。

[API] [获取店铺H5链接 / getshoph5url](/doc/store/shop/API/storemanage/api_getshoph5url)、[API] [获取店铺二维码 / getshopqrcode](/doc/store/shop/API/storemanage/api_getshopqrcode)、[API] [获取店铺口令 / getshoptaglink](/doc/store/shop/API/storemanage/api_getshoptaglink) 三个接口均支持传入企业微信参数（`wecom_corp_id` + `wecom_user_id`），通过带企业微信参数的链接下单的订单，会在成交来源中展示该企业。

如果你有企业微信的 `corp_id` 和 `user_id`，需要先通过 [API] [获取关联账号企微ID / shop_get_wecom_openid](/doc/store/shop/API/wecom/api_shop_get_wecom_openid) 换取小店侧的 `wecom_corp_id` 和 `wecom_user_id`，再填入上述三个接口的对应参数。注意：查询的企业 `corp_id` 必须是店铺的关联账号，且成员 `user_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] 获取主页展示商品列表<br/>getstorewindowproductlist"] --> B{需要调整?}
  B -->|调整排序| C["[API] 重新排序主页展示商品<br/>reorderstorewindowproduct"]
  B -->|隐藏/取消隐藏| D["[API] 隐藏小店主页商品<br/>hidestorewindowproduct"]
  B -->|置顶/取消置顶| E["[API] 置顶小店主页商品<br/>settopstorewindowproduct"]
  style B fill:#ffffff,stroke:#0ab8a6,color:#666666
```

注意事项：

- [API] [获取主页展示商品列表 / getstorewindowproductlist](/doc/store/shop/API/homepage/storewindow/api_getstorewindowproductlist) 只返回**上架中**的商品，支持翻页（最大每页 30 条）
- 隐藏商品不会导致下架，仅在主页不可见，用户仍可通过直播间、短视频、搜索等其他渠道购买
- 重新排序的最大移动步长为 500（即新序号与当前序号的差距不超过 500）
- 置顶商品会排列在商品综合排序列表的顶部，最多允许置顶 50 个商品；置顶商品内部按操作时间倒序排列（后置顶的商品排在前面）

**商品分类查询**：商品分类由分类树和分类商品两部分数据组成，需分两步获取。

先通过 [API] [获取在店铺主页展示的商品分类 / getclassificationtree](/doc/store/shop/API/homepage/shoptype/api_getclassificationtree) 获取完整分类树结构，再通过 [API] [获取分类关联的商品ID列表 / getclassificationproductlist](/doc/store/shop/API/homepage/shoptype/api_getclassificationproductlist) 获取指定分类下的商品列表。

### 阶段三：主页装修

通过背景图和精选展示位两组接口装修店铺主页。两者流程完全一致：**先上传图片获取图片链接**，再提交申请等待审核，审核通过后在主页生效。

**主页背景图**：

```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] 上传图片<br/>img_upload"] --> B["[API] 提交背景图申请<br/>submitbackground"]
  B --> C{审核中}
  C -->|通过| D[生效展示]
  C -->|撤销| E["[API] 撤销背景图申请<br/>cancelbackground"]
  D --> F["[API] 查询背景图<br/>getbackground"]
  D --> G["[API] 清空背景图并撤销<br/>removebackground"]
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
```

**精选展示位**：

精选展示位支持三种类型的内容，提交前需根据类型准备对应的内容参数：

| 展示位类型 | type 值 | 需提前准备 | 获取方式 |
|-----------|---------|-----------|---------|
| 商品 | `1` | 商品 ID（`product_id`） | 调用 [API] [获取商品列表 / getproductlist](/doc/store/shop/API/channels-shop-product/shop/api_getproductlist) 接口查询，商品需处于**上架状态** |
| 视频号 | `3` | 视频号 ID（`finder_user_name`）+ 视频 ID（`feed_id`） | 登录[视频号助手](https://channels.weixin.qq.com/)，首页查看视频号 ID，「动态管理」模块获取视频 ID |
| 公众号 | `4` | 公众号文章链接（`url`） | 在微信客户端打开公众号文章，通过分享功能获取链接（`https://mp.weixin.qq.com/...`） |

```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
  P1[准备商品ID] --> U
  P2[准备视频号ID和视频ID] --> U
  P3[准备公众号文章链接] --> U
  U["[API] 上传图片<br/>img_upload"] --> B["[API] 提交展示位申请<br/>submitbannerapply"]
  B --> C{审核中}
  C -->|通过| D[生效展示]
  C -->|撤销| E["[API] 撤销展示位申请<br/>cancelbannerapply"]
  D --> F["[API] 查询精选展示位<br/>getbanner"]
  D --> G["[API] 清空展示位并撤销<br/>removebanner"]
  style P1 fill:#ffffff,stroke:#0ab8a6,color:#666666
  style P2 fill:#ffffff,stroke:#0ab8a6,color:#666666
  style P3 fill:#ffffff,stroke:#0ab8a6,color:#666666
  style C fill:#ffffff,stroke:#0ab8a6,color:#666666
  style D fill:#ffffff,stroke:#0ab8a6,color:#666666
```

图片上传说明：

- 上传接口路径：`POST /shop/ec/basics/img/upload`，支持二进制流或图片 URL 两种方式
- 必须使用 `resp_type=1` 获取图片链接（返回 `img_url`），图片链接永久有效，同一张图片无需重复上传
- 支持格式：bmp、jpg/jpeg、png、svg、webp；上传大小上限 10MB
- 「撤销申请」仅撤销审核中的新申请，不影响当前已生效的展示内容；「清空并撤销」同时移除已生效内容并撤销审核中的申请

## 店铺状态流转

店铺有 4 种状态，其中 `open_finished` 和 `closing` 之间可双向切换（对应正常营业和暂停营业），通过 [事件] [小店状态变更回调事件 / channels_ec_change_status](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_change_status) 监听；最终注销由 [事件] [小店最终注销回调事件 / channels_ec_close_store](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_close_store) 单独通知。

```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[opening<br/>开通中] --> B[open_finished<br/>正常营业]
  B <--> C[closing<br/>暂停营业]
  C --> D[close_finished<br/>已注销]
```

状态说明：

- `opening`：开店审核/开通流程进行中，尚未正式营业
- `open_finished`：店铺已正常开通，处于正常营业状态；此时 API 会额外返回 `open_timestamp`（开店时间戳）
- `closing`：店铺暂停营业中，可以恢复回 `open_finished`，也可以继续走最终注销流程
- `close_finished`：店铺已完成最终注销，不可恢复

事件触发规则：

- `opening` → `open_finished`：开店完成，**不触发** [事件] [小店状态变更回调事件 / channels_ec_change_status](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_change_status)
- `open_finished` ↔ `closing`：正常营业与暂停营业之间切换，**触发** [事件] [小店状态变更回调事件 / channels_ec_change_status](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_change_status)
- `closing` → `close_finished`：最终注销完成，**触发** [事件] [小店最终注销回调事件 / channels_ec_close_store](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_close_store)，**不触发** channels_ec_change_status

## 接口全览

### API 接口

**店铺基础**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [获取店铺基本信息](/doc/store/shop/API/storemanage/api_mmecapi_basicinfo) / mmecapi_basicinfo | `GET /channels/ec/basics/info/get` | 获取店铺名称、头像、状态等 |
| [获取店铺H5链接](/doc/store/shop/API/storemanage/api_getshoph5url) / getshoph5url | `POST /channels/ec/basics/shop/h5url/get` | 获取店铺H5链接，支持企微参数 |
| [获取店铺二维码](/doc/store/shop/API/storemanage/api_getshopqrcode) / getshopqrcode | `POST /channels/ec/basics/shop/qrcode/get` | 获取店铺二维码，支持企微参数 |
| [获取店铺口令](/doc/store/shop/API/storemanage/api_getshoptaglink) / getshoptaglink | `POST /channels/ec/basics/shop/taglink/get` | 获取店铺微信口令，支持企微参数 |
| [获取关联账号企微ID](/doc/store/shop/API/wecom/api_shop_get_wecom_openid) / shop_get_wecom_openid | `POST /channels/ec/wecom/get_wecom_id` | 通过企微 corp_id + user_id 查询在小店侧的 wecom_corp_id 和 wecom_user_id |

**商品排序**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [获取主页展示商品列表](/doc/store/shop/API/homepage/storewindow/api_getstorewindowproductlist) / getstorewindowproductlist | `POST /channels/ec/store/window/product/list/get` | 获取主页展示的上架商品列表 |
| [重新排序主页展示商品](/doc/store/shop/API/homepage/storewindow/api_reorderstorewindowproduct) / reorderstorewindowproduct | `POST /channels/ec/store/window/product/reorder` | 调整商品在主页的排序 |
| [隐藏小店主页商品](/doc/store/shop/API/homepage/storewindow/api_hidestorewindowproduct) / hidestorewindowproduct | `POST /channels/ec/store/window/product/hide` | 隐藏/取消隐藏主页商品 |
| [置顶小店主页商品](/doc/store/shop/API/homepage/storewindow/api_settopstorewindowproduct) / settopstorewindowproduct | `POST /channels/ec/store/window/product/settop` | 置顶/取消置顶主页商品 |

**主页背景图**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [提交背景图申请](/doc/store/shop/API/homepage/background/api_submitbackgroundapply) / submitbackground | `POST /channels/ec/basics/homepage/background/apply/submit` | 提交背景图，审核通过后生效 |
| [查询背景图](/doc/store/shop/API/homepage/background/api_getbackground) / getbackground | `POST /channels/ec/basics/homepage/background/get` | 查询生效的背景图和审核中的申请 |
| [清空主页背景图并撤销流程中的申请](/doc/store/shop/API/homepage/background/api_removebackground) / removebackground | `POST /channels/ec/basics/homepage/background/remove` | 清空背景图并撤销审核中的申请 |
| [撤销主页背景图申请](/doc/store/shop/API/homepage/background/api_cancelbackgroundapply) / cancelbackground | `POST /channels/ec/basics/homepage/background/apply/cancel` | 仅撤销审核中的申请 |

**精选展示位**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [提交精选展示位申请](/doc/store/shop/API/homepage/banner/api_submitbannerapply) / submitbanner | `POST /channels/ec/basics/homepage/banner/apply/submit` | 提交展示位，审核通过后生效 |
| [查询精选展示位](/doc/store/shop/API/homepage/banner/api_getbanner) / getbanner | `POST /channels/ec/basics/homepage/banner/get` | 查询生效的展示位和审核中的申请 |
| [清空精选展示位并撤销流程中的申请](/doc/store/shop/API/homepage/banner/api_removebanner) / removebanner | `POST /channels/ec/basics/homepage/banner/remove` | 清空展示位并撤销审核中的申请 |
| [撤销精选展示位申请](/doc/store/shop/API/homepage/banner/api_cancelbannerapply) / cancelbanner | `POST /channels/ec/basics/homepage/banner/apply/cancel` | 仅撤销审核中的申请 |

**商品分类**

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [获取在店铺主页展示的商品分类](/doc/store/shop/API/homepage/shoptype/api_getclassificationtree) / getclassificationtree | `POST /channels/ec/store/classification/tree/get` | 获取主页商品分类树 |
| [获取分类关联的商品ID列表](/doc/store/shop/API/homepage/shoptype/api_getclassificationproductlist) / getclassificationtreeproduct | `POST /channels/ec/store/classification/tree/product/get` | 获取某分类下的商品ID列表 |

### 事件通知

| 中文名 / 英文名 | 事件标识 | 功能说明 |
|----------------|---------|---------|
| [小店状态变更回调事件](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_change_status) / channels_ec_change_status | `Event: channels_ec_change_status` | 店铺状态变化时通知（不含开店和注销） |
| [小店最终注销回调事件](/doc/store/shop/notify/storebasics_callback/channels_ec_basic_close_store) / channels_ec_close_store | `Event: channels_ec_close_store` | 店铺从 closing 变为 close_finished 时通知 |
| [小店修改名称回调事件](/doc/store/shop/notify/storebasics_callback/set_shop_nickname) / set_shop_nickname | `Event: set_shop_nickname` | 店铺修改名称时通知 |

## 常见问题 FAQ

**Q：获取店铺基本信息为什么是 GET 请求？**
A：本模块中 [API] [获取店铺基本信息 / mmecapi_basicinfo](/doc/store/shop/API/storemanage/api_mmecapi_basicinfo) 是唯一使用 GET 请求的接口（错误使用 POST 会返回错误码 43001），其余 17 个接口均为 POST 请求。

**Q：隐藏商品和下架商品有什么区别？**
A：通过 [API] [隐藏小店主页商品 / hidestorewindowproduct](/doc/store/shop/API/homepage/storewindow/api_hidestorewindowproduct) 隐藏的商品仅在店铺主页不可见，商品仍保持上架状态，用户可通过直播间、短视频、搜索等其他渠道购买。下架商品则会完全停止售卖。

**Q：背景图/精选展示位的「清空」和「撤销」有什么区别？**
A：「撤销申请」仅撤销审核中的新申请，不影响当前已生效的展示内容；「清空并撤销」会同时移除已生效的展示内容和撤销审核中的申请。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（1条）
2026 年 04 月 23 日新增 店铺管理 开发指南