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

# 集成

> 为你的应用选择合适的接入路径

## 先选接入路径

<CardGroup cols={3}>
  <Card title="AI 集成" icon="sparkles" href="/zh/integrate/ai-integration">
    **最快落地**

    适合已有代码仓库，希望借助 Claude Code 等编码代理完成方案设计、接口接入和联调验证的团队。
  </Card>

  <Card title="API / SDK" icon="code" href="/zh/integrate/sdks">
    **最可控**

    适合需要自定义收银台流程、服务端编排、动态定价或精细化权限控制的场景。
  </Card>

  <Card title="托管收银台" icon="link" href="/zh/quickstart">
    **最简单**

    适合先上线支付链接、快速验证收款闭环，后续再逐步深化集成的团队。
  </Card>
</CardGroup>

***

## 如何选择

| 如果你当前更关心          | 建议路径      | 原因                         |
| ----------------- | --------- | -------------------------- |
| 尽快完成首个可用版本        | AI 集成     | 适合直接把现有代码仓库交给编码代理生成接入方案和代码 |
| 对支付流程和服务端逻辑有完整控制权 | API / SDK | 适合自定义收银台、动态定价、权限控制和内部编排    |
| 先验证收款闭环，再决定是否深入开发 | 托管收银台     | 适合低工程投入、快速上线               |

<Note>
  很多团队的实际路径是：先用托管收银台或 AI 集成完成第一版，再逐步演进到 API / SDK 深度集成。
</Note>

***

## 一次完整集成通常包含什么

大多数 Waffo Pancake 集成都会包含四部分：

* **身份认证**：为服务端调用准备 Merchant ID 和 API Key
* **产品与收银台**：创建一次性商品或订阅商品，并生成收银台入口
* **Webhook**：接收支付、退款、订阅生命周期事件
* **环境切换**：先在测试环境验证，再发布到生产环境

```
你的应用
    |
    +-- 身份认证 --> API / SDK 调用
    |
    +-- 商品与收银台 --> 收款
    |
    +-- Webhook --> 同步订单与订阅状态
```

<Note>
  你不需要一开始就把所有层都做完。很多团队会先从托管收银台或 AI 集成开始，后续再逐步深化 API 能力。
</Note>

***

## 每条路径通常会交付什么

### AI 集成

* 让 AI 编码助手阅读 `llms-full.txt` 和官方 skill 上下文
* 结合你的技术栈生成接入代码、Webhook 处理和联调建议
* 适合已有代码仓库，希望缩短从设计到落地的时间

### API / SDK

* 由你的服务端控制商品、收银台、Webhook 和状态同步
* 适合需要动态定价、细粒度权限控制、内部业务编排的场景
* 更适合长期演进、深度定制和复杂计费模型

### 托管收银台

* 直接使用控制台生成的收银台链接或公开支付入口
* 适合先验证产品是否能收款，再决定是否继续投入工程资源
* 最适合作为第一阶段接入方案

***

## 推荐实施顺序

<Steps>
  <Step title="创建账户">
    在 [Merchant Dashboard](https://pancake.waffo.ai/merchant/auth/signin) 注册并创建第一个商店。
  </Step>

  <Step title="设置身份认证">
    在商户控制台准备 Merchant ID 与 API Key。
  </Step>

  <Step title="创建商品">
    先定义商品类型、价格和计费周期，再通过控制台或 API 创建商品。
  </Step>

  <Step title="实现收银台">
    通过 API 创建 Checkout Session，或直接使用控制台生成的收银台链接。
  </Step>

  <Step title="处理 Webhook">
    设置 Webhook 端点，处理支付、退款和订阅事件。
  </Step>

  <Step title="端到端测试">
    使用 [测试模式](/zh/features/test-mode) 和测试卡号验证完整流程。
  </Step>

  <Step title="上线">
    发布商品并切换到生产环境。
  </Step>
</Steps>

***

## 实施前准备

在真正写代码前，建议先明确这几项：

* 你卖的是一次性商品、订阅，还是两者组合
* 是否需要动态定价，例如超额用量、充值包、按报价收费
* 成功支付后，系统需要开通什么权限或发放什么资源
* 你希望通过哪些 Webhook 事件驱动业务状态变化
* 哪些能力只在测试环境验证，哪些要等到正式环境再开启

<Tip>
  如果这些问题还没完全想清楚，优先走 AI 集成路径会更高效；如果这些规则已经很清晰，直接进入 API / SDK 路径更合适。
</Tip>

***

## 常用能力入口

<CardGroup cols={2}>
  <Card title="身份认证" icon="lock" href="/zh/integrate/authentication">
    配置 Merchant ID、API Key 和服务端认证方式。
  </Card>

  <Card title="测试模式" icon="flask" href="/zh/features/test-mode">
    使用测试环境和测试卡号验证完整链路。
  </Card>

  <Card title="Webhook" icon="webhook" href="/zh/integrate/webhooks">
    接收实时事件并同步订单、退款、订阅状态。
  </Card>

  <Card title="SDKs" icon="code" href="/zh/integrate/sdks">
    查看官方 SDK、框架接入方式和代码示例。
  </Card>

  <Card title="AI 集成" icon="sparkles" href="/zh/integrate/ai-integration">
    用 AI 编码助手完成方案设计、代码生成和联调。
  </Card>

  <Card title="快速入门" icon="rocket" href="/zh/quickstart">
    从第一笔支付开始，快速理解完整接入路径。
  </Card>
</CardGroup>

***

## 开发者设置

API 与开发页面提供将 Waffo Pancake 与您的应用程序集成的工具。

<Frame>
  <img src="https://mintcdn.com/waffo/B4zeaxzoWQQ2IKOM/images/dashboard/developers-api-keys.png?fit=max&auto=format&n=B4zeaxzoWQQ2IKOM&q=85&s=5998536bbb675141922d4548c4378704" alt="Developer API Keys" width="1440" height="900" data-path="images/dashboard/developers-api-keys.png" />
</Frame>

## API 密钥

### 概述

API 密钥用于验证您对 Waffo Pancake API 的请求。

<CardGroup cols={2}>
  <Card title="测试环境密钥" icon="flask">
    * 创建时选择测试环境
    * 用于开发和测试
    * 无真实收费
  </Card>

  <Card title="生产环境密钥" icon="key">
    * 创建时选择生产环境
    * 用于真实支付
    * 私钥必须保密
  </Card>
</CardGroup>

### 密钥类型

| 密钥类型       | 使用场景  | 描述             |
| ---------- | ----- | -------------- |
| **API 密钥** | 仅服务器端 | 签名请求，完全 API 访问 |

### API 密钥认证

<Note>
  API Key 认证由 SDK 自动处理。安装 `@waffo/pancake-ts` 后，只需提供 Merchant ID 和私钥，SDK 会自动完成请求签名。
</Note>

```typescript theme={"system"}
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
```

<Warning>
  切勿在客户端代码、版本控制或公共仓库中暴露您的私钥。
</Warning>

### 创建 API 密钥

API 密钥用于安全的服务端认证：

<Steps>
  <Step title="导航到开发者">
    前往控制台 → API 与开发 → API 密钥
  </Step>

  <Step title="点击'创建 API 密钥'">
    API 密钥生成器打开
  </Step>

  <Step title="生成密钥对">
    点击"生成"创建密钥对

    * 公钥发送到服务器
    * 私钥由您保管
  </Step>

  <Step title="命名您的密钥">
    给它一个描述性名称（例如，"生产服务器"）
  </Step>

  <Step title="选择环境">
    选择测试或生产环境
  </Step>

  <Step title="下载私钥">
    **重要：** 下载并安全存储您的私钥
  </Step>
</Steps>

<Warning>
  您的私钥只显示一次。请安全存储 - 您需要它进行 API 认证。
</Warning>

### 管理密钥

| 操作 | 描述                          |
| -- | --------------------------- |
| 查看 | 查看密钥名称、创建日期                 |
| 删除 | 永久移除密钥（通过 `delete-key` API） |

## Webhooks

### 什么是 Webhooks？

Webhooks 在 Waffo Pancake 中发生事件时通知您的服务器。

### 可用事件

| 事件                               | 触发条件    |
| -------------------------------- | ------- |
| `order.completed`                | 订单完成    |
| `subscription.activated`         | 订阅已激活   |
| `subscription.payment_succeeded` | 订阅扣费成功  |
| `subscription.updated`           | 订阅已更新   |
| `subscription.canceling`         | 订阅取消已安排 |
| `subscription.canceled`          | 订阅结束    |
| `subscription.uncanceled`        | 订阅取消已撤回 |
| `subscription.past_due`          | 订阅扣费逾期  |
| `refund.succeeded`               | 退款处理成功  |
| `refund.failed`                  | 退款处理失败  |

### 设置 Webhooks

<Steps>
  <Step title="添加端点">
    输入您的 webhook URL（必须是 HTTPS）
  </Step>

  <Step title="选择事件">
    选择要接收的事件
  </Step>

  <Step title="获取签名密钥">
    复制 webhook 签名密钥
  </Step>

  <Step title="验证签名">
    在您的代码中实现签名验证
  </Step>
</Steps>

### Webhook 负载示例

```json theme={"system"}
{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 9900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}
```

### 签名验证

验证 webhook 真实性：

```javascript theme={"system"}
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
```

### Webhook 最佳实践

<AccordionGroup>
  <Accordion title="快速响应">
    在 5 秒内返回 2xx 状态。异步处理重型工作。
  </Accordion>

  <Accordion title="处理重复">
    事件可能会多次发送。使用事件 ID 进行去重。
  </Accordion>

  <Accordion title="重试逻辑">
    失败的 webhooks 最多重试 5 次，采用指数退避。
  </Accordion>

  <Accordion title="监控失败">
    为 webhook 投递失败设置告警。
  </Accordion>
</AccordionGroup>

## API 文档

### 基础 URL

```
https://api.waffo.ai/v1
```

### 认证

**使用 SDK 进行 API 密钥认证（服务器间通信）：**

```typescript theme={"system"}
import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { store } = await client.stores.create({ name: "My Store" });
```

### 常用端点

| 端点                                                | 方法   | 描述             |
| ------------------------------------------------- | ---- | -------------- |
| `/v1/actions/onetime-product/create-product`      | POST | 创建一次性产品        |
| `/v1/actions/subscription-product/create-product` | POST | 创建订阅           |
| `/v1/actions/onetime-order/create-order`          | POST | 创建收银台会话        |
| `/v1/graphql`                                     | POST | 查询数据 (GraphQL) |

## 速率限制

| 模式 | 限制         |
| -- | ---------- |
| 测试 | 100 请求/分钟  |
| 正式 | 1000 请求/分钟 |

当被限流时，您将收到 `429` 响应和 `Retry-After` 头。

## 安全最佳实践

<CardGroup cols={2}>
  <Card title="环境变量" icon="lock">
    将密钥存储在环境变量中，切勿在代码中。
  </Card>

  <Card title="密钥轮换" icon="rotate">
    定期轮换密钥，特别是在团队变动后。
  </Card>

  <Card title="IP 限制" icon="shield">
    限制密钥仅用于已知 IP 地址。
  </Card>

  <Card title="最小权限" icon="user-shield">
    仅创建具有所需权限的密钥。
  </Card>
</CardGroup>

## 测试

### 测试模式

使用测试模式进行开发：

* 所有端点工作方式相同
* 不处理真实收费
* 可用测试卡号
* 完整的 webhook 测试

### 测试卡

| 卡号                    | 行为             |
| --------------------- | -------------- |
| `4576 7500 0000 0110` | 成功（Visa）       |
| `2226 9000 0000 0110` | 成功（Mastercard） |
| `4576 7500 0000 0220` | 拒绝             |

## 日志和调试

### API 日志

查看最近的 API 请求：

* 请求方法和端点
* 响应状态
* 时间戳
* 请求/响应体

### Webhook 日志

跟踪 webhook 投递：

* 事件类型
* 投递状态
* 收到的响应
* 重试次数