# AI 集成

> 使用 Claude、ChatGPT、Cursor 和 GitHub Copilot 等 AI 助手，几分钟内将 2328.io 集成到您的应用程序中。

2328.io 文档专为 **LLM 友好** 而设计。您可以将整个 API 参考文档交给任何现代 AI 助手，让它在几分钟内（而非数小时）以您选择的语言生成可运行的集成代码 — 包括 PHP、Node.js、Python、Go、Rust。

本页介绍如何高效完成此操作。

## 为什么使用 AI 进行集成

- **更快上手** — 跳过样板代码，直接进入业务逻辑
- **正确的签名** — AI 能够可靠地以任何语言重现 HMAC-SHA256 签名
- **Webhook 处理器** — 开箱即用地生成签名验证和幂等处理器
- **始终最新** — 我们的 `llms-full.txt` 在每次文档更新时都会重新生成，因此您始终能获取当前的 schema

## 机器可读文档

我们按照 [llmstxt.org](https://llmstxt.org) 标准发布三个端点：

| 端点 | 用途 |
|------|------|
| [`/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 页面还会暴露 `<link rel="alternate" type="text/markdown">` 指向其 Markdown 版本，因此 AI 爬虫可以自动发现。

## 使用 Claude 或 ChatGPT 快速开始

### 第 1 步 — 提供文档

打开一个新的对话，将 [`llms-full.txt`](https://doc.2328.io/llms-full.txt) 的内容作为第一条消息粘贴；如果模型可以抓取链接，也可以直接分享链接。

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

### 第 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 交互的 agent 或聊天机器人，请将文档一次性注入到系统提示中：

```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 — 远低于任何现代模型的上下文限制。您可以在自己一侧缓存它，并每天刷新一次。

## 效果良好的示例提示

在分享 `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` 并重新提示