> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oblodai.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Подключите Oblodai к своему приложению за минуты с помощью Claude, ChatGPT, Cursor или Copilot: LLM-версии документации, MCP-сервер и готовые промпты.

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

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

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

| Endpoint                                                   | Назначение                                             |
| ---------------------------------------------------------- | ------------------------------------------------------ |
| [`/llms.txt`](https://docs.oblodai.com/llms.txt)           | Краткий индекс всей документации со ссылками           |
| [`/llms-full.txt`](https://docs.oblodai.com/llms-full.txt) | Вся документация одним файлом — для вставки в чат с AI |
| `/{страница}.md`                                           | Любая страница в сыром Markdown: добавьте `.md` к URL  |

Каждая HTML-страница содержит `<link rel="alternate" type="text/markdown">`, поэтому AI-краулеры
находят Markdown-версию сами. В меню каждой страницы есть «Copy page» и открытие прямо в
ChatGPT/Claude.

<Note>
  `llms-full.txt` — большой файл (около мегабайта). Для моделей с небольшим контекстом удобнее
  MCP-сервер ниже: ассистент подтянет только нужные страницы.
</Note>

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

Агенты с поддержкой Model Context Protocol подключаются напрямую:

```text theme={null}
https://docs.oblodai.com/mcp
```

Endpoint публичный, **только на чтение** и не требует ключа мерчанта. Он отдаёт исключительно
содержимое документации: через него **нельзя** проверить баланс, создать платёж или перевести
средства.

Конфигурация для MCP-клиента (транспорт — Streamable HTTP):

```json theme={null}
{
  "mcpServers": {
    "oblodai-docs": {
      "url": "https://docs.oblodai.com/mcp"
    }
  }
}
```

Инструменты сервера:

| Инструмент                      | Когда агенту его использовать                                        |
| ------------------------------- | -------------------------------------------------------------------- |
| `search_oblodai`                | Поиск по всей документации: фрагменты с прямыми ссылками на страницы |
| `query_docs_filesystem_oblodai` | Прочитать полную Markdown-версию конкретной страницы                 |
| `submit_feedback`               | Оставить отзыв о документации                                        |

<Warning>
  Документационный MCP — источник знаний, а не пульт управления кошельком. Не передавайте в
  аргументах инструментов API-ключи, секреты вебхуков и данные клиентов.
</Warning>

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

**Шаг 1 — передайте документацию.** Вставьте содержимое
[`llms-full.txt`](https://docs.oblodai.com/llms-full.txt) первым сообщением, или просто дайте
ссылку, если модель умеет ходить по URL, или подключите MCP-сервер.

**Шаг 2 — опишите свой стек:**

```text theme={null}
Я делаю приложение на Laravel 11. Мне нужно:
1. Создать платёж под заказ (сумма в USD, пользователь платит USDT TRC-20)
2. Обработать вебхук и зачислить баланс пользователю
3. Сохранять платежи в таблице payments

Используй API Oblodai из документации выше. Включи HMAC-подпись запросов,
проверку подписи вебхука и идемпотентную обработку.
```

**Шаг 3 — проверьте и протестируйте.** Перед запуском сгенерированного кода:

* подпись запроса — `hex(HMAC-SHA256(секрет, "<ts>\n<МЕТОД>\n<путь>\n<тело>"))`, склейка ровно
  переводами строк ([как подписать запрос](/guides/signing-requests));
* подпись вебхука сверяется **константным по времени** сравнением (`hash_equals`, `hmac.compare_digest`,
  `crypto.timingSafeEqual`) — никогда `==` ([безопасность вебхуков](/guides/webhooks-security));
* обработчик вебхука идемпотентен: дедуп по `uuid`+`status` до зачисления;
* прогоните всё в [песочнице](/guides/testing): dev-store с тестовыми деньгами, симуляцией депозитов
  (`POST /v1/sandbox/deposit`) и повтором вебхуков — реальные средства для проверки не нужны.

<Warning>
  Никогда не выпускайте сгенерированный AI код для платежей без ручного ревью логики подписи и
  проверки вебхуков. Это критические границы безопасности.
</Warning>

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

### Cursor

Добавьте документацию как источник docs: `Settings → Features → Docs → Add new doc` →
`https://docs.oblodai.com`. Затем в чате:

```text theme={null}
@Oblodai сгенерируй обработчик вебхука в Next.js App Router
с проверкой подписи и идемпотентным зачислением
```

### GitHub Copilot

Copilot Chat умеет читать `llms-full.txt` напрямую:

```text theme={null}
#fetch https://docs.oblodai.com/llms-full.txt

Используя документацию Oblodai выше, реализуй endpoint выплат в Express,
который выводит USDT TRC-20 на адрес пользователя.
```

### Windsurf / Continue / другие

Любой ассистент с контекстом по URL или вложением файла работает так же: приложите `llms-full.txt`
(или подключите MCP) и опишите задачу.

## Claude API (свой агент)

Если вы строите собственного агента, который должен помогать с интеграцией Oblodai — подключите
MCP-сервер документации или вставьте `llms-full.txt` в системный промпт:

```python theme={null}
from anthropic import Anthropic
import urllib.request

docs = urllib.request.urlopen(
    "https://docs.oblodai.com/llms-full.txt"
).read().decode()

client = Anthropic()
response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    system=f"Ты — ассистент интеграции Oblodai. Отвечай по справке ниже.\n\n<docs>\n{docs}\n</docs>",
    messages=[{"role": "user", "content": "Напиши функцию на Python, создающую счёт на 10 USDT"}],
)
print(response.content[0].text)
```

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

**Полная бэкенд-интеграция:**

```text theme={null}
Собери сервис на Node.js + Express с двумя роутами:
- POST /checkout → создаёт платёж Oblodai и возвращает url страницы оплаты
- POST /webhook/oblodai → проверяет подпись и помечает заказ оплаченным
TypeScript, Zod для валидации. Подпись запросов и вебхуков — по документации.
```

**Постоянные адреса пополнения (статические кошельки):**

```text theme={null}
У меня Django-приложение, пользователи пополняют баланс в USDT TRC-20.
У каждого пользователя должен быть постоянный адрес пополнения. Реализуй это
на статических кошельках Oblodai (POST /v1/wallet, order_id = id пользователя)
и напиши обработчик вебхука, зачисляющий баланс при депозите.
```

**Утилита выплат:**

```text theme={null}
Напиши CLI на Go: принимает валюту, сеть, сумму и адрес, создаёт выплату через
POST /v1/payout (ключ — из переменной окружения), затем опрашивает
POST /v1/payout/info до финального статуса.
```

## Лучшие практики

* **Начинайте с `llms-full.txt` или MCP** — там нет HTML-шума, только содержание.
* **Чётко описывайте стек** — фреймворк, версия языка, ORM.
* **Просите тесты** — AI хорошо генерирует unit-тесты для логики подписи.
* **Перепроверяйте ветки ошибок** — AI их иногда пропускает; сверьтесь с
  [каталогом ошибок](/reference/errors-catalog).
* **Код подписи ревьюйте руками** — это единственная часть, которую обязательно сделать точно.
* **Гоняйте в песочнице до прода** — dev-store покрывает весь цикл: платежи, недоплаты, выплаты,
  вебхуки ([тестирование](/guides/testing)).
* **API меняется — документация обновляется сама** (спека генерируется из кода), поэтому при
  повторном заходе просто перечитайте `llms-full.txt` заново.