> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 連携ツール（waffo-integrate）

> AI コーディングツールで Waffo SDK 連携を自動化。手動連携より 33% 高速、成功率 100%。

waffo-integrate は Waffo 公式の AI 連携 Skill です。インタラクティブなウィザードを通じて、開発者の SDK 連携を自動的に完了させます。Claude Code や Cursor などの AI コーディングツールに対応しています。

<Note>
  本ページの「AI」は AI コーディングツールによる SDK 連携を指します。AI エージェントからのステーブルコイン決済を受け入れたい場合は、[x402 ステーブルコイン決済](/docs/ja/developer-docs/use-cases/x402-stablecoin-acquiring)を参照してください。
</Note>

## 連携ロードマップ

<Steps>
  <Step title="プロジェクトを準備する">
    Claude Code または Cursor でプロジェクトコードを開きます。
  </Step>

  <Step title="Skill をインストールする">
    `npx @waffo/waffo-integrate` を実行します。
  </Step>

  <Step title="Waffo 連携を起動する">
    AI アシスタントに Waffo 決済の連携を依頼します。
  </Step>

  <Step title="ビジネス要件に回答する">
    決済、返金、サブスクリプション、Webhook、加盟店設定照会、決済手段照会など、必要な機能を選択します。
  </Step>

  <Step title="コードを確認して生成する">
    AI ツールがコードをプレビューし、確認後に SDK 初期化、サービス、Webhook ハンドラー、テストを生成します。
  </Step>

  <Step title="検証を実行する">
    AI ツールが決済、返金、サブスクリプション、Webhook フローを対象に連携テストを実行します。
  </Step>

  <Step title="テストレポートを提出する">
    生成されたテストレポートを Waffo の技術連携グループへ送付して確認を受けます。
  </Step>
</Steps>

## waffo-integrate を利用する理由

| 指標      | Skill 利用時 | 手動連携  | 改善   |
| ------- | --------- | ----- | ---- |
| 連携成功率   | **100%**  | 75%   | +25% |
| 平均所要時間  | 128 秒     | 192 秒 | -33% |
| トークン使用量 | 58.8k     | 66.3k | -11% |

## インストール

<CodeGroup>
  ```bash 自動検出（推奨） theme={null}
  npx @waffo/waffo-integrate
  ```

  ```bash Claude Code theme={null}
  npx @waffo/waffo-integrate --claude
  # 或
  claude /install-skill waffo-com/waffo-integrate
  ```

  ```bash Cursor theme={null}
  npx @waffo/waffo-integrate --cursor
  ```
</CodeGroup>

## 連携フロー

<Steps>
  <Step title="Skill を起動する">
    AI アシスタントにトリガーフレーズを入力します：`集成 Waffo 支付`、`integrate waffo`、`接入waffo`、`waffo sdk`、または `waffo payment`。
  </Step>

  <Step title="言語検出">
    Skill がプロジェクト言語を自動検出します：`package.json` → Node.js、`pom.xml` / `build.gradle` → Java、`go.mod` → Go。
  </Step>

  <Step title="機能選択">
    必要な機能をインタラクティブに選択します（順番にプロンプト表示）：決済、返金、サブスクリプション、Webhook、加盟店設定照会、決済手段照会。スマート推奨：決済を選択すると返金の追加を提案。サブスクリプションを選択すると Webhook の追加を提案します。
  </Step>

  <Step title="フレームワーク選択（Webhook のみ）">
    | 言語      | 推奨フレームワーク   | その他の選択肢        |
    | ------- | ----------- | -------------- |
    | Node.js | Express     | NestJS、Fastify |
    | Java    | Spring Boot | —              |
    | Go      | Gin         | Echo、Fiber、Chi |
  </Step>

  <Step title="コードプレビューと生成">
    Skill はまず完全なコードをレビュー用に表示し、確認後に生成します：SDK 初期化、決済/返金/サブスクリプションサービス、Webhook 処理、テストファイル、`.env.example`。
  </Step>

  <Step title="連携検証（任意）">
    決済、返金、サブスクリプションの全フローを網羅する 15 件の受け入れテストを実行します。HTTP エンドポイントテスト + Playwright による自動 Checkout 操作 + データベース状態チェックを含みます。
  </Step>
</Steps>

検証完了後、生成されたテストレポートを自社と Waffo の技術連携グループ（WeCom または Lark グループなど）へ送付し、連携結果の確認を受けてください。

## 13 項目の組み込み API ルール

Skill に組み込まれたルールが、よくあるミスを自動的に防止します：

| #  | ルール                                                  | 防止される問題                           |
| -- | ---------------------------------------------------- | --------------------------------- |
| 1  | リクエスト ID の最大長は 32 文字                                 | Waffo の冪等キー長制限を超える値               |
| 2  | サブスクリプションは `orderCurrency` ではなく `currency` を使用       | フィールド名の混同                         |
| 3  | サブスクリプションは `orderAmount` ではなく `amount` を使用           | フィールド名の混同                         |
| 4  | 各操作の必須フィールドチェック                                      | `payMethodType`、`goodsInfo` などの欠落 |
| 5  | `periodType` は DAILY/WEEKLY/MONTHLY のみ               | 無効な列挙値 `YEARLY`、`MONTH`           |
| 6  | `periodInterval` は Number ではなく String                | 型エラー                              |
| 7  | サブスクリプションは `payMethodType` が必須                       | SDK エラー A0003                     |
| 8  | `productName` は ONE\_TIME\_PAYMENT / SUBSCRIPTION のみ | 無効な製品タイプ                          |
| 9  | `isSuccess()` でレスポンスをチェック                            | エラー処理の欠落                          |
| 10 | Webhook は署名検証 + レスポンス署名が必須                           | セキュリティ脆弱性                         |
| 11 | Java は `WaffoConfig.builder()` を使用                   | SDK 初期化失敗                         |
| 12 | タイムスタンプは SDK が自動注入                                   | 手動タイムスタンプ形式の誤り                    |
| 13 | merchantId は SDK が自動注入                               | 重複設定                              |

## 生成コードの特徴

* **エラー処理**：`WaffoUnknownStatusError`（成功している可能性あり）と `WaffoError`（クライアントエラー）を区別
* **セキュリティ**：Webhook の署名検証 + レスポンス署名、環境変数による認証情報管理
* **ベストプラクティス**：冪等性のあるリクエスト ID、サービス層の分離、JSON 解析前の Webhook 登録
* **テスト**：サンドボックス連携テストスタブ、テスト用カード番号

詳細なドキュメントは [waffo-integrate GitHub](https://github.com/waffo-com/waffo-integrate) を参照してください。