メインコンテンツへスキップ

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 リクエストは以下の URL に対して行います。 
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!,
});
以下に文書化されたすべてのエンドポイントには、REST/cURL の例と合わせて SDK の例が含まれています。SDK ドキュメントの全文 ->

​
認証

Waffo Pancake は、すべてのプログラム的な API アクセスに API Key 認証 を使用します。API Key 認証は SDK によって自動的に処理されます。 公開チェックアウトフローでは、X-Store-Slug ヘッダーを使用した Store Slug 認証を使用します。 認証について詳しく ->

​
共通ヘッダー

ヘッダー必須説明
Content-TypeYes常に 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成功
400Bad Request — 無効なパラメータ
401Unauthorized — 認証失敗
403Forbidden — 権限不足
404Not Found
409Conflict — 冪等リクエストが処理中
429Rate Limited — リクエストが多すぎます
500Internal Server Error
501Not Implemented
502Bad Gateway

​
環境

API Key 認証は、署名の検証に成功した鍵に基づいて環境を自動的に決定します。Store Slug 認証では X-Environment ヘッダーが必要です。
環境ヘッダー値説明
TestX-Environment: test実際の課金なし、データは隔離
ProductionX-Environment: prod実際のトランザクション

​
冪等性

X-Idempotency-Key ヘッダーを含めることで、書き込み操作の重複を防止できます。
項目仕様
ヘッダーX-Idempotency-Key
最大長256 文字
使用可能な文字英字、数字、ハイフン (-)、アンダースコア (_)
キャッシュ期間24 時間
シナリオ動作ステータス
初回リクエスト通常実行、2xx レスポンスをキャッシュ元のステータス
重複（完了済み）再実行せずにキャッシュされたレスポンスを返す元のステータス
重複（処理中）コンフリクトエラーを返す409
元のリクエストが失敗（非 2xx）同じキーでリトライ可能—

​
エンドポイントグループ

認証

チェックアウトフロー用のセッショントークン発行

ストア

ストアの作成、更新、削除

単発購入商品

単発購入商品の作成と管理

サブスクリプション商品

階層型サブスクリプション商品とグループの作成

注文

チェックアウトセッションと注文の作成

サブスクリプション

サブスクリプションライフサイクルの管理

返金

返金のリクエストと処理

GraphQL

GraphQL ですべてのデータをクエリ