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

# API оформления подписок

> Интеграция бота, биллинга и поддержки: персональные настройки, темы, объявления и правила выдачи Flow.

API управляет оформлением существующих подписок Remnawave. Изменения доставляются при обновлении подписки через gateway Axottle. API не создаёт тарифы, не изменяет лимиты трафика и не выдаёт доступ к чужим профилям.

Во вкладке **Страница подписок → API** показаны пути для выбранного подключения.

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

Нужен отдельный Bearer-токен интеграции `axt_…`. Cookie-сессия панели, ссылка подписки и внутренний ключ страницы `axsp_…` для этого API не подходят.

Администратор с `settings.manage` создаёт токен через `POST /api/v1/internal-tokens`, используя административную авторизацию панели. Пример тела запроса:

```json theme={null}
{
  "name": "Биллинг: оформление подписок",
  "scopes": ["subscriptions:CONNECTION_ID:write"],
  "allowed_ips": []
}
```

Замените `CONNECTION_ID` идентификатором нужного подключения. Секрет возвращается один раз в поле `token`, идентификатор токена — в `token_info.id`. Храните секрет на сервере интеграции, не в клиентском приложении.

| Область | Доступ |
| - | - |
| `subscriptions:CONNECTION_ID:read` | Чтение оформления, каталогов и предпросмотр |
| `subscriptions:CONNECTION_ID:write` | Чтение, изменение и сброс настроек, управление объявлениями подключения |
| `subscription-flows:FLOW_ID:read` | Чтение правила выдачи конкретного Flow и истории |
| `subscription-flows:FLOW_ID:write` | Чтение и изменение выдачи конкретного Flow |

Общий scope `*` не открывает этот API. Права подключения не дают права менять Flow. Право Flow распространяется на все его опубликованные профили, включая другие подключения.

`allowed_ips` ограничивает IP/CIDR непосредственного сетевого клиента Axottle. За reverse proxy это адрес прокси, а не значение клиентского `X-Forwarded-For`. Пустой список не ограничивает источник по IP.

## Пользователи и каталоги

Базовый путь: `/api/subscriptions/v1/connections/CONNECTION_ID`.

| Метод | Путь относительно базового | Результат |
| - | - | - |
| GET | `/users?q=NAME_OR_UUID` | До 50 пользователей последней синхронизации |
| GET | `/users/USER_UUID` | Сохранённые персональные настройки |
| PATCH | `/users/USER_UUID` | Частичное изменение; пропущенные поля сохраняются |
| PUT | `/users/USER_UUID` | Полная замена; пропущенные поля сбрасываются |
| DELETE | `/users/USER_UUID` | Сброс персональных настроек, ответ 204 |
| POST | `/users/USER_UUID/preview` | Предпросмотр без сохранения |
| GET | `/themes` и `/themes/SLUG` | Каталог тем и профиль цветов |
| GET | `/audiences` | Internal squads из Remnawave |
| GET | `/flows` | Опубликованные Flow подключения |

`USER_UUID` — UUID аккаунта Remnawave, а не Telegram ID и не токен ссылки подписки. Чтение отдельного пользователя, запись и предпросмотр проверяют его в Remnawave. Ответ не раскрывает исходную ссылку или ключи конфигураций.

Основные поля настроек:

| Поля | Значения |
| - | - |
| `title` | До 25 символов; пусто — название исходной подписки |
| `theme` | Slug из каталога, `resetcolors` или пустая строка |
| `announcement_mode` | `inherit` или `custom` |
| `description`, `announcement` | До 200 символов каждое |
| `announcement_until` | RFC3339 с часовым поясом или `null` |
| `support_notice`, `route_notice` | Boolean: сообщения поддержки и изменений подключений |
| `support_url` | Публичная HTTPS-ссылка без логина и пароля либо пустая строка |
| `routes_mode` | `inherit`, `prefer` или `only` |
| `flow_ids` | До 32 уникальных Flow ID и не более 32 публичных профилей суммарно; для `prefer` и `only` выбор непустой |

Неизвестные поля отклоняются. PATCH требует хотя бы одно поле. PUT с пустым объектом сбрасывает все персональные настройки.

Пример изменения темы и личного объявления; переменные задаются на сервере интеграции:

```bash theme={null}
curl --request PATCH \
  "$AXOTTLE_URL/api/subscriptions/v1/connections/$CONNECTION_ID/users/$USER_UUID" \
  --header "Authorization: Bearer $SUBSCRIPTIONS_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"theme":"ocean","announcement_mode":"custom","announcement":"Вам ответили в поддержке"}'
```

Предпросмотр принимает **полный черновик** `settings`, а не частичный PATCH:

```json theme={null}
{
  "settings": {
    "title": "Axottle",
    "theme": "ocean",
    "announcement_mode": "custom",
    "description": "Ваша подписка"
  },
  "user_agent": "Happ/3 iOS"
}
```

Результат содержит заголовки, применимость темы, выбранное сообщение, совпадения аудиторий и состояние выбора Flow. Реальное пересечение с доступными профилями выполняется при выдаче подписки.

## Объявления

Используйте `GET /announcements`, `PUT /announcements/RULE_ID` и `DELETE /announcements/RULE_ID?version=N` относительно пути подключения.

PUT принимает полное правило. Для создания передайте `version: 0`; для изменения получите текущую версию через GET. Обязательны название до 80 символов и текст до 200. Аудитории: `all`, `squad`, `user`; для двух последних задайте `targets` — от 1 до 32 идентификаторов. Доступны исключения `excluded_users`, приоритет 0–100, `starts_at` / `ends_at`, платформа `any` / `ios` / `android` / `desktop` и точный `tag`.

Устаревшая версия при PUT возвращает 400, при DELETE — 409. Перечитайте правило и объедините изменения; автоматическая перезапись может потерять правку оператора. До 100 правил на подключение. [Приоритет сообщений](https://docs.axottle.com/ru/subscription-page/announcements.md#как-выбирается-сообщение) совпадает с интерфейсом панели.

## Выдача Flow

| Метод | Путь |
| - | - |
| GET / PUT | `/api/subscriptions/v1/flows/FLOW_ID/subscription` |
| GET | `/api/subscriptions/v1/flows/FLOW_ID/subscription/history` |

GET возвращает `rule`, связанные `nodes`, `profiles` и сведения о старых правилах `legacy_rules`. Измените нужные поля полученного `rule` и передайте **полное правило с его version** через PUT. Для новой записи версия равна 0; устаревшая версия отклоняется с 400. Состояние исключения вычисляет сервер.

Правило включает режим `drain_mode` (`off`, `manual`, `auto`), доступность `health_enabled`, источник нагрузки `node_id`, пороги, минимальную длительность исключения `hold_seconds`, оформление и обслуживание. История возвращает до 50 событий за 30 дней. Для записи требуется отдельный scope Flow и доступная возможность ConnectionUnits. [Назначение настроек](https://docs.axottle.com/ru/subscription-page/presentation.md#общая-выдача-flow).

## Ошибки

| Код | Причина |
| - | - |
| 400 | Неверные поля, выбор или версия правила |
| 401 | Нет токена, он неверен или отозван |
| 403 | Недостаточная область доступа или ограничение IP |
| 404 | Запрашиваемый ресурс не найден |
| 409 | Конфликт версии при удалении объявления |
| 502 | Не удалось подтвердить аккаунт в Remnawave |

Тело ошибки имеет поле `error`. Получение ошибки не следует считать успешным сохранением.

## Проверка

Начните с чтения каталога и настроек тестового пользователя. Выполните предпросмотр, затем PATCH одного поля и повторное чтение. Обновите подписку в поддерживаемом приложении. Отдельно проверьте, что токен не имеет доступа к другому подключению или Flow.

## Откат

Верните сохранённые прежние поля через PATCH либо удалите персональные настройки через DELETE. Для правила объявления или Flow сначала получите его актуальную версию и затем сохраните прежние значения. Отзыв токена через `DELETE /api/v1/internal-tokens/TOKEN_ID` запрещает последующие запросы, но не отменяет уже сохранённые изменения.

Примеры используют переменные и условные идентификаторы; запросы к рабочей панели в рамках сверки не выполнялись.


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