GraphQL API

概要

Waffo Pancake GraphQL API は、すべてのデータへの読み取り専用アクセスを提供します。書き込みには REST アクションエンドポイントを使用し、クエリには GraphQL を使用します。

POST /v1/graphql

認証: API Key

GraphQL API はクエリのみをサポートしています。すべての書き込み操作（作成、更新、削除）は REST アクションエンドポイントを使用します。

リクエストの作成

リクエストボディ

フィールド	型	必須	説明
`query`	string	Yes	GraphQL クエリ文字列
`variables`	object	No	クエリ変数

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" }]

// Uses callApi() helper from authentication.mdx
const result = await callApi("POST", "/v1/graphql", {
  query: "query { stores { id name status } }",
  variables: {},
});
console.log(result.data.stores);
// => [{ id: "STO_2aUyqjCzEIiEcYMKj7TZtw", name: "My Store", status: "active" }]

// Uses callApi() helper from authentication.mdx
String body = """
    {"query":"query { stores { id name status } }","variables":{}}""";

String response = callApi("POST", "/v1/graphql", body);
System.out.println(response);
// => {"data":{"stores":[{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"My Store","status":"active"}]}}

# Uses call_api() helper from authentication.mdx
result = call_api("POST", "/v1/graphql", {
    "query": "query { stores { id name status } }",
    "variables": {},
})
stores = result["data"]["stores"]
print(stores)
# => [{"id": "STO_2aUyqjCzEIiEcYMKj7TZtw", "name": "My Store", "status": "active"}]

// Uses callAPI() helper from authentication.mdx
body := map[string]interface{}{
    "query":     "query { stores { id name status } }",
    "variables": map[string]interface{}{},
}
result, err := callAPI("POST", "/v1/graphql", body)
if err != nil {
    log.Fatal(err)
}
fmt.Println(string(result))
// => {"data":{"stores":[{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"My Store","status":"active"}]}}

// Uses call_api() helper from authentication.mdx
let body = serde_json::json!({
    "query": "query { stores { id name status } }",
    "variables": {}
});
let result = call_api("POST", "/v1/graphql", &body).await?;
println!("{}", result);
// => {"data":{"stores":[{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"My Store","status":"active"}]}}

/* Uses call_api() helper from authentication.mdx */
const char *body = "{\"query\":\"query { stores { id name status } }\",\"variables\":{}}";
char *response = call_api("POST", "/v1/graphql", body);
printf("%s\n", response);
free(response);

// Uses callApi() helper from authentication.mdx
std::string body = R"({"query":"query { stores { id name status } }","variables":{}})";
std::string response = callApi("POST", "/v1/graphql", body);
std::cout << response << std::endl;
// => {"data":{"stores":[{"id":"STO_2aUyqjCzEIiEcYMKj7TZtw","name":"My Store","status":"active"}]}}

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"query":"query { stores { id name status } }","variables":{}}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/graphql
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/graphql" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"query":"query { stores { id name status } }","variables":{}}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/graphql
$TIMESTAMP
$BODY_HASH"

SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

wget -qO- "https://api.waffo.ai/v1/graphql" \
  --header="Content-Type: application/json" \
  --header="X-Merchant-Id: $MERCHANT_ID" \
  --header="X-Timestamp: $TIMESTAMP" \
  --header="X-Signature: $SIGNATURE" \
  --post-data="$BODY"

ステータスコード

ステータス	説明
200	クエリ成功（GraphQL エラーはレスポンスボディの `errors` フィールドに含まれます）
400	リクエストボディが有効な JSON ではない / クエリ欠落 / クエリ構文エラー / 無効な環境 / ロールの欠落または無効 / `errors` がすべて引数エラー（`extensions.code` が `BAD_USER_INPUT`）
401	認証失敗
403	操作タイプが許可されていません（Query のみサポート）/ このエンドポイントでは許可されないロール
429	レート制限を超過 —— `Retry-After` ヘッダーの間隔後に再試行
500	内部サーバーエラー

スキーマイントロスペクション

推奨: 標準の GraphQL イントロスペクションを使用して完全なスキーマを検出してください。これにより、常に最新の型とフィールドで作業できます。

GraphQL の型は REST/SDK の型と異なります。 例えば、prices は REST では Record<string, PriceInfo>（オブジェクトマップ）ですが、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 } }
    }
  }
}

API Key 認証では、単一エンティティクエリ、フィルター付きリストクエリ、カウントクエリ、分析クエリを含む 18 種類のクエリタイプにアクセスできます。

フィルタリング

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`	`{ attemptCount: { gte: 3 } }`
`AmountFilter`	`eq`, `ne`, `gt`, `gte`, `lt`, `lte`	`{ amount: { gte: "9.99" }, currency: { eq: "USD" } }`
`BooleanFilter`	`eq`	`{ isActive: { eq: true } }`

引数はクエリ実行前に検証されます。ID フィルター（id、storeId、orderId など）はエンティティの Short ID（例: STO_xxx）または UUID を受け付け、eq、ne、in、notIn、isNull のみ使用できます。DateTimeFilter の値は ISO 8601 形式の日付または日時である必要があります。不正な値の場合はエラーが返され、extensions.code は BAD_USER_INPUT になります。

AmountFilter の値は通貨の主単位の10進文字列です（例: "9.99"）。金額フィルターは、同じ filter オブジェクト内に currency: { eq: "..." }（単一通貨）を必ず併記する必要があります。通貨をまたいだ金額比較はサポートされていません。

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 になることがあります。

クエリ例

ストアと商品

ストア、単発商品、サブスクリプション商品、商品バージョンのクエリ

注文と決済

注文、サブスクリプション注文、決済、返金チケットのクエリ

分析

収益統計、決済分析、トレンド分析、顧客インサイト

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

概要

リクエストの作成

リクエストボディ

ステータスコード

スキーマイントロスペクション

利用可能なすべてのクエリを検出

型フィールドを検出

フィルタリング

ページネーション

環境固有のフィールド

クエリ例

ストアと商品

注文と決済

分析

​概要

​リクエストの作成

​リクエストボディ

​ステータスコード

​スキーマイントロスペクション

​利用可能なすべてのクエリを検出

​型フィールドを検出

​フィルタリング

​ページネーション

​環境固有のフィールド

​クエリ例

ストアと商品

注文と決済

分析

概要

リクエストの作成

リクエストボディ

ステータスコード

スキーマイントロスペクション

利用可能なすべてのクエリを検出

型フィールドを検出

フィルタリング

ページネーション

環境固有のフィールド

クエリ例