> ## 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.
# API リファレンス
> Waffo Pancake をアプリケーションに統合する
## 概要
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`](https://www.npmjs.com/package/@waffo/pancake-ts) SDK は、完全な型安全性で API 全体をラップします。認証、リクエスト署名、冪等キー、Webhook 検証を自動的に処理します。
```bash theme={"system"}
npm install @waffo/pancake-ts
```
```typescript theme={"system"}
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 ドキュメントの全文 ->](/integrate/sdks)
***
## 認証
Waffo Pancake は、すべてのプログラム的な API アクセスに **API Key 認証** を使用します。API Key 認証は SDK によって自動的に処理されます。
公開チェックアウトフローでは、`X-Store-Slug` ヘッダーを使用した **Store Slug** 認証を使用します。
[認証について詳しく ->](/api-reference/authentication)
***
## 共通ヘッダー
| ヘッダー | 必須 | 説明 |
| ------------------- | ---- | ------------------------------------------------- |
| `Content-Type` | Yes | 常に `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}`。
| プレフィックス | エンティティ | 例 |
| ------- | ----------------- | ----------------------------- |
| `MER` | Merchant | `MER_2D5F8G3H1K4M6N9P` |
| `STO` | Store | `STO_3bVzrkD0FJjFdZNLk8Ualx` |
| `PROD` | Product / Version | `PROD_4cWAslE1GKkGeaOMl9Vbmy` |
| `ORD` | Order | `ORD_5dXBtmF2HLlHfbPNm0Wcnz` |
| `PAY` | Payment | `PAY_6eYCunG3IMmIgcQOnaXdoA` |
| `REF` | Refund | `REF_7fZDvoH4JNnJhdRPobYepB` |
| `TKT` | Ticket | `TKT_8gAEwpI5KOoKieSQL1ZfqC` |
| `KEY` | API Key | `KEY_4F7H0I5J3K6M8N1P` |
Checkout Session ID は特別なフォーマットを使用します: `cs_` + UUID（例：`cs_550e8400-e29b-41d4-a716-446655440000`）。Short ID システムの一部ではありません。
***
## レスポンスフォーマット
### 成功
```json theme={"system"}
{
"data": {
"store": {
"id": "STO_3bVzrkD0FJjFdZNLk8Ualx",
"name": "My Store",
"status": "active",
"createdAt": "2026-01-15T10:30:00.000Z"
}
}
}
```
### エラー
```json theme={"system"}
{
"data": null,
"errors": [
{
"message": "Store slug already exists",
"layer": "store"
}
]
}
```
`errors` 配列では、`errors[0]` が障害の**根本原因**です。後続のエントリはリクエストチェーン内の上位レベルの呼び出し元を表します。
### エラーの `layer` フィールド
各エラーには、システムのどの部分がエラーを生成したかを示す `layer` 文字列が含まれます。デバッグ時に根本原因を特定するために使用してください。値は常に定義済みのレイヤー名のいずれかです（例：`"gateway"`、`"store"`、`"product"`）。
***
## HTTP ステータスコード
| コード | 説明 |
| --- | --------------------------- |
| 200 | 成功 |
| 400 | Bad Request -- 無効なパラメータ |
| 401 | Unauthorized -- 認証失敗 |
| 403 | Forbidden -- 権限不足 |
| 404 | Not Found |
| 409 | Conflict -- 冪等リクエストが処理中 |
| 429 | Rate Limited -- リクエストが多すぎます |
| 500 | Internal Server Error |
| 501 | Not Implemented |
| 502 | Bad Gateway |
***
## 環境
API Key 認証は、署名の検証に成功した鍵に基づいて環境を自動的に決定します。Store Slug 認証では `X-Environment` ヘッダーが必要です。
| 環境 | ヘッダー値 | 説明 |
| ---------- | --------------------- | -------------- |
| Test | `X-Environment: test` | 実際の課金なし、データは隔離 |
| Production | `X-Environment: prod` | 実際のトランザクション |
***
## 冪等性
`X-Idempotency-Key` ヘッダーを含めることで、書き込み操作の重複を防止できます。
| 項目 | 仕様 |
| ------- | ------------------------------ |
| ヘッダー | `X-Idempotency-Key` |
| 一意性 | マーチャントアカウント内でリクエストごとにグローバルに一意 |
| 最大長 | 256 文字 |
| 使用可能な文字 | 英字、数字、ハイフン (`-`)、アンダースコア (`_`) |
| キャッシュ期間 | 24 時間 |
可能な場合はキーを SDK に生成させてください。SDK は `merchantId` + パス + ボディ から決定的なハッシュを導出するため、構造上リクエストごとに一意になります。自分で構築する場合は、`merchantId` と UUID を組み合わせてください。
```
X-Idempotency-Key: MER_2aUyqjCzEIiEcYMKj7TZtw-8f14e45f-ea8c-4b0a-9f7d-3b2c1d0e5a67
```
短く推測しやすいキーは、別のリクエストが既に使用しているキーと一致する可能性があり、その場合はそのリクエストのキャッシュされたレスポンスが返されます。詳しい要件は [エラー -> 安全なリトライのための冪等性](/api-reference/errors#idempotency-for-safe-retries) を参照してください。
| シナリオ | 動作 | ステータス |
| ----------------- | ---------------------- | ------- |
| 初回リクエスト | 通常実行、2xx レスポンスをキャッシュ | 元のステータス |
| 重複（完了済み） | 再実行せずにキャッシュされたレスポンスを返す | 元のステータス |
| 重複（処理中） | コンフリクトエラーを返す | 409 |
| 元のリクエストが失敗（非 2xx） | 同じキーでリトライ可能 | -- |
***
## エンドポイントグループ
チェックアウトフロー用のセッショントークン発行
ストアの作成、更新、削除
単発購入商品の作成と管理
階層型サブスクリプション商品とグループの作成
チェックアウトセッションと注文の作成
サブスクリプションライフサイクルの管理
返金のリクエストと処理
GraphQL ですべてのデータをクエリ