# Tích hợp với AI

> Tích hợp 2328.io vào ứng dụng của bạn trong vài phút bằng các trợ lý AI như Claude, ChatGPT, Cursor và GitHub Copilot.

Tài liệu 2328.io được xây dựng theo hướng **thân thiện với LLM**. Bạn có thể đưa toàn bộ tài liệu API cho bất kỳ trợ lý AI hiện đại nào và để nó tạo ra một bản tích hợp hoạt động được trong ngôn ngữ bạn chọn — PHP, Node.js, Python, Go, Rust — chỉ trong vài phút thay vì hàng giờ.

Trang này giải thích cách thực hiện hiệu quả.

## Vì sao nên dùng AI để tích hợp

- **Onboarding nhanh hơn** — bỏ qua phần boilerplate, đi thẳng vào logic nghiệp vụ
- **Ký yêu cầu chính xác** — AI tái tạo đáng tin cậy việc ký HMAC-SHA256 trong mọi ngôn ngữ
- **Webhook handlers** — sinh ra phần xác minh chữ ký và các handler idempotent ngay lập tức
- **Cập nhật mới nhất** — `llms-full.txt` của chúng tôi được tái tạo sau mỗi lần cập nhật tài liệu, vì vậy bạn luôn có schema hiện hành

## Tài liệu thân thiện với máy

Chúng tôi xuất bản ba endpoint theo chuẩn [llmstxt.org](https://llmstxt.org):

| Endpoint | Purpose |
|----------|---------|
| [`/llms.txt`](https://doc.2328.io/llms.txt) | Mục lục ngắn của toàn bộ tài liệu kèm liên kết |
| [`/llms-full.txt`](https://doc.2328.io/llms-full.txt) | Toàn bộ tài liệu trong một file duy nhất — dán vào chat AI của bạn |
| [`/md/{locale}/{slug}`](https://doc.2328.io/md/en/payments) | Bất kỳ trang nào ở dạng Markdown thuần |

Mọi trang HTML đều phơi bày `<link rel="alternate" type="text/markdown">` trỏ đến phiên bản Markdown, để các AI crawler tự khám phá.

## Bắt đầu nhanh với Claude hoặc ChatGPT

### Bước 1 — Cung cấp tài liệu

Mở một chat mới và dán nội dung của [`llms-full.txt`](https://doc.2328.io/llms-full.txt) làm tin nhắn đầu tiên, hoặc đơn giản chia sẻ link nếu mô hình có thể fetch nó.

### Bước 2 — Mô tả stack của bạn

Nói cho trợ lý biết bạn đang xây dựng gì:

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

### Bước 3 — Xem xét và kiểm thử

Trợ lý sẽ tạo ra một controller, một service class và một webhook handler. Trước khi triển khai:

- Kiểm tra rằng `apiSign()` mã hóa thân yêu cầu thành Base64 **trước** HMAC-SHA256
- Kiểm tra rằng các webhook handler gọi `hash_equals()` (không phải `===`) để so sánh chữ ký
- Đảm bảo handler là idempotent — kiểm tra `order_id` / `txid` trước khi ghi có
- Kiểm thử với một thanh toán thực nhỏ trên môi trường dev trước

> **WARNING:** Đừng bao giờ triển khai mã thanh toán do AI sinh ra mà chưa rà soát logic ký và xác minh webhook. Đây là những ranh giới bảo mật quan trọng.

## Tích hợp với IDE

### Cursor

Thêm tài liệu làm nguồn docs tùy biến trong cài đặt Cursor:

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

Sau đó trong chat, đặt tiền tố cho câu hỏi của bạn bằng `@2328.io`:

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

### GitHub Copilot

Copilot Chat có thể đọc trực tiếp `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 / các trợ lý khác

Bất kỳ trợ lý nào hỗ trợ context theo URL hoặc đính kèm file đều hoạt động theo cùng cách — đính kèm `llms-full.txt` và mô tả mục tiêu của bạn.

## Claude API (Agent SDK)

Nếu bạn đang xây dựng agent hoặc chatbot riêng cần tương tác với 2328.io, hãy nạp tài liệu một lần vào system prompt:

```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:** File tài liệu đầy đủ chỉ khoảng ~15 KB — thấp hơn rất nhiều so với giới hạn context của các mô hình hiện đại. Bạn có thể cache nó ở phía mình và làm mới một lần mỗi ngày.

## Các prompt mẫu hoạt động tốt

Sao chép những prompt này vào Claude, ChatGPT hoặc AI IDE của bạn sau khi đã chia sẻ `llms-full.txt`:

**Tích hợp backend đầy đủ:**
```
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.
```

**Công cụ rút tiền:**
```
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.
```

**Ví tĩnh cho việc nạp tiền của người dùng:**
```
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.
```

## Best practices cho tích hợp có hỗ trợ của AI

- **Bắt đầu từ `llms-full.txt`** — nó được thiết kế cho context LLM, không có boilerplate
- **Cụ thể về stack của bạn** — framework, phiên bản ngôn ngữ, ORM
- **Yêu cầu test** — AI rất giỏi sinh ra unit test cho logic ký
- **Kiểm tra kỹ phần xử lý lỗi** — AI đôi khi bỏ qua các nhánh thất bại
- **Rà soát mã chữ ký bằng tay** — đây là phần duy nhất *bắt buộc* phải chính xác
- **Refresh định kỳ** — nếu API của chúng tôi thay đổi, fetch lại `llms-full.txt` và prompt lại