跳转到主要内容

​
概述

Waffo Pancake GraphQL API 提供对所有数据的只读访问。写操作使用 REST action 端点，查询使用 GraphQL。 
POST /v1/graphql
认证方式： API Key
GraphQL API 仅支持查询。所有写操作（创建、更新、删除）使用 REST action 端点。
查询深度限制：最大嵌套深度为 7 层。超过此限制返回 400。深度从根 query 字段开始计数。每个嵌套的对象选择增加 1 层深度。标量字段不增加深度 — 只有包含子选择的对象/列表字段才计数。
query {                                    # depth 1
  orders {                                 # depth 2
    id                                     # (scalar, no depth increase)
    payments {                             # depth 3
      id
      refunds {                            # depth 4
        id
        refundTicket {                     # depth 5
          id
          versions {                       # depth 6
            id
            reviewedByMerchant {           # depth 7 (limit)
              id                           # OK -- scalar at depth 7
              # store { ... }              # Would be depth 8 -- REJECTED
            }
          }
        }
      }
    }
  }
}
如果查询超过限制，可通过拆分为多个查询或移除不必要的嵌套层级来简化。

​
发起请求

​
请求体

字段类型必需说明
querystring是GraphQL 查询字符串
variablesobject否查询变量
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。这确保您始终使用最新的类型和字段。

​
发现所有可用查询

query {
  __schema {
    queryType {
      fields {
        name
        description
        args {
          name
          type { name kind }
        }
      }
    }
  }
}

​
发现类型字段

query {
  __type(name: "Store") {
    name
    fields {
      name
      type { name kind ofType { name } }
    }
  }
}
merchant 角色可以访问 18 种查询类型，包括单实体查询、带过滤的列表查询、计数查询和分析查询。

​
过滤

GraphQL 查询支持使用类型化过滤对象进行过滤：
类型运算符示例
StringFiltereq、ne、in、contains{ storeId: { eq: "STO_xxx" } }
DateTimeFiltereq、gt、lt、gte、lte{ createdAt: { gte: "2026-01-01" } }
IntFiltereq、gt、lt、gte、lte{ amount: { gte: 1000 } }
BooleanFiltereq{ 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" } }
  )
}
参数类型说明
limitinteger返回结果的最大数量
offsetinteger跳过的结果数量

​
环境相关字段

API Key 环境影响返回的产品数据：
  • version — 返回指定环境的版本
  • status — 返回指定环境中的状态
产品可能在测试环境中 active 但在生产环境中 inactive（如果尚未发布）。

​
查询示例

门店和产品

查询门店、一次性产品、订阅产品和产品版本

订单和支付

查询订单、订阅订单、支付和退款工单

数据分析

收入统计、支付分析、趋势分析和客户洞察