> ## 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.

# API 参考

> 将 Waffo Pancake 集成到您的应用程序

## 概述

Waffo Pancake API 允许您以编程方式管理整个支付基础设施：

* 创建和管理门店
* 创建商品（一次性和订阅）
* 生成收银台会话和处理订单
* 管理订阅和计费
* 通过 GraphQL 查询数据
* 处理退款

## 基础 URL

所有 API 请求发送至：

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

## 架构

API 采用混合架构：

* **REST 端点** (`/v1/actions/...`) 用于所有写操作（创建、更新、删除）
* **GraphQL** (`/v1/graphql`) 用于所有读操作（查询）

所有 REST 端点仅使用 `POST` 方法。没有 GET、PUT、PATCH 或 DELETE 方法。

## TypeScript SDK

官方 [`@waffo/pancake-ts`](https://www.npmjs.com/package/@waffo/pancake-ts) SDK 提供完整类型安全的 API 封装。它自动处理认证、请求签名、幂等键和 Webhook 验签。

```bash theme={"system"}
npm install @waffo/pancake-ts
```

```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!,
});
```

以下文档的每个端点都包含 SDK 示例和 REST/cURL 示例。[查看完整 SDK 文档 ->](/integrate/sdks)

***

## 认证

Waffo Pancake 使用 **API Key 认证** 进行所有编程式 API 访问。SDK 自动处理 API Key 认证。

对于面向公众的收银台流程，使用 **Store Slug** 认证，通过 `X-Store-Slug` 请求头访问。

[了解更多认证信息 ->](/api-reference/authentication)

***

## 通用请求头

| 请求头                 | 必需  | 说明                                               |
| ------------------- | --- | ------------------------------------------------ |
| `Content-Type`      | 是   | 始终为 `application/json`                           |
| `X-Store-Slug`      | 条件性 | Store Slug（用于公开收银台流程）                            |
| `X-Environment`     | 条件性 | `test` 或 `prod`（使用 Store Slug 认证时必需，API Key 不需要） |
| `X-Idempotency-Key` | 可选  | 写操作的唯一 ID（缓存 24 小时）                              |

<Note>
  API Key 认证请求头（`X-Merchant-Id`、`X-Timestamp`、`X-Signature`）由 SDK 自动处理。您只需在初始化客户端时提供 Merchant ID 和私钥。
</Note>

***

## 请求格式

* **方法**: 所有写端点使用 `POST`
* **请求体**: JSON
* **时间戳**: ISO 8601 UTC（例如 `2026-01-23T00:00:00.000Z`）
* **金额**: 显示格式字符串（例如 `"29.00"` = \$29.00 USD）
* **货币**: ISO 4217 代码（例如 `USD`、`EUR`、`JPY`）
* **状态值**: 始终小写（例如 `active`，不是 `ACTIVE`）

### ID 格式

所有对外实体 ID 使用 **Short ID** 格式：`{PREFIX}_{base62}`。

| 前缀     | 实体                | 示例                            |
| ------ | ----------------- | ----------------------------- |
| `MER`  | Merchant          | `MER_2D5F8G3H1K4M6N9P`        |
| `STO`  | Store             | `STO_3bVzrkD0FJjFdZNLk8Ualx`  |
| `PROD` | Product / Version | `PROD_4cWAslE1GKkGeaOMl9Vbmy` |
| `ORD`  | Order             | `ORD_5dXBtmF2HLlHfbPNm0Wcnz`  |
| `PAY`  | Payment           | `PAY_6eYCunG3IMmIgcQOnaXdoA`  |
| `REF`  | Refund            | `REF_7fZDvoH4JNnJhdRPobYepB`  |
| `TKT`  | Ticket            | `TKT_8gAEwpI5KOoKieSQL1ZfqC`  |
| `KEY`  | API Key           | `KEY_4F7H0I5J3K6M8N1P`        |

<Note>
  Checkout Session ID 使用特殊格式：`cs_` + UUID（例如 `cs_550e8400-e29b-41d4-a716-446655440000`）。它们不属于 Short ID 体系。
</Note>

***

## 响应格式

### 成功

```json theme={"system"}
{
  "data": {
    "store": {
      "id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
      "name": "My Store",
      "status": "active",
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  }
}
```

### 错误

```json theme={"system"}
{
  "data": null,
  "errors": [
    {
      "message": "Store slug already exists",
      "layer": "store"
    }
  ]
}
```

<Note>
  在 `errors` 数组中，`errors[0]` 是故障的**根因**。后续条目代表请求链中更高层的调用方。
</Note>

### 错误 `layer` 字段

每个错误包含一个 `layer` 字符串，指示系统的哪个部分产生了该错误。调试时可用于定位根因。该值始终是预定义的层名称之一（例如 `"gateway"`、`"store"`、`"product"`）。

***

## HTTP 状态码

| 状态码 | 说明              |
| --- | --------------- |
| 200 | 成功              |
| 400 | 请求错误 -- 参数无效    |
| 401 | 未授权 -- 认证失败     |
| 403 | 禁止访问 -- 权限不足    |
| 404 | 未找到             |
| 409 | 冲突 -- 幂等请求正在处理中 |
| 429 | 频率限制 -- 请求过多    |
| 500 | 内部服务器错误         |
| 501 | 未实现             |
| 502 | 网关错误            |

***

## 环境

API Key 认证根据成功验证的密钥自动确定环境。Store Slug 认证需要 `X-Environment` 请求头：

| 环境 | 请求头值                  | 说明         |
| -- | --------------------- | ---------- |
| 测试 | `X-Environment: test` | 无真实扣费，数据隔离 |
| 生产 | `X-Environment: prod` | 真实交易       |

***

## 幂等性

通过 `X-Idempotency-Key` 请求头防止重复写操作：

| 项目   | 规格                        |
| ---- | ------------------------- |
| 请求头  | `X-Idempotency-Key`       |
| 最大长度 | 256 字符                    |
| 允许字符 | 字母、数字、连字符 (`-`)、下划线 (`_`) |
| 缓存时长 | 24 小时                     |

| 场景            | 行为             | 状态码   |
| ------------- | -------------- | ----- |
| 首次请求          | 正常执行，缓存 2xx 响应 | 原始状态码 |
| 重复（已完成）       | 返回缓存响应，不重新执行   | 原始状态码 |
| 重复（处理中）       | 返回冲突错误         | 409   |
| 原始请求失败（非 2xx） | 同一个键可以重试       | --    |

***

## 端点分组

<CardGroup cols={2}>
  <Card title="认证" icon="key" href="/api-reference/endpoints/auth">
    为收银台流程签发 Session Token
  </Card>

  <Card title="门店" icon="store" href="/api-reference/endpoints/stores">
    创建、更新和删除门店
  </Card>

  <Card title="一次性商品" icon="box" href="/api-reference/endpoints/onetime-products">
    创建和管理一次性购买商品
  </Card>

  <Card title="订阅商品" icon="repeat" href="/api-reference/endpoints/subscription-products">
    创建分层订阅商品和产品组
  </Card>

  <Card title="订单" icon="cart-shopping" href="/api-reference/endpoints/orders">
    创建收银台会话和订单
  </Card>

  <Card title="订阅" icon="calendar" href="/api-reference/endpoints/subscriptions">
    管理订阅生命周期
  </Card>

  <Card title="退款" icon="rotate-left" href="/api-reference/endpoints/refunds">
    请求和处理退款
  </Card>

  <Card title="GraphQL" icon="code" href="/api-reference/endpoints/graphql">
    通过 GraphQL 查询所有数据
  </Card>
</CardGroup>