# 小程序连接小店

> 本文档面向自研商家和 ISV 服务商，覆盖小程序连接小店的完整接入流程，包括关联账号、小程序组件、定制商品、礼物营销和事件通知。

## 开发前准备

- **功能了解**：开发前建议先阅读以下运营文档了解完整业务流程
  - [微信小店「小程序连接小店」功能指引](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7296/99bdb51e4787f776/growth_center_manual_for_store/2)
  - [微信小店「关联账号」使用指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/6234/a159c18fbc526c24)：介绍视频号、公众号、企业微信、小程序等各渠道的关联能力与操作方法
- **权限与凭证**：商家自研可直接调用，使用小店 access_token；第三方服务商需获得商家对`权限集 ID：131`的授权，使用 authorizer_access_token
- **消息推送配置**：需配置消息推送回调 URL，本模块涉及的事件：[事件] [订单通知 / cooperation_shop_order](/doc/store/shop/linkstore/miniprogram_connection/miniprogram_callback/Order_notification)。详见 [消息通知（回调）说明](/doc/store/shop/dev_before/message_push)

## 接入流程

小程序连接小店的能力依赖关联关系。完整接入分为以下环节：先建立小程序与小店的关联关系，再按需接入小程序组件、小程序 API、定制商品、礼物营销和事件通知。

### 关联关系建立

小程序与微信小店之间需要先建立关联关系才能使用连接能力。关联关系由小店侧发起邀请，小程序侧接受后生效（status=1）；解绑后 status=2。

```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[邀请接受中<br/>status=4]
    B --> C{被邀请方处理}
    C -->|接受| D[已绑定<br/>status=1]
    C -->|拒绝| E[邀请已拒绝<br/>status=3]
    C -->|超时| F[邀请接受超时<br/>status=5]
    C -->|失败| G[邀请接受失败<br/>status=6]
    C -->|店铺取消| H[邀请店铺取消<br/>status=7]
    D -->|解绑| I[已解绑<br/>status=2]
    style A fill:#ffffff,stroke:#0ab8a6,color:#666666
    style C fill:#ffffff,stroke:#0ab8a6,color:#666666
    style E fill:#ffffff,stroke:#0ab8a6,color:#666666
    style F fill:#ffffff,stroke:#0ab8a6,color:#666666
    style G fill:#ffffff,stroke:#0ab8a6,color:#666666
    style H fill:#ffffff,stroke:#0ab8a6,color:#666666
```

### 小程序组件接入

关联关系建立后，小程序可以直接使用以下原生组件展示小店内容：

| 组件名称 | 组件标签 | 最低基础库 | 用途说明 |
|---------|---------|-----------|---------|
| [商品卡组件](/miniprogram/dev/component/store-product.md) | `<store-product>` | 3.7.0 | 在小程序中展示微信小店商品卡片，需与小店建立关联关系 |
| [店铺卡组件](/miniprogram/dev/component/store-home.md) | `<store-home>` | 3.5.5 | 在小程序中展示微信小店店铺卡片，无关联关系限制 |
| [礼物组件](/miniprogram/dev/component/store-gift.md) | `<store-gift>` | 3.8.10 | 在小程序中展示微信小店礼物功能，需与小店建立关联关系，且商家需对该小程序创建礼物活动 |
| [优惠券组件](/miniprogram/dev/component/store-coupon.md) | `<store-coupon>` | 3.8.3 | 在小程序中展示微信小店优惠券，无关联关系限制 |

### 小程序 API 接入

| API 名称 | 用途说明 |
|---------|---------|
| [wx.openStoreOrderDetail](/miniprogram/dev/api/open-api/store/wx.openStoreOrderDetail.md) | 打开微信小店订单详情页 |
| [wx.openStoreCouponDetail](/miniprogram/dev/api/open-api/store/wx.openStoreCouponDetail.md) | 打开微信小店优惠券详情页 |

### 定制商品接入

适用于个性化印刷、定制刻字、3D 打印等定制商品场景。用户在小程序内完成定制操作后先上传文件获取 `media_id`，将 `media_id` 作为参数传入 `<store-product>` 商品卡；用户点击商品卡跳转到小店下单页完成下单；商家收到订单后通过小店服务端获取文件下载链接，完成定制发货。

```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] 上传资料<br/>uploadec"]
    B --> C["获取 media_id<br/>传入 &lt;store-product&gt; 参数"]
    C --> D[用户点击商品卡<br/>跳转小店下单]
    D --> E["[API] 获取文件下载链接<br/>getdownloadurl"]
    E --> F[下载文件定制发货]
    style A fill:#ffffff,stroke:#0ab8a6,color:#666666
    style C fill:#ffffff,stroke:#0ab8a6,color:#666666
    style D fill:#ffffff,stroke:#0ab8a6,color:#666666
    style F fill:#ffffff,stroke:#0ab8a6,color:#666666
```

| 步骤 | 接口 | 调用方 | 说明 |
|------|------|--------|------|
| 用户定制后上传文件 | [API] [上传资料 / uploadec](/doc/store/shop/API/miniandstore/basic/api_uploadec) | 小程序服务端 | 传入用户 `openid`，返回 `media_id`；支持图片、CAD、3DMax、文档、压缩包等格式，最大 50M |
| 商家获取文件并发货 | [API] [获取文件下载链接 / getdownloadurl](/doc/store/shop/API/miniandstore/basic/api_getdownloadurl) | 小店服务端 | 传入 `openid` 和 `order_id`，返回临时下载链接（有效期 10 分钟，每订单限 10 次/天）|

两个接口均须在服务端调用，不可在小程序前端直接调用。上传资料权限集 ID：`180`，获取文件下载链接权限集 ID：`131`。

### 礼物营销接入

开发前建议先阅读 [微信小店「礼物抽奖」使用指南](https://store.weixin.qq.com/chengzhang/webdoc/wiki/7536/38ed4b87e7fee213/service_account_doc) 了解礼物活动的创建与管理。

礼物营销分为**采购模式**（开发者自采自发）和**商家配置模式**（商家提供礼物、开发者发放），两种模式仅在获取活动 ID 的方式上不同，之后的 API 调用和前端收礼流程完全一致。小游戏送礼物可参考 [小游戏开放能力 - 微信礼物](/minigame/dev/guide/open-ability/WeChatGift.md)。

#### 角色说明

| 角色 | 说明 |
|------|------|
| 小店商家 | 在小店后台创建礼物活动，授权指定发礼方参与发礼 |
| 发礼方 | 通过服务端接口发放礼物，支持**小程序、小游戏、微信小店、移动应用**四种账号类型，使用对应账号的 access_token 调用接口 |
| 用户 | 通过小程序内的 [`<store-gift>`](/miniprogram/dev/component/store-gift.md) 组件查看和领取礼物 |

#### 步骤1：创建礼物活动

> 采购模式和商家配置模式的活动创建方式不同

**采购模式**

1. 在 [小程序后台](https://mp.weixin.qq.com/) - 支付与交易 - 微信小店 - 礼物活动
2. 在「已购买的礼物」分类下点击「去购买」
3. 通过微信扫码后跳转至选礼物页面
4. 选择礼物份数并完成付款（单次购买生成一个活动，单活动最多 500 件，可分多次购买）
5. 购买后可在「微信 - 我 - 小店与卡包」查看付款订单
6. 返回 [小程序后台](https://mp.weixin.qq.com/) - 支付与交易 - 微信小店 - 礼物活动 - 「已购买的礼物」页面，查看已支付的礼物活动，获得活动 ID

购买后 48 小时自动失效，请尽快发出礼物。

**商家配置模式**

1. 商家进入 [微信小店后台](https://store.weixin.qq.com/shop/home) - 推荐运营 - 礼物运营
2. 点击「创建活动」，选择推广渠道「小程序」
3. 在发放账号中选择需要发放的小程序
4. 选择要发放的礼物商品和份数（仅支持小店在售商品）

活动上线后内容不可修改，请谨慎操作。

#### 步骤2：调用 API 发放礼物

拿到活动 ID 后，通过服务端 API 完成礼物分配：

```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/>list_present_activity"] --> B["[API] 查询礼物活动详情<br/>get_activity"]
    B --> C{模式?}
    C -->|采购| D["[API] 查询礼物订单详情<br/>get_present_order"]
    C -->|商家配置| E["[API] 创建并发送礼物<br/>create_present_order"]
    D --> F["[API] 指定礼物收礼者<br/>set_present_receiver"]
    style C fill:#ffffff,stroke:#0ab8a6,color:#666666
```

之后按模式调用：

**采购模式**

1. 调用 [API] [查询小店礼物活动列表 / list_present_activity](/doc/store/shop/API/miniandstore/cooperation_gift/api_list_present_activity) 获取已购买的礼物活动列表，拿到活动 ID `activity_id`
2. 调用 [API] [查询礼物活动详情 / get_activity](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_activity) 确认活动信息，得到 `present_order_id`（礼物单 ID）
3. 调用 [API] [查询礼物订单详情 / get_present_order](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_present) 查询子单列表，拿到子单 `order_id`
4. 调用 [API] [指定礼物收礼者 / set_present_receiver](/doc/store/shop/API/miniandstore/cooperation_gift/api_set_present_receiver) 传入子单 `order_id` 和用户 `openid` 完成分配。一个用户只能指定一个 `order_id`，指定多个会报错，开发者需自行实现「挑选一个空的订单分配」逻辑，指定后不可更改。同一活动库存中同一用户只能发一件，如需给同一用户发多件需在购买时拆单。

**商家配置模式**

1. 调用 [API] [查询小店礼物活动列表 / list_present_activity](/doc/store/shop/API/miniandstore/cooperation_gift/api_list_present_activity) 获取已授权的活动列表，拿到活动 ID `activity_id`
2. 调用 [API] [查询礼物活动详情 / get_activity](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_activity) 确认活动信息
3. 调用 [API] [创建并发送礼物 / create_present_order](/doc/store/shop/API/miniandstore/cooperation_gift/api_create_present_order) 传入活动 `activity_id` 和用户 `openid` 创建礼物单，返回 `present_id`

#### 步骤3：前端拉起礼物组件

在小程序页面中引入 [`<store-gift>`](/miniprogram/dev/component/store-gift.md) 组件（基础库 ≥ 3.8.10），传入步骤2返回的礼物订单 ID 和用户 `openid`：

```html
<store-gift present-order-id="xxx" open-id="xxx" />
```

用户被指定为收礼者后，可通过以下方式领取礼物：

1. 在小程序内点击礼物卡片，显示「已抽中，待收下」，点击「收下礼物」填写收货地址
2. 或在微信「服务通知」中查看通知，点击「收下礼物」填写收货地址

24 小时内未收下，礼物将自动失效。

#### 步骤4：查询发货状态

通过 [API] [查询礼物订单详情 / get_present_order](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_present) 查询礼物的领取状态和发货状态。

#### 库存与发放规则

| 规则项 | 采购模式 | 商家配置模式 |
|--------|---------|-------------|
| 库存来源 | 开发者购买（个人支付）| 商家提供 |
| 库存锁定 | 购买时锁定 | 创建订单后锁定 |
| 自动失效 | 购买后 48 小时 | 下单 24 小时后用户未收下，订单过期，库存释放 |
| 活动有效期 | 购买时间 + 30 天 | 最长 30 天 |
| 用户领取限制 | 同一活动中同一用户只能发一件 | 不限制 |
| 指定收礼者 | 指定后不可更改 | 创建订单时指定 |
| 活动修改 | - | 上线后内容不可修改 |
| 过期提醒 | 临近过期，小店侧发送服务通知 | 临近过期，小店侧发送服务通知 |
| 支付订单号 | 有（个人支付订单）| 无（不涉及资金交易）|

### 事件通知接入

配置消息推送后，当用户通过小程序进入小店下单成功，小店侧会向渠道小程序推送订单通知回调。

[事件] [订单通知 / cooperation_shop_order](/doc/store/shop/linkstore/miniprogram_connection/miniprogram_callback/Order_notification) 推送至**小程序侧**配置的消息回调地址，存在两个 Event 值：

| 场景 | Event 值 |
|------|---------|
| 旧版关联账号 | `cooperation_shop_order` |
| 新版关联账号 | `related_shop_order_submission` |

回调消息示例（解密后的明文 JSON）：

```json
{
    "ToUserName": "gh_2defbb026678",
    "FromUserName": "OPENID",
    "CreateTime": 1706518830,
    "MsgType": "event",
    "Event": "cooperation_shop_order",
    "Data": {
        "order_id": "coiqBw3B****TdtdzIpQ",
        "shop_appid": "店铺appid"
    }
}
```

> `order_id` 并非小店侧的订单 ID，仅供渠道小程序查询使用。

重试策略：0s / 0s / 10s / 1min / 5min / 30min / 60min / 60min / 60min，最多推送 10 次。

## 接口全览

### 第三方应用服务端接口

> 以下接口支持小程序、小游戏、微信小店、移动应用四种账号类型调用。

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [上传资料](/doc/store/shop/API/miniandstore/basic/api_uploadec) / uploadec | `POST /channels/ec/open/upload` | 上传定制商品文件，返回 `media_id` 供下单时传参（仅小程序场景使用）|
| [查询小店礼物活动列表](/doc/store/shop/API/miniandstore/cooperation_gift/api_list_present_activity) / list_present_activity | `POST /channels/ec/b2c/activity/list/promoter/get` | 查询小店授权给当前应用的送礼活动列表 |
| [查询礼物活动详情](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_activity) / get_activity | `POST /channels/ec/b2c/activity/info/promoter/get` | 查询指定送礼活动的商品、库存、有效期等详情 |
| [指定礼物收礼者](/doc/store/shop/API/miniandstore/cooperation_gift/api_set_present_receiver) / set_present_receiver | `POST /channels/ec/order/presentorder/receiver/set` | 传入 `present_id` 和收礼用户 `openid`，绑定收礼关系 |
| [创建并发送礼物](/doc/store/shop/API/miniandstore/cooperation_gift/api_create_present_order) / create_present_order | `POST /channels/ec/order/presentorder/create` | 创建礼物单，返回 `present_id`；外部应用身份调用时额外返回 `business_type`（外部 App 跳转业务类型）和 `query`（外部 App 跳转参数）|
| [查询礼物订单列表](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_present_list) / list_present_order | `POST /channels/ec/order/presentlist/get` | 查询当前应用已发放的礼物单列表 |
| [查询收礼者订单列表](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_receiver_order_list) / get_receiver_order_list | `POST /channels/ec/order/receiverorderlist/get` | 查询发放给某位收礼者的订单列表 |
| [查询礼物订单详情](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_present) / get_present_order | `POST /channels/ec/order/present/get` | 查询指定礼物单的状态详情 |

存在旧版接口 [查询礼物订单列表（旧）](/doc/store/shop/API/miniandstore/cooperation_gift/api_list_present_order) 和 [查询礼物订单详情（旧）](/doc/store/shop/API/miniandstore/cooperation_gift/api_get_present_order)，推荐使用上方新版接口。

### 小店服务端接口

| 中文名 / 英文名 | 请求方式 | 功能说明 |
|----------------|---------|---------|
| [获取文件下载链接](/doc/store/shop/API/miniandstore/basic/api_getdownloadurl) / getdownloadurl | `POST /channels/ec/open/get_download_url` | 传入 `openid` 和 `order_id`，获取定制商品文件的临时下载链接 |

### 事件通知（推送至小程序侧）

| 中文名 / 英文名 | 事件标识 | 功能说明 |
|----------------|---------|---------|
| [订单通知](/doc/store/shop/linkstore/miniprogram_connection/miniprogram_callback/Order_notification) / cooperation_shop_order | `cooperation_shop_order` / `related_shop_order_submission` | 用户通过小程序下单成功后，小店推送订单回调至渠道小程序配置的消息回调地址 |

### 小程序组件

| 组件名称 | 组件标签 | 最低基础库 |
|---------|---------|-----------|
| [商品卡组件](/miniprogram/dev/component/store-product.md) | `<store-product>` | 3.7.0 |
| [店铺卡组件](/miniprogram/dev/component/store-home.md) | `<store-home>` | 3.5.5 |
| [礼物组件](/miniprogram/dev/component/store-gift.md) | `<store-gift>` | 3.8.10 |
| [优惠券组件](/miniprogram/dev/component/store-coupon.md) | `<store-coupon>` | 3.8.3 |

### 小程序 API

| API 名称 | 功能说明 |
|---------|---------|
| [wx.openStoreOrderDetail](/miniprogram/dev/api/open-api/store/wx.openStoreOrderDetail.md) | 打开微信小店订单详情页 |
| [wx.openStoreCouponDetail](/miniprogram/dev/api/open-api/store/wx.openStoreCouponDetail.md) | 打开微信小店优惠券详情页 |

## 常见问题 FAQ

**Q：订单通知的 Event 有两个值，如何区分？**
A：`cooperation_shop_order` 用于旧版关联账号，`related_shop_order_submission` 用于新版关联账号。两者消息结构相同，开发者需根据实际的关联关系类型处理对应的 Event 值。

**Q：礼物 API 使用哪个 access_token 调用？**
A：所有礼物接口均由**第三方应用服务端**调用，使用对应应用的 access_token，支持小程序、小游戏、微信小店、移动应用四种账号类型；上传资料（uploadec）仅小程序场景使用，由**小程序服务端**调用，使用小程序 access_token；获取文件下载链接（getdownloadurl）由**小店服务端**调用，使用小店 access_token。

**Q：采购模式和商家配置模式如何选择？**
A：采购模式适用于开发者自采自发的场景，开发者自行购买礼物后通过 API 分配给用户；商家配置模式适用于商家提供礼物、小程序负责发放的场景，商家在小店后台创建活动授权关联小程序，小程序通过 API 创建礼物订单发放。两种模式的 API 调用流程不同：采购模式通过查询活动详情获取已购买的礼物单后指定收礼者；商家配置模式通过创建礼物订单生成新的礼物单。

**Q：采购模式中一个用户可以分配多个礼物吗？**
A：不可以。一个用户只能指定一个 `order_id`，指定多个会报错。开发者需自行实现「挑选一个空的订单分配」逻辑。指定收礼者后不可更改。

**Q：礼物活动创建后可以修改吗？**
A：商家配置模式中，活动上线后内容（发放商品及件数等）不可修改。采购模式中，开发者购买的礼物在购买后 48 小时自动失效，请尽快发出。

**Q：用户被指定为收礼者后多久内需要领取？**
A：24 小时内未收下，礼物将自动失效。

![](https://res8.wxqcloud.qq.com.cn/wxdoc/56617deb-b17d-4cf1-bccd-71d2c41ccc76.svg)文档变更日志（2条）
2026 年 06 月 23 日补充 礼物营销 相关说明
2026 年 04 月 28 日新增 小程序连接小店 开发指南