# Интеграция с 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-краулеры обнаруживали её автоматически.

## MCP-сервер документации

ИИ-агенты с поддержкой [Model Context Protocol](https://modelcontextprotocol.io) могут подключаться напрямую к адресу:

```
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` | Прочитать полную переносимую Markdown-версию одной страницы. |
| `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` предлагает проверить существующий код: подпись запросов, границы клиента и проекта, работу с десятичными числами, идемпотентность, порядок webhook-событий, неоднозначные тайм-ауты и пробелы в сверке.

### Рекомендуемый порядок работы агента

1. Вызовите `get_integration_guide` для выбранного сценария интеграции.
2. Прочитайте все связанные страницы через MCP-ресурсы или `get_doc`.
3. Используйте `search_docs` для вопросов о конкретной платформе и нестандартных ситуациях.
4. До вызовов платёжного API реализуйте подпись запросов и тесты обработки webhook.
5. Проверьте результат с помощью `review-2328-integration`.
6. Проведите небольшие реальные транзакции в контролируемой среде: доступ к документации через MCP не подтверждает доступность production API.

> **WARNING:** Документационный MCP — источник знаний по интеграции, а не интерфейс управления кошельком. Не передавайте в аргументах инструментов и промптах API-ключи, ключи выплат, секреты webhook, персональные данные клиентов или production-данные.

## Быстрый старт с 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` и повторяйте промпт