> ## 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.

# インテグレーション

> アプリに最適な統合パスを選ぶ

## まず接続パスを選ぶ

<CardGroup cols={3}>
  <Card title="AI Integration" icon="sparkles" href="/ja/integrate/ai-integration">
    **最速で導入**

    既存コードベースがあり、Claude Code などのコーディングエージェントで設計、実装、検証まで進めたいチーム向けです。
  </Card>

  <Card title="API / SDK" icon="code" href="/ja/integrate/sdks">
    **最も高い制御性**

    チェックアウトフローのカスタマイズ、サーバー側オーケストレーション、動的価格設定、細かな制御が必要なケース向けです。
  </Card>

  <Card title="Hosted Checkout" icon="link" href="/ja/quickstart">
    **最もシンプル**

    まず決済リンクで素早く収益化を確認し、その後で段階的に統合を深めたいチーム向けです。
  </Card>
</CardGroup>

***

## どう選ぶか

| いま重視したいこと                | おすすめのパス         | 理由                                     |
| ------------------------ | --------------- | -------------------------------------- |
| まず最初の利用可能版を早く出したい        | AI Integration  | 既存コードベースをもとに、コーディングエージェントで短時間に統合を進めやすい |
| 決済フローやサーバー側ロジックを細かく制御したい | API / SDK       | カスタムチェックアウト、動的価格、権限制御、内部オーケストレーションに向く  |
| 深い実装の前に収益化フローを検証したい      | Hosted Checkout | エンジニアリングコストを抑えて素早く公開できる                |

<Note>
  多くのチームは、最初に Hosted Checkout や AI Integration で立ち上げ、その後に API / SDK へ拡張していきます。
</Note>

***

## 典型的なインテグレーション構成

Waffo Pancake の統合は、通常次の 4 つで構成されます。

* **認証**: サーバー側リクエストのための Merchant ID と API Key
* **商品とチェックアウト**: 単発商品またはサブスクリプション商品を作成し、購入導線を用意
* **Webhook**: 決済、返金、サブスクリプションイベントの受信
* **環境移行**: テスト環境で検証し、その後本番へ公開

```
あなたのアプリケーション
    |
    +-- 認証 --> API / SDK リクエスト
    |
    +-- 商品 + チェックアウト --> 決済
    |
    +-- Webhook --> 注文・サブスクリプション同期
```

<Note>
  初日からすべてを実装する必要はありません。Hosted Checkout や AI Integration から始めて、後で API 利用を深めることもできます。
</Note>

***

## 各パスで得られるもの

### AI Integration

* AI コーディングアシスタントに `llms-full.txt` と公式 skill コンテキストを読ませる
* 技術スタックに合わせた統合コード、Webhook 処理、検証手順を生成できる
* 既存コードベースがあり、実装時間を短縮したい場合に向く

### API / SDK

* 商品、チェックアウト、Webhook、状態同期をサーバー側で完全に制御できる
* 動的価格、細かな権限管理、独自のバックエンド編成に向く
* 長期的なカスタマイズや複雑な課金ロジックに最適

### Hosted Checkout

* ダッシュボードで生成したチェックアウトリンクや公開購入導線をそのまま使える
* 深い開発投資の前に商用フローを検証したい場合に向く
* 多くの場合、最初の導入段階に最適

***

## 推奨の導入順序

<Steps>
  <Step title="アカウント作成">
    [Merchant Dashboard](https://pancake.waffo.ai/merchant/auth/signin) でサインアップし、最初のストアを作成します。
  </Step>

  <Step title="認証を準備">
    マーチャントダッシュボードで Merchant ID と API Key を用意します。
  </Step>

  <Step title="商品を作成">
    商品タイプ、価格、課金周期を定義し、ダッシュボードまたは API で商品を作成します。
  </Step>

  <Step title="チェックアウトを実装">
    API で Checkout Session を作成するか、ダッシュボードで生成したチェックアウトリンクを使います。
  </Step>

  <Step title="Webhook を処理">
    決済、返金、サブスクリプションイベント用の Webhook エンドポイントを設定します。
  </Step>

  <Step title="エンドツーエンドで検証">
    [テストモード](/ja/features/test-mode) とテストカードで全体フローを確認します。
  </Step>

  <Step title="本番公開">
    商品を公開し、本番環境へ切り替えます。
  </Step>
</Steps>

***

## 実装前に決めておくこと

コードを書く前に、次の点を明確にしておくと進めやすくなります。

* 単発商品、サブスクリプション、または両方を扱うか
* 超過利用、クレジット、見積もり金額などで動的価格が必要か
* 支払い完了後に付与するアクセス権限やリソースは何か
* どの Webhook イベントで業務状態を更新するか
* どの機能を本番移行までテスト環境に留めるか

<Tip>
  これらがまだ曖昧なら AI Integration から始めるのが効率的です。すでに整理できているなら API / SDK パスの方が適しています。
</Tip>

***

## 主要な導線

<CardGroup cols={2}>
  <Card title="認証" icon="lock" href="/ja/integrate/authentication">
    Merchant ID、API Key、サーバー側認証を設定します。
  </Card>

  <Card title="テストモード" icon="flask" href="/ja/features/test-mode">
    実課金なしでフルフローを検証します。
  </Card>

  <Card title="Webhooks" icon="webhook" href="/ja/integrate/webhooks">
    リアルタイムイベントを受け取り、注文とサブスクリプションを同期します。
  </Card>

  <Card title="SDKs" icon="code" href="/ja/integrate/sdks">
    公式 SDK、フレームワークパターン、コード例を確認します。
  </Card>

  <Card title="AI Integration" icon="sparkles" href="/ja/integrate/ai-integration">
    AI コーディングアシスタントで設計、実装、検証を進めます。
  </Card>

  <Card title="Quickstart" icon="rocket" href="/ja/quickstart">
    最初の決済フローからエンドツーエンドの導線を素早く理解します。
  </Card>
</CardGroup>

***

## 開発者設定

API と開発ページは、Waffo Pancake をアプリケーションと統合するためのツールを提供します。

## APIキー

### 概要

APIキーは Waffo Pancake API へのサーバー間リクエストを認証します。

<CardGroup cols={2}>
  <Card title="テストキー" icon="flask">
    * `test` 環境用に作成
    * 開発に使用
    * 実際の課金なし
    * 本番データと分離
  </Card>

  <Card title="本番キー" icon="key">
    * `prod` 環境用に作成
    * 本番に使用
    * 実際の支払いを処理
    * 秘密鍵を安全に保管
  </Card>
</CardGroup>

### キータイプ

| キータイプ     | ユースケース    | 説明                |
| --------- | --------- | ----------------- |
| **APIキー** | サーバーサイドのみ | 署名リクエスト、フルAPIアクセス |

### APIキー認証

<Note>
  API Key 認証は SDK が自動的に処理します。`@waffo/pancake-ts` をインストールし、Merchant ID と秘密鍵を提供するだけで、SDK がリクエストの署名を自動的に行います。
</Note>

```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!,
});
```

<Warning>
  クライアントサイドコード、バージョン管理、パブリックリポジトリで秘密鍵を公開しないでください。
</Warning>

### APIキーの作成

<Steps>
  <Step title="開発者に移動">
    ダッシュボード → API と開発 → APIキー
  </Step>

  <Step title="「APIキーを作成」をクリック">
    APIキージェネレーターが開きます。
  </Step>

  <Step title="キーペアを生成">
    「生成」をクリックしてキーペアを作成。

    * 公開鍵がサーバーに送信されます
    * 秘密鍵はあなたが保管します
  </Step>

  <Step title="キーに名前を付ける">
    説明的な名前を付ける（例：「本番サーバー」）
  </Step>

  <Step title="環境を選択">
    **テスト**または**本番**環境を選択。
  </Step>

  <Step title="秘密鍵をダウンロード">
    **重要：** 秘密鍵をダウンロードして安全に保存。
  </Step>
</Steps>

<Warning>
  秘密鍵は一度だけ表示されます。安全に保存してください -- API認証に必要です。
</Warning>

### キーの管理

| アクション | 説明            |
| ----- | ------------- |
| 表示    | キー名、作成日、環境を確認 |
| 削除    | キーを永久に削除      |

## Webhooks

### Webhooksとは？

Webhooksは、Waffo Pancakeでイベントが発生したときにサーバーに通知します。

### 利用可能なイベント

| イベント                             | トリガー                |
| -------------------------------- | ------------------- |
| `order.completed`                | 注文完了                |
| `subscription.activated`         | サブスクリプション有効化        |
| `subscription.payment_succeeded` | サブスクリプション決済成功       |
| `subscription.updated`           | サブスクリプション更新         |
| `subscription.canceling`         | サブスクリプションのキャンセル予定   |
| `subscription.canceled`          | サブスクリプション終了         |
| `subscription.uncanceled`        | サブスクリプションのキャンセル取り消し |
| `subscription.past_due`          | サブスクリプション決済期限超過     |
| `refund.succeeded`               | 返金処理成功              |
| `refund.failed`                  | 返金処理失敗              |

### Webhooksのセットアップ

<Steps>
  <Step title="エンドポイントを追加">
    WebhookのURL（HTTPSが必須）を入力。
  </Step>

  <Step title="イベントを選択">
    受信したいイベントを選択。
  </Step>

  <Step title="設定を保存">
    Webhookエンドポイントを保存。
  </Step>
</Steps>

### Webhookペイロード例

```json theme={"system"}
{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 2900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}
```

<Note>
  すべてのIDはUUID v4形式です。金額は最小通貨単位です。タイムスタンプはISO 8601 UTC形式です。
</Note>

### Webhookベストプラクティス

<AccordionGroup>
  <Accordion title="素早くレスポンス">
    30秒以内に2xxステータスを返す。重い処理は非同期で行う。
  </Accordion>

  <Accordion title="重複を処理">
    イベントは複数回送信される可能性があります。イベントIDで重複排除。
  </Accordion>

  <Accordion title="リトライロジック">
    失敗したWebhooksは最大5回、遅延を増やしながらリトライされます（5分、30分、2時間、24時間）。
  </Accordion>

  <Accordion title="失敗を監視">
    ダッシュボードでWebhook配信ログを確認。
  </Accordion>
</AccordionGroup>

## APIドキュメント

### ベースURL

```
https://api.waffo.ai/v1
```

### アーキテクチャ

Waffo Pancake はハイブリッド API を使用します：

* **REST（POST）** -- `/v1/actions/...` 経由のすべての書き込み操作
* **GraphQL** -- `/v1/graphql` 経由のすべての読み取り操作

### 認証例

**SDK を使用した API キー認証（サーバー間通信）：**

```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!,
});

const { store } = await client.stores.create({ name: "My Store" });
```

### 一般的なエンドポイント

| エンドポイント                                           | メソッド | 説明                  |
| ------------------------------------------------- | ---- | ------------------- |
| `/v1/actions/onetime-product/create-product`      | POST | 単発プロダクトを作成          |
| `/v1/actions/subscription-product/create-product` | POST | サブスクリプションプロダクトを作成   |
| `/v1/actions/onetime-order/create-order`          | POST | チェックアウトセッションを作成     |
| `/v1/actions/subscription-order/create-order`     | POST | サブスクリプションチェックアウトを作成 |
| `/v1/graphql`                                     | POST | データをクエリ (GraphQL)   |

<Card title="完全なAPIリファレンス" icon="code" href="/ja/api-reference/introduction">
  リクエスト/レスポンス例を含む完全なエンドポイントドキュメント。
</Card>

## セキュリティベストプラクティス

<CardGroup cols={2}>
  <Card title="環境変数" icon="lock">
    秘密鍵はコードではなく環境変数に保存。
  </Card>

  <Card title="キーローテーション" icon="rotate">
    特にチーム変更後は定期的にキーをローテーション。
  </Card>

  <Card title="キー分離" icon="shield">
    テストと本番で異なるAPIキーを使用。
  </Card>

  <Card title="安全な保管" icon="vault">
    プラットフォームのシークレット管理を使用して秘密鍵を保管。
  </Card>
</CardGroup>

## テスト

### テストモード

開発にはテストモードを使用：

* すべてのエンドポイントが同じように動作
* 実際の課金は処理されない
* テストカード番号が利用可能
* フルWebhookテスト

### テストカード

| カード番号                 | 動作             |
| --------------------- | -------------- |
| `4576 7500 0000 0110` | 成功（Visa）       |
| `2226 9000 0000 0110` | 成功（Mastercard） |
| `4576 7500 0000 0220` | 拒否             |

## ログとデバッグ

### Webhookログ

Webhook配信を追跡：

* イベントタイプ
* 配信ステータス（成功/失敗）
* エンドポイントからのHTTPレスポンス
* リトライ回数とタイムスタンプ