# Інтеграція з 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` регенерується під час кожного оновлення документації, тож ви завжди отримуєте актуальні schema

## Машинно-читабельна документація

Ми публікуємо три endpoints за стандартом [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

AI-агенти, які підтримують [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}` | Одна локалізована сторінка; відсутні переклади повертаються англійською. |

Шаблон ресурсу підтримує завершення для локалі та 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()` кодує тіло у base64 **перед** HMAC-SHA256
- Перевірте, що обробники webhook викликають `hash_equals()` (а не `===`) для порівняння підписів
- Переконайтеся, що обробник є ідемпотентним — перевіряйте `order_id` / `txid` перед зарахуванням
- Спочатку протестуйте на dev-середовищі невеликим реальним платежем

> **WARNING:** Ніколи не запускайте у продакшн платіжний код, згенерований AI, без рев'ю логіки підписання та перевірки webhook. Це критичні межі безпеки.

## Інтеграції з 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, інжектуйте документацію один раз у системний 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:** Файл повної документації займає близько 15 КБ — значно менше, ніж ліміт контексту будь-якої сучасної моделі. Ви можете кешувати його у себе та оновлювати раз на добу.

## Приклади prompts, що добре працюють

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