# Интеграция с AI

> Интегрируйте 2328.io в своё приложение за минуты с помощью AI-ассистентов вроде Claude, ChatGPT, Cursor и GitHub Copilot.

Документация 2328.io создана **дружественной к LLM**. Вы можете передать всю API-справку любому современному AI-ассистенту и получить рабочую интеграцию на любом языке — PHP, Node.js, Python, Go, Rust — за минуты, а не часы.

На этой странице рассказано, как сделать это эффективно.

## Зачем использовать AI для интеграции

- **Быстрый старт** — пропустите шаблонный код и сразу переходите к бизнес-логике
- **Корректная подпись** — AI надёжно воспроизводит подпись HMAC-SHA256 на любом языке
- **Обработчики webhook'ов** — генерация проверки подписи и идемпотентных обработчиков «из коробки»
- **Актуальность** — наш `llms-full.txt` пересоздаётся при каждом обновлении документации, поэтому вы всегда получаете актуальные схемы

## Машиночитаемая документация

Мы публикуем три endpoint'а по стандарту [llmstxt.org](https://llmstxt.org):

| 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) | Любая страница в виде сырого Markdown |

Каждая HTML-страница также содержит `<link rel="alternate" type="text/markdown">`, указывающий на её Markdown-версию, чтобы AI-краулеры обнаруживали её автоматически.

## Быстрый старт с Claude или ChatGPT

### Шаг 1 — Передайте документацию

Откройте новый чат и вставьте содержимое [`llms-full.txt`](https://doc.2328.io/llms-full.txt) первым сообщением — или просто поделитесь ссылкой, если модель умеет её получать.

### Шаг 2 — Опишите свой стек

Расскажите ассистенту, что вы строите:

```
Я делаю приложение на Laravel 11. Мне нужно:
1. Создать платёж под заказ (сумма в USD, пользователь платит USDT TRC20)
2. Обработать webhook и зачислить баланс пользователю
3. Сохранить записи о платежах в таблице `payments`

Используй API 2328.io выше. Включи подпись HMAC, проверку
подписи webhook'а и идемпотентность.
```

### Шаг 3 — Проверьте и протестируйте

Ассистент сгенерирует контроллер, сервис-класс и обработчик webhook'а. Перед запуском:

- Убедитесь, что `apiSign()` кодирует тело в Base64 **до** HMAC-SHA256
- Проверьте, что обработчики webhook'ов используют `hash_equals()` (а не `===`) для сравнения подписей
- Убедитесь, что обработчик идемпотентен — проверяйте `order_id` / `txid` перед зачислением
- Сначала протестируйте небольшой реальный платёж в dev-окружении

> **WARNING:** Никогда не выпускайте сгенерированный AI код для платежей без ревью логики подписи и проверки webhook'ов. Это критические границы безопасности.

## Интеграции с IDE

### Cursor

Добавьте документацию как пользовательский источник docs в настройках 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 КБ, что укладывается в контекстное окно любой современной модели. Можно кэшировать его на своей стороне и обновлять раз в день.

## Промпты, которые работают хорошо

Скопируйте их в Claude, ChatGPT или ваш AI-IDE после того, как поделитесь `llms-full.txt`:

**Полная бэкенд-интеграция:**
```
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 хорошо генерирует unit-тесты для логики подписи
- **Перепроверяйте обработку ошибок** — AI иногда пропускает ветки с ошибками
- **Вручную ревьюйте код подписи** — это единственная часть, которую *обязательно* нужно сделать точно
- **Периодически обновляйте** — если наш API меняется, перезагружайте `llms-full.txt` и повторяйте промпт