> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 集成工具（waffo-integrate）

> 通过 AI 编码工具自动完成 Waffo SDK 集成，比手动集成快 33%，成功率 100%。

waffo-integrate 是 Waffo 官方的 AI 集成 Skill，帮助开发者通过交互式向导自动完成 SDK 集成。支持 Claude Code、Cursor 等 AI 编码工具。

<Note>
  本页的「AI」指用 AI 编码工具完成 SDK 集成。如果你想接收 AI Agent 用稳定币支付，参见 [x402 稳定币收单](/docs/zh/developer-docs/use-cases/x402-stablecoin-acquiring)。
</Note>

## 接入路线图

<Steps>
  <Step title="准备项目">
    确认项目代码已在 Claude Code 或 Cursor 中打开。
  </Step>

  <Step title="安装 Skill">
    运行 `npx @waffo/waffo-integrate`。
  </Step>

  <Step title="触发 Waffo 集成">
    在 AI 助手中要求集成 Waffo 支付。
  </Step>

  <Step title="回答业务问题">
    选择需要的能力，例如支付、退款、订阅、Webhook、商户配置查询和支付方式查询。
  </Step>

  <Step title="审核并生成代码">
    AI 工具会先展示代码预览，确认后生成 SDK 初始化、服务层、Webhook 处理和测试文件。
  </Step>

  <Step title="运行验证">
    AI 工具会运行集成测试，覆盖支付、退款、订阅和 Webhook 流程。
  </Step>

  <Step title="提交测试报告">
    将生成的测试报告发送到 Waffo 技术对接群确认。
  </Step>
</Steps>

## 为什么使用 waffo-integrate

| 指标       | 使用 Skill | 手动集成  | 提升   |
| -------- | -------- | ----- | ---- |
| 集成通过率    | **100%** | 75%   | +25% |
| 平均耗时     | 128s     | 192s  | -33% |
| Token 消耗 | 58.8k    | 66.3k | -11% |

## 安装

<CodeGroup>
  ```bash 自动检测（推荐） theme={null}
  npx @waffo/waffo-integrate
  ```

  ```bash Claude Code theme={null}
  npx @waffo/waffo-integrate --claude
  # 或
  claude /install-skill waffo-com/waffo-integrate
  ```

  ```bash Cursor theme={null}
  npx @waffo/waffo-integrate --cursor
  ```
</CodeGroup>

## 集成流程

<Steps>
  <Step title="触发 Skill">
    在 AI 助手中输入触发词：`集成 Waffo 支付`、`integrate waffo`、`接入waffo`、`waffo sdk` 或 `waffo payment`。
  </Step>

  <Step title="语言检测">
    Skill 自动检测项目语言：`package.json` → Node.js，`pom.xml` / `build.gradle` → Java，`go.mod` → Go。
  </Step>

  <Step title="功能选择">
    交互式选择需要的功能（逐个询问）：支付、退款、订阅、Webhook、商户配置查询、支付方式查询。智能推荐：选了支付会建议接退款，选了订阅会建议接 Webhook。
  </Step>

  <Step title="框架选择（仅 Webhook）">
    | 语言      | 推荐框架        | 其他选项             |
    | ------- | ----------- | ---------------- |
    | Node.js | Express     | NestJS, Fastify  |
    | Java    | Spring Boot | —                |
    | Go      | Gin         | Echo, Fiber, Chi |
  </Step>

  <Step title="代码预览 & 生成">
    Skill 先展示完整代码供审核，确认后自动生成：SDK 初始化、支付/退款/订阅服务、Webhook 处理、测试文件、`.env.example`。
  </Step>

  <Step title="集成验证（可选）">
    运行 15 项验收测试，覆盖支付、退款、订阅全流程。通过 HTTP 端点测试 + Playwright 自动化收银台操作 + 数据库状态检查。
  </Step>
</Steps>

验证完成后，请将生成的测试报告发送到贵司和 Waffo 的技术对接群（企微或 Lark 群），用于确认集成结果。

## 内置 13 条 API 规则

Skill 内置的规则自动防止常见错误：

| #  | 规则                                                | 防止的问题                            |
| -- | ------------------------------------------------- | -------------------------------- |
| 1  | Request ID 最长 32 字符                               | 超过 Waffo 幂等键长度限制                 |
| 2  | 订阅用 `currency` 不是 `orderCurrency`                 | 字段名混淆                            |
| 3  | 订阅用 `amount` 不是 `orderAmount`                     | 字段名混淆                            |
| 4  | 各操作的必填字段检查                                        | 缺少 `payMethodType`、`goodsInfo` 等 |
| 5  | `periodType` 仅 DAILY/WEEKLY/MONTHLY               | 无效枚举 `YEARLY`、`MONTH`            |
| 6  | `periodInterval` 是 String 不是 Number               | 类型错误                             |
| 7  | 订阅必传 `payMethodType`                              | SDK 报错 A0003                     |
| 8  | `productName` 仅 ONE\_TIME\_PAYMENT / SUBSCRIPTION | 无效产品类型                           |
| 9  | 响应使用 `isSuccess()` 检查                             | 遗漏错误处理                           |
| 10 | Webhook 必须验签 + 响应签名                               | 安全漏洞                             |
| 11 | Java 使用 `WaffoConfig.builder()`                   | SDK 初始化失败                        |
| 12 | 时间戳 SDK 自动注入                                      | 手动时间戳格式错误                        |
| 13 | merchantId SDK 自动注入                               | 重复设置                             |

## 生成的代码特性

* **错误处理**：区分 `WaffoUnknownStatusError`（可能成功）和 `WaffoError`（客户端错误）
* **安全**：Webhook 签名验证 + 响应签名、环境变量管理凭证
* **最佳实践**：幂等请求 ID、服务层分离、Webhook 先注册后解析 JSON
* **测试**：沙盒集成测试桩、测试卡号

详细文档参见 [waffo-integrate GitHub](https://github.com/waffo-com/waffo-integrate)。