# 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 クローラーが自動的にこれを発見できます。

## 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` を再取得して再プロンプトします