跳转到主要内容

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.

​
概述

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 SDK 提供完整类型安全的 API 封装。它自动处理认证、请求签名、幂等键和 Webhook 验签。 
npm install @waffo/pancake-ts

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 文档 ->

​
认证

Waffo Pancake 使用 API Key 认证 进行所有编程式 API 访问。SDK 自动处理 API Key 认证。 对于面向公众的结账流程，使用 Store Slug 认证，通过 X-Store-Slug 请求头访问。 了解更多认证信息 ->

​
通用请求头

请求头必需说明
Content-Type是始终为 application/json
X-Store-Slug条件性Store Slug（用于公开结账流程）
X-Environment条件性test 或 prod（使用 Store Slug 认证时必需，API Key 不需要）
X-Idempotency-Key可选写操作的唯一 ID（缓存 24 小时）
API Key 认证请求头（X-Merchant-Id、X-Timestamp、X-Signature）由 SDK 自动处理。您只需在初始化客户端时提供 Merchant ID 和私钥。

​
请求格式

  • 方法: 所有写端点使用 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}。
前缀实体示例
MERMerchantMER_2D5F8G3H1K4M6N9P
STOStoreSTO_3bVzrkD0FJjFdZNLk8Ualx
PRODProduct / VersionPROD_4cWAslE1GKkGeaOMl9Vbmy
ORDOrderORD_5dXBtmF2HLlHfbPNm0Wcnz
PAYPaymentPAY_6eYCunG3IMmIgcQOnaXdoA
REFRefundREF_7fZDvoH4JNnJhdRPobYepB
TKTTicketTKT_8gAEwpI5KOoKieSQL1ZfqC
KEYAPI KeyKEY_4F7H0I5J3K6M8N1P
Checkout Session ID 使用特殊格式：cs_ + UUID（例如 cs_550e8400-e29b-41d4-a716-446655440000）。它们不属于 Short ID 体系。

​
响应格式

​
成功

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

​
错误

{
  "data": null,
  "errors": [
    {
      "message": "Store slug already exists",
      "layer": "store"
    }
  ]
}
在 errors 数组中，errors[0] 是故障的根因。后续条目代表请求链中更高层的调用方。

​
错误 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）同一个键可以重试—

​
端点分组

认证

为结账流程签发 Session Token

门店

创建、更新和删除门店

一次性商品

创建和管理一次性购买商品

订阅商品

创建分层订阅商品和产品组

订单

创建结账会话和订单

订阅

管理订阅生命周期

退款

请求和处理退款

GraphQL

通过 GraphQL 查询所有数据