# 知识库使用指南

## 一、目录索引

以下为 `微信支付官网文档/` 的完整目录树，用于辅助检索。

```text
微信支付官网文档/
├── APIv2/
│   ├── 普通商户/
│   │   ├── SDK&开发工具/                  # V2 SDK / 开发工具
│   │   ├── 扩展工具/                      # 分账、清关报关等
│   │   ├── 支付产品/                      # JSAPI、H5、Native、APP、小程序、付款码等
│   │   ├── 运营工具/                      # 委托代扣、小程序红包、付款到银行卡等
│   │   └── 通用规则/                      # 协议、签名、字段与安全
│   └── 合作伙伴/
│       ├── SDK&开发工具/                  # V2 SDK / 工具
│       ├── 扩展工具/                      # 分账等
│       ├── 支付产品/                      # JSAPI、H5、Native、APP、小程序、付款码等（特约商户）
│       ├── 运营工具/                      # 委托代扣、现金红包等
│       └── 通用规则/                      # 合作伙伴 V2 通用规则
├── APIv3/
│   ├── 普通商户/
│   │   ├── Skills&开发工具/               # 开发工具、调试与辅助
│   │   ├── 交易支持产品/                  # 消费者投诉 2.0、清关报关等
│   │   ├── 信用产品/                      # 微信支付分、支付分停车服务
│   │   ├── 安全工具/                      # 证书、加密、平台公钥
│   │   ├── 支付产品/                      # JSAPI、H5、Native、APP、小程序、合单、付款码、医保、分账、下载账单、订单退款等
│   │   ├── 营销产品/                      # 代金券、支付有礼、支付即服务、智慧商圈、H5/小程序发券等
│   │   ├── 资金产品/                      # 商家转账
│   │   └── 通用规则/                      # 签名、证书、回调、开发参数等
│   └── 合作伙伴/
│       ├── Skills&开发工具/               # 合作伙伴开发工具与 Skills
│       ├── 交易支持产品/                  # 消费者投诉 2.0、微信电子发票、清关报关等
│       ├── 信用产品/                      # 微信支付分、支付分停车服务
│       ├── 品牌经营/                      # 商家名片、摇优惠、名片会员等（服务商代品牌方操作）
│       ├── 子商户管理/                    # 特约商户进件、开户意愿确认、不活跃商户核实等
│       ├── 安全工具/                      # 合作伙伴安全与证书
│       ├── 平台收付通-电商交易解决方案/   # 平台收付通 / 电商收付通
│       ├── 支付产品/                      # JSAPI、H5、Native、APP、小程序、合单、付款码、医保（合作伙伴/间连）、分账、下载账单、订单退款等
│       ├── 营销产品/                      # 代金券、支付有礼、支付即服务、智慧商圈、点金计划、H5/小程序发券等
│       └── 通用规则/                      # 合作伙伴 V3 通用规则
└── brand/                                 # 品牌经营平台（品牌方直连），独立接入体系
    └── 品牌商户/
        ├── 快速开始/                      # 品牌入驻与开发参数说明
        ├── Skills&开发工具/               # 签名验签、开发参数申请与配置、接口规则
        ├── 商家名片/                      # 支付凭证跳转的品牌主页，展示优惠、服务、客服
        ├── 商家名片会员/                  # 品牌会员经营（入会、积分、等级、会员券）
        ├── 摇一摇有优惠/                  # 基于消费偏好的多场景优惠投放与发券
        ├── 商品券（单券）/                # 品牌优惠券，单次使用
        ├── 商品券（多次优惠）/            # 品牌优惠券，一张券可多次核销（集次卡）
        ├── 品牌门店/                      # 品牌线下门店数据管理
        └── 品牌经营（隐藏文档）/          # 人群包、联合投放等（邀请制）
```

> 品牌方直连走 `brand/品牌商户/`，服务商代品牌方操作走 `APIv3/合作伙伴/品牌经营/`。

## 二、业务目录结构

每个业务目录下统一组织如下（以实际为准，不是所有业务都完整包含）：


| 目录 / 文档    | 内容说明                                              |
| ---------- | ------------------------------------------------- |
| **产品介绍**   | 产品功能、适用场景、商户准入、接入前的资质与权限申请等说明                     |
| **开发接入准备** | 系统配置、密钥、证书等准备工作                                   |
| **开发指引**   | 接口调用流程、时序、注意事项、最佳实践                               |
| **API 列表** | 该产品所有接口的请求/响应参数、字段定义，以及各语言（curl / Java / Go）的请求示例 |
| **常见问题**   | 高频问题与排查思路                                         |
| **错误码**    | 接口返回的错误码列表与含义、排查建议                                |
| **附录**     | 权限申请指引、账号绑定、授权目录配置等补充说明                           |


品牌经营的公共开发规则（签名验签、开发参数申请与配置、接口规则）统一在 `brand/品牌商户/Skills&开发工具/开发须知/`；接入前的品牌入驻与开发参数说明在 `brand/品牌商户/快速开始/`。

## 三、文档定位流程速查

### 角色与文档路径对照


| 角色         | API 版本 | 文档路径                         | 说明                                 |
| ---------- | ------ | ---------------------------- | ---------------------------------- |
| 普通商户       | APIv3  | `APIv3/普通商户/`                | 自行申请商户号、自行调用接口                     |
| 普通商户       | APIv2  | `APIv2/普通商户/`                | 仅存量接口或产品无 V3 版本时使用                 |
| 特约商户（自行调用） | APIv3  | `APIv3/普通商户/`                | 非电商/小微/间连子商户可用 `sub_mchid` 调普通商户接口 |
| 服务商（代特约商户） | APIv3  | `APIv3/合作伙伴/`                | 服务商代特约商户发起支付、进件、分账等                |
| 服务商（代特约商户） | APIv2  | `APIv2/合作伙伴/`                | 仅存量接口                              |
| 服务商（代品牌方）  | APIv3  | `APIv3/合作伙伴/品牌经营/`           | 服务商受品牌方委托代调品牌经营接口，鉴权走服务商证书         |
| 平台服务商（收付通） | APIv3  | `APIv3/合作伙伴/平台收付通-电商交易解决方案/` | 电商/O2O 平台类业务                       |
| 品牌商户（直连）   | brand  | `brand/品牌商户/`                | 品牌方独立接入品牌经营平台，鉴权走品牌证书              |


### 定位步骤

1. 确认 **角色** 与 **API 版本** → 按上表缩小到对应目录。若用户未明确角色/版本，先对关键词做全局搜索；如果搜索结果命中多个路径（如同时出现在 `APIv3/普通商户/` 和 `APIv3/合作伙伴/`），则反问用户确认自己的角色或接入模式，再进入对应路径。
2. 根据用户描述（场景、产品名、接口名等）定位到具体业务目录（如 `支付产品/JSAPI支付/`、`商品券（单券）/`）；业务模糊时用关键词在对应目录下搜索探路，按命中路径分布判断。
3. 在业务目录下按问题类型选择对应文档（产品介绍 / 开发指引 / 常见问题 / 错误码 / API 列表 等）→ 读取精读。
4. 若需接口请求示例，按 `<接口名>-请求示例-{curl,java,go}-<doc_id>.md` 在该业务的 `API列表/` 下查找。

## 四、单篇文档结构

文件名格式为 `标题-文档ID.md`（如 `产品介绍-4012062524.md`），目录路径为中文。文件名和路径已包含足够的语义信息，可直接用于判断相关性，无需批量读 `front matter` 做筛选。

每篇 `.md` 文首带有 YAML **front matter**：

```yaml
---
url: "https://pay.weixin.qq.com/doc/v3/merchant/4012062524.md"
title: "产品介绍"
doc_id: 4012062524
---
```

品牌文档的 `url` 形如 `https://pay.weixin.qq.com/doc/brand/4015989179.md`。

## 五、用户描述模糊时的澄清话术

当用户使用的词在知识库中对应多个不同产品时，**必须先输出对应澄清话术并停止**，不得先行检索或作答。用户已明确说出具体产品名称的（如「电子回单」「接口安全IP」「代金券」等），直接按对应产品检索，无需反问。

### 澄清话术

```text
1. 券类型不明确
   触发词：券、优惠券、发券、领券
   ---
   微信支付有以下几种券产品，它们是完全独立的体系：
   1. 商品券（品牌经营平台体系，支持单品优惠和集次卡，新接入推荐）
   2. 代金券（APIv3 营销产品，商户创建满减/折扣/立减券，发放给消费者抵扣）
   3. 商家券（存量产品，功能与代金券类似但接口不同，不再推荐新接入）
   请问您接入的是哪种券？

2. 发券组件/发券插件不明确
   触发词：小程序发券、发券组件、发券插件
   ---
   「发券组件」和「发券插件」是两个不同产品下的能力：
   1. 小程序发券组件（品牌商品券体系，在小程序内发放商品券）
   2. 小程序发券插件（代金券体系，wx-plugin 形式嵌入商户小程序发放代金券）
   3. H5 发券（代金券体系，通过 H5 页面发放代金券）
   请问您使用的是哪种？

3. 证书类型不明确
   触发词：证书、API证书
   ---
   微信支付涉及多种证书，用途完全不同：
   1. 商户 API 证书（商户在商户平台申请，用于向微信支付发请求时签名证明身份）
   2. 平台证书（微信支付平台下发给商户，用于验证微信支付的回调/响应签名，以及加密敏感字段）
   3. 微信支付公钥（与平台证书作用相同，新版验签方式，逐步替代平台证书）
   4. 品牌 API 证书（品牌商户在品牌经营平台申请，用于品牌 API 请求签名）
   请问您问的是哪种证书？

4. 密钥类型不明确
   触发词：密钥、key、secret
   ---
   微信支付涉及多种密钥：
   1. APIv3 密钥（对称密钥，用于解密回调报文和加密敏感字段）
   2. APIv2 密钥（V2 接口的 API 安全密钥，MD5/HMAC-SHA256 签名）
   3. 品牌 API 密钥（品牌商户专用，用于解密品牌回调报文）
   请问您问的是哪种密钥？

5. IP 类型不明确
   触发词：IP、白名单、IP设置
   ---
   IP 相关的设置有几种不同的含义：
   1. 商户平台的 IP 白名单配置（商家转账/商家转账到零钱/企业付款到零钱/现金红包/企业付款到银行卡，调用前须在商户平台配置服务器IP白名单，否则报错拦截）
   2. 下单时的用户终端 IP 字段（JSAPI/小程序/APP/H5/Native支付及合单支付的下单接口中 payer_client_ip / spbill_create_ip 应该传什么值、怎么正确获取用户真实IP，传错会被风控拦截）
   请问您问的是哪个？

6. 转账产品不明确
   触发词：转账、付款、打款、提现
   ---
   转账相关有以下产品，注意它们是不同版本/不同接口：
   1. 商家转账（APIv3 新版，需用户确认收款，2025年起替代旧版，推荐）
   2. 商家转账到零钱（APIv3 旧版，批量转账无需用户确认，已停止新开通）
   3. 企业付款到零钱（APIv2 存量，付款到微信零钱，已不支持新开通，逐步下线）
   4. 付款到银行卡（APIv2 存量，已不推荐）
   请问您需要哪种？

7. 分账场景不明确
   触发词：分账
   ---
   分账有以下几种场景：
   1. 普通分账（普通商户或服务商基础分账）
   2. 收付通分账（平台收付通/电商收付通体系）
   3. 连锁品牌分账（品牌经营体系下连锁门店分账）
   请问您的分账场景是？

8. 红包类型不明确
   触发词：红包、发红包
   ---
   红包有以下类型：
   1. 现金红包（APIv2，向用户发放现金红包）
   2. 小程序红包（APIv2，在小程序内发放红包）
   请问您需要哪种？

9. 回单/账单/凭证不明确
    触发词：回单、账单、凭证、对账
    ---
    回单/账单相关有几种不同的含义：
    1. 电子回单（商家转账专属，每笔转账成功后可申请下载的电子凭证PDF）
    2. 交易账单/资金账单（所有支付产品通用，按日生成的对账文件，用于商户日终对账）
    3. 分账账单（分账产品专属，记录分账动账明细的对账文件）
    请问您需要的是哪种？
```