概要
Waffo Pancake GraphQL API は、すべてのデータへの読み取り専用アクセスを提供します。書き込みには REST アクションエンドポイントを使用し、クエリには GraphQL を使用します。POST /v1/graphql
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 | クエリ欠落 / クエリ構文エラー / 無効な環境 / ロールの欠落または無効 |
| 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 } }
}
}
}
フィルタリング
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 } } |
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— 指定された環境でのステータスを返します
active で production では inactive になることがあります。
クエリ例
ストアと商品
ストア、単発商品、サブスクリプション商品、商品バージョンのクエリ
注文と決済
注文、サブスクリプション注文、決済、返金チケットのクエリ
分析
収益統計、決済分析、トレンド分析、顧客インサイト