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

# Обзор API

> Полное REST API бота Bedolaga — 710 эндпоинтов, 898 схем данных, 85 групп

## Архитектура

Bedolaga предоставляет единый FastAPI-сервер на порту `8080` с тремя областями API:

| Область | Префикс | Авторизация | Назначение |
| - | - | - | - |
| **Web API** | `/` | `X-API-Key` | Программное администрирование бота |
| **Cabinet API** | `/cabinet/*` | JWT Bearer | Личный кабинет пользователя |
| **Cabinet Admin API** | `/cabinet/admin/*` | JWT Bearer + роль | Управление через веб-кабинет |

> **710**
>
> Эндпоинтов

> **898**
>
> Pydantic-схем

> **85**
>
> Групп (тегов)

### По областям

| Область | Эндпоинтов | Групп | Описание |
| - | - | - | - |
| Web API | 277 | 32 | Управление ботом, рассылки, подписки, серверы |
| Cabinet User | 146 | 21 | Подписки, платежи, рефералы, поддержка |
| Cabinet Admin | 287 | 33 | Пользователи, тарифы, RemnaWave, RBAC |

## Авторизация

### Web API — API Key

Все эндпоинты Web API требуют ключ в заголовке:

```bash theme={null}
curl -H "X-API-Key: YOUR_TOKEN" https://your-domain.com/users
```

Ключ создаётся через админ-панель бота или через API: `POST /tokens`.

### Cabinet API — JWT

Cabinet использует JWT-токены (HS256):

```bash theme={null}
curl -H "Authorization: Bearer ACCESS_TOKEN" https://your-domain.com/cabinet/subscription
```

Получение токена:

| Способ | Эндпоинт | Описание |
| - | - | - |
| Telegram WebApp | `POST /cabinet/auth/telegram` | Передать `initData` |
| Telegram Widget | `POST /cabinet/auth/telegram/widget` | Данные виджета |
| Email | `POST /cabinet/auth/email/login` | Email + пароль |
| OAuth 2.0 | `GET /cabinet/auth/oauth/{provider}` | Google, Яндекс, Discord, VK |
| Telegram OIDC | `POST /cabinet/auth/telegram/oidc` | Telegram OIDC авторизация |

Обновление: `POST /cabinet/auth/refresh` с refresh-токеном.

### Cabinet Admin API

Те же JWT-токены, но пользователь должен быть администратором (`ADMIN_IDS` / `ADMIN_EMAILS`) или иметь назначенную [роль RBAC](/cabinet/rbac.md) с нужными разрешениями.

## Быстрый старт

**1. Health Check**

```bash theme={null}
curl https://your-domain.com/health
```

Ответ: `{"status": "ok"}`

**2. Получить список пользователей**

```bash theme={null}
curl -H "X-API-Key: YOUR_TOKEN" \
  "https://your-domain.com/users?page=1&per_page=20"
```

**3. Создать подписку**

```bash theme={null}
curl -X POST -H "X-API-Key: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 123, "period_days": 30, "traffic_limit_gb": 100}' \
  https://your-domain.com/subscriptions
```

## WebSocket

Два WebSocket-эндпоинта для real-time обновлений:

| Путь | Авторизация | Назначение |
| - | - | - |
| `/ws?token=API_KEY` | API Key | Дашборд админ-панели |
| `/cabinet/ws?token=JWT` | JWT | Уведомления Cabinet |
| Мобильная поддержка | JWT или Telegram `initData` | Живая переписка в тикетах, субпротокол `bedolaga.support.mobile.v1` |

> [!NOTE]
>
> По вебсокету кабинета приходят и события рекуррентных СБП-подписок Platega (`sbp_recurring.*`), и события тикетов (`ticket.created`, `ticket.status_changed`, `message.created`).

## Web API — группы

> **Пользователи и подписки**
>
> | Группа | Описание |
> | - | - |
> | `users` | Управление пользователями, включая ручное пополнение баланса |
> | `subscriptions` | Подписки и ключи подключения |
> | `transactions` | Финансовые операции |
> | `partners` | Партнёрская программа |
>
> **Ручное пополнение** (`v3.67.0`): `POST /users/{id}/deposit` начисляет сумму на баланс и проводит её через весь пост-топап конвейер — уведомления, автопокупку из корзины, реферальные бонусы. Операция идемпотентна по внешнему ключу, повтор с тем же ключом деньги не удваивает.
>
> Потолок одной операции задаётся `WEB_API_MANUAL_DEPOSIT_MAX_KOPEKS` (по умолчанию 10 000 ₽, `0` — без ограничения). Эндпоинт рассчитан на автоматизацию — например, на AI-агента поддержки, — и лимит служит предохранителем от ошибки на два порядка.

> **Контент и рассылки**
>
> | Группа | Описание |
> | - | - |
> | `broadcasts` | Массовые рассылки |
> | `pages` | Информационные страницы |
> | `welcome-texts` | Приветственные сообщения |
> | `main-menu` | Настройки главного меню |
> | `menu-layout` | Конструктор расположения кнопок меню |
> | `pinned-messages` | Закреплённые сообщения |
> | `notifications` | Системные уведомления |

> **Маркетинг**
>
> | Группа | Описание |
> | - | - |
> | `promo-codes` | Промокоды |
> | `promo-groups` | Промо-группы (периодические скидки) |
> | `promo-offers` | Рекламные предложения |
> | `campaigns` | Рекламные кампании с трекингом |
> | `contests` | Конкурсы и розыгрыши |
> | `polls` | Опросы |

> **Инфраструктура**
>
> | Группа | Описание |
> | - | - |
> | `remnawave` | RemnaWave API (ноды, сквады, инбаунды) |
> | `servers` | Управление серверами |
> | `settings` | Настройки бота |
> | `backups` | Резервные копии |
> | `stats` | Статистика |
> | `logs` | Логи ошибок |
> | `health` | Проверки состояния |

> **Интеграции**
>
> | Группа | Описание |
> | - | - |
> | `webhooks` | Webhook-обработчики платёжных систем |
> | `miniapp` | Telegram Mini App API |
> | `media` | Загрузка и хранение файлов |
> | `auth` | Аутентификация Web API |
> | `support` | Система тикетов |
> | `ban-notifications` | Уведомления о банах |
> | `Landing Pages` | Публичные лендинги для привлечения клиентов |

## Cabinet API — группы

> **Пользовательский кабинет (146 эндпоинтов)**
>
> | Группа | Описание |
> | - | - |
> | `Cabinet Auth` | Авторизация (Telegram, email, OAuth) |
> | `Cabinet OAuth` | OAuth 2.0 провайдеры |
> | `Cabinet Subscription` | Подписки, тарифы, ключи |
> | `Cabinet Balance` | Баланс и пополнение |
> | `Cabinet Referral` | Реферальная программа |
> | `Cabinet Tickets` | Тикеты поддержки |
> | `Cabinet Notifications` | Уведомления |
> | `Cabinet Promo` / `Cabinet Promocode` | Промокоды |
> | `Cabinet Contests` / `Cabinet Polls` | Конкурсы и опросы |
> | `Fortune Wheel` | Колесо фортуны |
> | `Cabinet Info` | Информация о сервисе |
> | `Branding` | Брендирование и оформление |
> | `Cabinet Account Linking` | Привязка и отвязка аккаунтов |
> | `Cabinet Account Merge` | Объединение аккаунтов |
> | `Cabinet Gift` | Подарочные подписки |
> | `Cabinet Withdrawal` | Вывод партнёрских средств |

> **Админ-панель (287 эндпоинтов)**
>
> | Группа | Описание |
> | - | - |
> | `Cabinet Admin Users` | Управление пользователями |
> | `Cabinet Admin Tariffs` | Тарифы |
> | `Cabinet Admin Servers` | Серверы |
> | `Cabinet Admin RemnaWave` | RemnaWave интеграция |
> | `Cabinet Admin Broadcasts` | Рассылки |
> | `Cabinet Admin Payments` | Платежи |
> | `Cabinet Admin Payment Methods` | Способы оплаты |
> | `Cabinet Admin Tickets` | Тикеты поддержки |
> | `Cabinet Admin Ban System` | Система банов |
> | `Cabinet Admin Campaigns` | Рекламные кампании |
> | `Cabinet Admin Channels` | Обязательные каналы |
> | `Cabinet Admin Partners` | Партнёры |
> | `Cabinet Admin Withdrawals` | Выводы средств |
> | `Cabinet Admin Pinned Messages` | Закреплённые сообщения |
> | `Cabinet Admin Apps` | VPN-приложения |
> | `Cabinet Admin Stats` | Статистика и аналитика |
> | `Admin RBAC` / `Admin RBAC Policies` / `Admin RBAC Audit Log` | [Роли и доступ](/cabinet/rbac.md) |
> | `Admin Settings` | Настройки |
> | `Admin Traffic` | Мониторинг трафика |
> | `Admin Fortune Wheel` | Колесо фортуны |
> | `Admin Email Templates` | Email-шаблоны |
> | `Admin Promo Groups` / `Admin Promo Offers` / `Admin Promocodes` | Маркетинг |
> | `Admin Button Styles` | Стили кнопок |
> | `Cabinet Admin Updates` | Проверка обновлений |
> | `Cabinet Admin Landings` | Управление лендингами |
> | `Cabinet Admin Referral Network` | Граф реферальной сети |
> | `Cabinet Admin Sales Stats` | Статистика продаж |
> | `Admin Menu Layout` | Конструктор меню |

## Документация на сервере

При включённом `IS_DOCS_ENABLED=true` доступны:

* **Swagger UI**: `https://your-domain.com/docs`
* **ReDoc**: `https://your-domain.com/redoc`
* **OpenAPI JSON**: `https://your-domain.com/openapi.json`

> [!WARNING]
>
> В продакшене рекомендуется отключить документацию: `IS_DOCS_ENABLED=false`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.