Waffo Pancake GraphQL API 提供对所有数据的只读访问。写操作使用 REST action 端点，查询使用 GraphQL。
认证方式： API Key
发送请求
请求体
| 字段 | 类型 | 必需 | 说明 |
|---|
query | string | 是 | GraphQL 查询字符串 |
variables | object | 否 | 查询变量 |
import { WaffoPancake } from "@waffo/pancake-ts";
const client = new WaffoPancake({
merchantId: process.env.WAFFO_MERCHANT_ID!,
privateKey: process.env.WAFFO_PRIVATE_KEY!,
});
interface StoresQuery {
stores: Array<{ id: string; name: string; status: string }>;
}
const result = await client.graphql.query<StoresQuery>({
query: `{ stores { id name status } }`,
});
console.log(result.stores);
// => [{ id: "STO_2aUyqjCzEIiEcYMKj7TZtw", name: "My Store", status: "active" }]
状态码
| 状态码 | 说明 |
|---|
| 200 | 查询成功（GraphQL 错误在响应体的 errors 字段中） |
| 400 | 缺少查询 / 深度超限 / 无效环境 / 缺少或无效角色 |
| 401 | 认证失败 |
| 403 | 不允许的操作类型（仅支持 Query） |
| 500 | 内部服务器错误 |
Schema 内省
推荐： 使用标准 GraphQL 内省查询来发现完整 Schema。这确保您始终使用最新的类型和字段。
GraphQL 类型与 REST/SDK 类型不同。 例如，prices 在 REST 中是 Record<string, PriceInfo>（对象 map），但在 GraphQL 中是 [CurrencyPrice!]!（{currency, priceInfo} 数组）；metadata 在 REST 中是解析后的对象，但在 GraphQL 中是 JSON 字符串。请勿使用 SDK TypeScript 类型定义来构造 GraphQL 查询——始终使用内省或以下示例。
查询所有可用查询
query {
__schema {
queryType {
fields {
name
description
args {
name
type { name kind }
}
}
}
}
}
查询类型字段
query {
__type(name: "Store") {
name
fields {
name
type { name kind ofType { name } }
}
}
}
GraphQL 查询支持使用类型化过滤对象进行过滤：
| 类型 | 运算符 | 示例 |
|---|
StringFilter | eq, ne, in, contains | { storeId: { eq: "STO_xxx" } } |
DateTimeFilter | eq, gt, lt, gte, lte | { createdAt: { gte: "2026-01-01" } } |
IntFilter | eq, gt, lt, gte, lte | { amount: { gte: 1000 } } |
BooleanFilter | eq | { isActive: { eq: true } } |
query {
onetimeProducts(
filter: {
storeId: { eq: "STO_3bVzrkD0FJjFdZNLk8Ualx" }
status: { eq: "active" }
}
) {
id
name
prices
}
}
使用 limit 和 offset 进行分页。使用 *Count 查询获取总数。
query {
onetimeProducts(
filter: { storeId: { eq: "STO_3bVzrkD0FJjFdZNLk8Ualx" } }
limit: 10
offset: 0
) {
id
name
}
onetimeProductsCount(
filter: { storeId: { eq: "STO_3bVzrkD0FJjFdZNLk8Ualx" } }
)
}
| 参数 | 类型 | 说明 |
|---|
limit | integer | 返回的最大结果数 |
offset | integer | 跳过的结果数 |
环境相关字段
API Key 的环境影响返回的商品数据：
version — 返回指定环境的版本status — 返回指定环境中的状态
一个商品可能在 test 环境中是 active，但在 production 环境中是 inactive（如果尚未发布）。
查询示例
门店与商品
查询门店、一次性商品、订阅商品和商品版本
