# AI 統合

> Claude、ChatGPT、Cursor、GitHub Copilot などの AI アシスタントを使って、2328.io を数分でアプリケーションに統合します。

2328.io のドキュメントは **LLM フレンドリー** に作られています。最新の AI アシスタントに API リファレンス全体を渡すことで、PHP、Node.js、Python、Go、Rust など任意の言語で動作する統合コードを、数時間ではなく数分で生成させることができます。

このページでは、その効率的な進め方を説明します。

## なぜ AI を使って統合するのか

- **オンボーディングの高速化** — ボイラープレートをスキップし、ビジネスロジックに直行できます
- **正確な署名処理** — AI は任意の言語で HMAC-SHA256 署名を確実に再現します
- **Webhook ハンドラー** — 署名検証と冪等なハンドラーを最初から生成します
- **常に最新** — 私たちの `llms-full.txt` はドキュメント更新のたびに再生成されるため、常に最新のスキーマを得られます

## 機械可読なドキュメント

[llmstxt.org](https://llmstxt.org) 標準に準拠した 3 つのエンドポイントを公開しています：

| Endpoint | Purpose |
|----------|---------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | リンク付きの全ドキュメントの簡易インデックス |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | 単一ファイル形式の完全なドキュメント — これを AI チャットに貼り付けます |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | 任意のページを生の Markdown として取得 |

すべての HTML ページには、Markdown 版を指す `<link rel="alternate" type="text/markdown">` が出力されており、AI クローラーが自動的にこれを発見できます。

## MCPサーバーのドキュメント

[Model Context Protocol](https://modelcontextprotocol.io)をサポートするAIエージェントは、直接以下に接続できます:

```
https://doc.2328.io/mcp
```

エンドポイントは公開されており、読み取り専用で、マーチャントAPIキーは不要です。ドキュメントの知識のみを提供し、残高の確認、支払いの作成、資金の移動はできません。

一般的なリモートMCP設定:

```json
{
  "mcpServers": {
    "2328-docs": {
      "url": "https://doc.2328.io/mcp"
    }
  }
}
```

正確な設定構文はMCPクライアントによって異なります。Streamable HTTPを使用し、クライアントを上記のURLに向けてください。

### MCPツール

| ツール | エージェントが使用すべき場合 |
|------|------------------------------|
| `list_docs` | すべてのドキュメントトピックとリソースURIを発見します。 |
| `search_docs` | セクションレベルの回答を、ランク付けされた抜粋および直接リソースリンクとともに見つけます。 |
| `get_doc` | 1ページ分の完全なポータブルMarkdown版を読んでください。 |
| `get_integration_guide` | ホスト型チェックアウト、H2H、正確な暗号通貨請求書、静的ウォレット、自動変換、手動変換、または支払いのためのガイド付きプランを構築します。 |

すべてのツール結果には、構造化されたJSONと人間が読みやすいテキストが含まれます。検索結果は`resource_link`項目を返すため、エージェントは全文コーパスを読み込む代わりに必要なページだけを取得できます。

### MCPリソース

| リソース | 目的 |
|----------|---------|
| `docs://2328/index` | 機械可読のサービスおよび文書インデックス。 |
| `docs://2328/en/full` | 英語統合リファレンスの完全版、共有コードスニペットを拡張。 |
| `docs://2328/{locale}/{slug}` | ローカライズされたページ1件；翻訳がない場合は英語にフォールバック。 |

リソーステンプレートはロケールとスラッグの補完をサポートしており、互換性のあるクライアントが有効なURIを推測せずに発見できる。

### MCPプロンプト

- `integrate-2328` はエージェントに正しいガイドを読み、実装コード、テスト、設定、運用開始チェックリストを作成させる。
- `review-2328-integration` はエージェントに既存のコードを確認させ、署名、テナント／プロジェクトスコープ、小数処理、冪等性、ウェブフック順序、あいまいなタイムアウト、および照合ギャップをレビューさせる。

### 推奨エージェントワークフロー

1. 選択した統合パターンには `get_integration_guide` を使用してください。
2. MCP リソースまたは `get_doc` にリンクされたすべてのページを読みます。
3. フレームワーク固有または特殊ケースの質問には `search_docs` を使用してください。
4. API 呼び出しの前に署名とウェブフックのテストを実施してください。
5. 結果を `review-2328-integration` で確認してください。
6. 制御された環境で小さな実際の取引をテストしてください。MCP ドキュメントへのアクセスは、本番 API 接続を証明するものではありません。

> **WARNING:** MCP のドキュメントは統合知識のソースであり、ウォレット MCP ではありません。API キー、支払いキー、ウェブフックのシークレット、顧客の個人データ、本番ペイロードをツールの引数やプロンプトに貼り付けないでください。

## Claude または ChatGPT でのクイックスタート

### Step 1 — ドキュメントを提供する

新しいチャットを開き、[`llms-full.txt`](https://doc.2328.io/llms-full.txt) の内容を最初のメッセージとして貼り付けるか、モデルが取得可能であればリンクを共有するだけでも構いません。

### Step 2 — 自分のスタックを伝える

何を構築しているのかをアシスタントに伝えます：

```
I'm building a Laravel 11 application. I need to:
1. Create a payment for an order (amount in USD, user pays in USDT TRC20)
2. Handle the webhook and credit the user's balance
3. Store payment records in a `payments` table

Use the 2328.io API above. Include HMAC signing, webhook signature
verification, and idempotency.
```

### Step 3 — レビューとテスト

アシスタントはコントローラー、サービスクラス、Webhook ハンドラーを生成します。出荷前に以下を確認してください：

- `apiSign()` が HMAC-SHA256 の **前に** ボディを Base64 エンコードしていることを確認する
- Webhook ハンドラーが署名比較に `===` ではなく `hash_equals()` を使用していることを確認する
- ハンドラーが冪等であることを確認する — クレジット前に `order_id` / `txid` をチェックする
- まず開発環境で少額の実支払いをテストする

> **WARNING:** 署名と Webhook 検証ロジックをレビューせずに、AI が生成した決済コードを絶対に出荷しないでください。これらは重要なセキュリティ境界です。

## IDE 統合

### Cursor

Cursor 設定でドキュメントをカスタムドキュメントソースとして追加します：

```
Settings → Features → Docs → Add new doc
URL: https://doc.2328.io
```

その後、チャットで質問の先頭に `@2328.io` を付けます：

```
@2328.io generate a webhook handler in Next.js App Router
with signature verification and idempotent credit logic
```

### GitHub Copilot

Copilot Chat は `llms-full.txt` を直接読み取れます：

```
#fetch https://doc.2328.io/llms-full.txt

Using the 2328.io API docs above, implement a payout endpoint
in Express that withdraws USDT BEP20 to a user-supplied address.
```

### Windsurf / Continue / その他のアシスタント

URL コンテキストやファイル添付に対応するアシスタントであれば、同じ方法で動作します — `llms-full.txt` を添付して目的を伝えてください。

## Claude API（Agent SDK）

2328.io と対話する独自のエージェントやチャットボットを構築する場合、ドキュメントをシステムプロンプトに一度だけ注入します：

```python
from anthropic import Anthropic
import urllib.request

docs = urllib.request.urlopen(
    "https://doc.2328.io/llms-full.txt"
).read().decode()

client = Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    system=f"""You are an integration assistant for 2328.io.
Use the API reference below to answer questions and generate code.

<docs>
{docs}
</docs>""",
    messages=[
        {"role": "user", "content": "Write a Python function that creates a USDT payment"}
    ],
)

print(response.content[0].text)
```

> **INFO:** 完全版ドキュメントファイルは約 15 KB で、最新モデルのコンテキスト制限を大きく下回ります。自分の側でキャッシュし、1 日 1 回更新する運用が可能です。

## うまく機能するプロンプト例

`llms-full.txt` を共有した後、Claude、ChatGPT、または AI IDE に次のプロンプトをコピーしてください：

**バックエンドの完全統合:**
```
Build a Node.js + Express service that exposes two routes:
- POST /checkout → creates a 2328.io payment and returns the payment URL
- POST /webhook/2328 → verifies the signature and marks the order as paid
Use TypeScript, Zod for validation, and a simple in-memory store.
```

**出金ツール:**
```
Write a CLI in Go that takes a currency, network, amount, and address
and creates a payout via the 2328.io Payout API. Use a separate payout
API key from env. Poll the status endpoint until the payout is completed.
```

**ユーザー入金用の固定ウォレット:**
```
I have a Django app where users deposit USDT TRC20 to top up their balance.
Each user should have a permanent deposit address. Implement this using
2328.io static wallets, including the webhook handler that credits their
balance when a deposit arrives.
```

## AI 支援統合のベストプラクティス

- **`llms-full.txt` から始める** — LLM コンテキスト用に設計されており、ボイラープレートがありません
- **スタックを具体的に伝える** — フレームワーク、言語のバージョン、ORM
- **テストを依頼する** — AI は署名ロジックのユニットテスト生成が得意です
- **エラーハンドリングを再確認する** — AI は失敗パスを省略することがあります
- **署名コードを手動でレビューする** — 唯一 *正確に* 動作しなければならない部分です
- **定期的にリフレッシュする** — API が変更されたら、`llms-full.txt` を再取得して再プロンプトします