# 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`가 재생성되므로 항상 최신 스키마를 받게 됨

## 기계 판독 가능한 문서

[llmstxt.org](https://llmstxt.org) 표준을 따르는 세 가지 endpoint를 제공합니다:

| Endpoint | 용도 |
|----------|---------|
| [`/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) | 임의의 페이지를 raw Markdown으로 |

모든 HTML 페이지는 `<link rel="alternate" type="text/markdown">`로 해당 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` | 한 페이지의 전체 휴대용 마크다운 버전을 읽으세요. |
| `get_integration_guide` | 호스팅 결제, H2H, 정확한 암호화폐 청구서, 고정 지갑, 자동 변환, 수동 변환 또는 출금에 대한 가이드 계획을 구축하세요. |

모든 도구 결과에는 구조화된 JSON과 사람이 읽을 수 있는 텍스트가 포함됩니다. 검색 결과는 `resource_link` 항목을 반환하므로 에이전트가 전체 말뭉치를 로드하지 않고 필요한 페이지만 가져올 수 있습니다.

### MCP 리소스

| 리소스 | 목적 |
|----------|---------|
| `docs://2328/index` | 기계가 읽을 수 있는 서비스 및 문서 색인. |
| `docs://2328/en/full` | 영어 통합 참조가 공유 코드 조각과 함께 확장되었습니다. |
| `docs://2328/{locale}/{slug}` | 하나의 현지화된 페이지; 누락된 번역은 영어로 대체됩니다. |

리소스 템플릿은 로케일 및 슬러그 완료를 지원하며, 이를 통해 호환 가능한 클라이언트가 추측 없이 유효한 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로 빠르게 시작

### 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` 검사
- 먼저 dev 환경에서 소액의 실제 결제로 테스트

> **WARNING:** 서명과 webhook 검증 로직을 검토하지 않은 채로 AI가 생성한 결제 코드를 배포하지 마세요. 이 영역은 가장 중요한 보안 경계입니다.

## IDE 통합

### Cursor

Cursor 설정에서 docs를 사용자 정의 문서 소스로 추가하세요:

```
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와 상호작용해야 하는 자체 에이전트나 챗봇을 만든다면, 시스템 프롬프트에 docs를 한 번 주입하세요:

```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:** 전체 docs 파일은 약 15 KB로 — 최신 모델의 context 한도에 비해 충분히 작습니다. 자체 측에서 캐싱하고 하루에 한 번 새로 받아오면 됩니다.

## 잘 작동하는 예시 프롬프트

`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 context용으로 설계되어 보일러플레이트가 없음
- **스택을 구체적으로 명시** — 프레임워크, 언어 버전, ORM
- **테스트 작성 요청** — AI는 서명 로직에 대한 단위 테스트 생성에 뛰어남
- **오류 처리 재확인** — AI는 실패 경로를 종종 누락함
- **서명 코드는 직접 검토** — 정확히 일치해야 *반드시* 작동하는 유일한 부분임
- **주기적으로 갱신** — API가 변경되면 `llms-full.txt`를 다시 받고 다시 프롬프트하세요