> ## 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 + роль | Управление через веб-кабинет       |

<CardGroup cols={3}>
  <Card title="710" icon="route">
    Эндпоинтов
  </Card>

  <Card title="898" icon="code">
    Pydantic-схем
  </Card>

  <Card title="85" icon="tags">
    Групп (тегов)
  </Card>
</CardGroup>

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

| Область       | Эндпоинтов | Групп | Описание                                      |
| ------------- | ---------- | ----- | --------------------------------------------- |
| 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) с нужными разрешениями.

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

<Steps>
  <Step title="Health Check">
    ```bash theme={null}
    curl https://your-domain.com/health
    ```

    Ответ: `{"status": "ok"}`
  </Step>

  <Step title="Получить список пользователей">
    ```bash theme={null}
    curl -H "X-API-Key: YOUR_TOKEN" \
      "https://your-domain.com/users?page=1&per_page=20"
    ```
  </Step>

  <Step title="Создать подписку">
    ```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
    ```
  </Step>
</Steps>

## WebSocket

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

| Путь                    | Авторизация | Назначение           |
| ----------------------- | ----------- | -------------------- |
| `/ws?token=API_KEY`     | API Key     | Дашборд админ-панели |
| `/cabinet/ws?token=JWT` | JWT         | Уведомления Cabinet  |

## Web API — группы

<AccordionGroup>
  <Accordion title="Пользователи и подписки">
    | Группа          | Описание                     |
    | --------------- | ---------------------------- |
    | `users`         | Управление пользователями    |
    | `subscriptions` | Подписки и ключи подключения |
    | `transactions`  | Финансовые операции          |
    | `partners`      | Партнёрская программа        |
  </Accordion>

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

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

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

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

## Cabinet API — группы

<AccordionGroup>
  <Accordion title="Пользовательский кабинет (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`                  | Вывод партнёрских средств            |
  </Accordion>

  <Accordion title="Админ-панель (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) |
    | `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`                                              | Конструктор меню               |
  </Accordion>
</AccordionGroup>

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

При включённом `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`
</Warning>