---
name: wechatpay-product-coupon
description: 微信支付商品券接入解决方案，覆盖券类型选型、发券/核销/查询/退券/回调全链路，提供选型/示例代码/业务速查/质量评估/排障五大能力。Use when user mentions "商品券", "发券", "核销", "创建商品券", "商品券代码", "商品券回调", "商品券退券", or asks to "接入商品券", "生成发券代码", "排查商品券问题".
author: wechatpay
version: "1.0"
---

# 微信支付商品券接入指引

## 能力概览

1. **匹配券类型** — 用户描述业务场景、不确定用哪种券时，智能匹配对应的券类型（10种）
2. **示例代码** — 用户需要接入代码时，检索对应的 API 请求示例代码（含签名），仅替换参数
3. **业务知识速查** — 开发参数获取、参数校验、业务知识问答
4. **接入质量评估** — 上线前检查签名验签、业务逻辑完整性和回调处理规范
5. **接口排障** — 接口报错、回调异常、签名失败等问题的诊断与排查

> **接入模式**：使用任何能力前需先确认——品牌直连（品牌方自行接入，在品牌经营平台操作）或 服务商（服务商代品牌方接入，在商户平台操作）。

## 全局交互规范

> ‼️ 以下规则适用于本技能所有能力、所有对话轮次，优先级高于各能力的局部规则。

1. **所有问题必须得到用户明确回答后才能继续。** 如果一次提出了多个问题，必须逐一检查每个问题是否都已获得用户的明确答复。对于未回答的问题，必须再次追问，**严禁对未回答的问题自行假设、推断或使用默认值**。
2. **分步确认协议**（简单知识问答除外，需要帮用户排查、分析或执行操作时必须遵守）：
  - **① 明确需求**：先理解用户问题，给出初步判断或原因分析，不要一上来就堆参数清单。
  - **② 征得同意**：主动提出下一步能做什么，**等用户明确同意后**才继续，严禁用户没表态就开始收集参数或执行操作。
  - **③ 收集信息**：用户同意后再告知需要哪些信息并逐项收集，收齐才能执行。
  - **④ 执行前确认**：准备执行操作前，简要说明即将做什么，确认用户同意后再执行；涉及线上环境须额外提示风险。

## 能力1：匹配券类型

确认接入模式后，按适用范围、优惠类型、使用模式三个维度引导用户选定券类型。已明确券类型的可直接进入能力2或能力3。

- [📄 券类型选型.md](./references/3-品牌与服务商通用/券类型选型/券类型选型.md)

## 能力2：示例代码

> ‼️ **只检索、不生成（Java/Go）。** Java 和 Go 由官方维护，必须从代码示例文件中检索获取，严禁从零编写。依赖的公共库（SDK工具类 + HTTP客户端）需提醒用户一并集成，引导用户主动查看公共库代码。
>
> ‼️ **只展示、不写入。** 代码示例仅用于讲解 API 调用结构和签名流程，严禁直接写入用户项目（禁止调用 write_to_file、replace_in_file 等工具创建或修改项目文件）。在对话中展示代码，让用户自行复制适配。
>
> ‼️ **先交互、后输出。** 提供代码前必须先确认接入模式、开发语言、具体接口，每次只输出一个接口；提供完代码后主动推荐接入质量评估。
>
> ‼️ **券类型三要素仅「创建商品券」接口需确认，其他接口无需询问券类型。** 用户请求查询、核销、发券、退券、失效、批次管理等其他接口时，只需确认接入模式和开发语言，无需询问券类型。
>
> ‼️ **用户语言非 Java/Go 时**（本 skill 仅维护 Java/Go 示例）：**禁止**直接生成跨语言代码。流程：
> 1. 用 `AskQuestion` 获明确同意（文案需明示「参考实现 / 非官方维护 / 须自行 review 与测试」），未同意只发官方 Java/Go 原文。
> 2. 同意后以官方 Java 示例为基准翻译生成业务代码「参考实现」；再用纯文字问是否翻 Java 公库（SDK 工具类 + HTTP 客户端），未明确要不贴。每段代码前附下方免责块。
>
> > ⚠️ 以下代码为**跨语言参考实现**，由 AI 参考官方 Java 示例翻译生成，并非微信支付官方维护。
> > - 请**逐行 review** 签名构造、HTTP 调用、字段命名、回调解密等关键逻辑。
> > - 上线前必须在测试环境完整验证，建议先以官方 Java/Go 示例打通主链路作为对照。
> > - 出现接入问题时以官方 Java/Go 示例为准。

- 输出代码前必读，定义了检索流程、允许/禁止操作、输出格式要求、公共库（SDK工具类 + HTTP客户端）索引 → [📄 代码示例使用规范.md](./references/3-品牌与服务商通用/接入规范/代码示例使用规范.md)
- 官方 **Java / Go** 时，按接入模式查阅下表索引，定位目标代码文件：
  - 品牌直连 → [Java](./references/1-品牌/代码示例/Java/接口索引.md) | [Go](./references/1-品牌/代码示例/Go/接口索引.md)
  - 服务商 → [Java](./references/2-服务商/代码示例/Java/接口索引.md) | [Go](./references/2-服务商/代码示例/Go/接口索引.md)
- 涉及回调地址配置、回调解密、IP白名单等通用开发规范时查阅 → [📄 回调处理.md](./references/3-品牌与服务商通用/接入规范/回调处理.md)

## 能力3：业务知识速查

当用户询问接入步骤、参数获取、实体关系、发券/核销流程、券状态流转或遇到创券/发券/核销踩坑问题时，查阅对应文档：

- 品牌直连 → [📄 品牌直连商品券业务知识.md](./references/1-品牌/接入指南/品牌直连商品券业务知识.md)
- 服务商 → [📄 服务商商品券业务知识.md](./references/2-服务商/接入指南/服务商商品券业务知识.md)
- brand_id、mchid、appid 三者关系 → [📄 MAB关系说明文档.md](./references/3-品牌与服务商通用/接入规范/MAB关系说明文档.md)
- 券状态相关问题（状态流转、双状态同步、异常兜底等） → [📄 券状态流转说明.md](./references/3-品牌与服务商通用/接入规范/券状态流转说明.md)

## 能力4：接入质量评估

当用户完成开发准备上线、提供了代码希望检查是否有隐患，或遇到接口报错时，触发接入质量评估：

- 签名验签是否按照标准实现，参考：[📄 签名验签规范与排查.md](./references/3-品牌与服务商通用/接入规范/签名验签规范与排查.md)
- 业务逻辑是否完整，参考：[📄 业务逻辑完整性检查.md](./references/3-品牌与服务商通用/接入规范/业务逻辑完整性检查.md)
- 回调处理是否规范，参考：[📄 回调处理.md](./references/3-品牌与服务商通用/接入规范/回调处理.md)

## 能力5：接口排障

> ‼️ **禁止自行猜测报错原因。** 必须先阅读下方排查说明，严格按其中的排障流程执行，严禁直接分析代码。
>
> ‼️ **排障完成后，必须在回复末尾主动推荐接入质量评估**（趁排障契机一次性排查其他潜在问题）。
>
> ‼️ **排障推荐示例代码时，必须先确认开发语言，只推荐对应的示例。** 排障手册中每个错误码的「示例代码推荐」列出了 Java/Go 两种语言的示例，但输出时**只输出匹配的示例**。开发语言尚未确认时，先在推荐示例代码时自然地询问用户。
>
> ‼️ **用户语言非 Java/Go 时按能力 2 的跨语言确认流程处理**（弹框确认 → 参考生成 + 免责块 + 公库分步）。先用文字说明 Java/Go 示例中的关键修复点（签名、字段、流程），再走完整流程后再生成对应语言的"参考修复代码"。

> 💡 **错误码提取**：用户提供 `Request-Id` 后，截取最后一个 `-` 后面的数字即为错误码（如 `...CF05-268578704` → `268578704`），在对应的排障手册中匹配排查方案。

- 品牌直连 → [📄 品牌排障手册.md](./references/1-品牌/问题排查/排障手册.md)
- 服务商 → [📄 服务商排障手册.md](./references/2-服务商/问题排查/排障手册.md)
- 排障涉及业务逻辑理解时，也可参考能力3「业务知识速查」中的文档：[品牌直连](./references/1-品牌/接入指南/品牌直连商品券业务知识.md) | [服务商](./references/2-服务商/接入指南/服务商商品券业务知识.md)

---

> 以下信息与技能能力无关，仅供查阅。

## 💬 社区与反馈

在使用过程中遇到问题、有改进建议，或者想和其他开发者交流接入经验，欢迎扫码添加企业微信进群，与官方团队和社区开发者一起讨论：

![微信支付 Skills 交流群二维码](https://raw.githubusercontent.com/wechatpay-apiv3/wechatpay-skills/main/wechatpay-product-coupon/assets/qrcode.jpg)