> For the complete documentation index, see [llms.txt](https://docs.tumbler.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tumbler.app/ru/kontrakt-podpiski/metadata.md).

# Метаданные

## Для кого

Провайдеры, которые управляют поведением backend и клиента через мета-поля в теле ответа или HTTP-заголовки.

## Способы передачи и приоритет

* В теле: мета-строки `#key: value` в текстовых списках или объект `meta` в JSON.
* В заголовках: `Support-URL`, `Manage-URL`, `Hide-Settings`, `Subscription-Userinfo`, `X-Subscription-New-URL`, `X-Subscription-Mirrors` и другие эквивалентные `X-Subscription-*`/короткие имена (регистр не важен).
* **Приоритет:** заголовки перекрывают мета из тела. Если одно и то же поле задано в мета и в заголовке, применяется значение из заголовка.

## Что считается метаданными

Метаданные - это дополнительные поля управления вокруг уже существующей подписки. Они не заменяют сами VLESS/Xray/sing-box конфиги.

Минимальный рабочий ответ вообще может не содержать метаданных: достаточно валидных `vless://...` строк или JSON `links`/`nodes`. Метаданные добавляйте после того, как базовый импорт уже работает.

## Ключи управления провайдером

| Ключ                                                     | Тип / дефолт                                                                             | Пример                                                    | Эффект                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `support-url`                                            | string URL, пусто = нет ссылки                                                           | `https://help.example.com`                                | Кнопка/ссылка «Support» в UI и в `/v1/providers`; помогает пользователю обратиться в поддержку.                                                                                                                                                                            |
| `manage-url`                                             | string URL, пусто = нет ссылки                                                           | `https://account.example.com/billing`                     | Кнопка/ссылка «Manage» (аккаунт/оплата); показывается пользователю и в `/v1/providers`.                                                                                                                                                                                    |
| `mirrors`                                                | Список полных `http/https` URL без `userinfo` (`username:password@`), пусто = нет зеркал | `https://m1.example.com/sub, https://m2.example.com/sub`  | Используется refresh-циклом как fallback после основного URL; порядок сохраняется, дубликаты удаляются.                                                                                                                                                                    |
| `new-url`                                                | Полный URL, опционально                                                                  | `https://new.example.com/sub`                             | Побеждает `new-domain`. Становится новой canonical ссылкой: backend обновляет подписку по ней и отдаёт её клиенту.                                                                                                                                                         |
| `new-domain`                                             | Домен (без схемы/пути), опционально                                                      | `new.example.com`                                         | Меняет только хост canonical URL для будущих обновлений, если `new-url` не задан. Используйте, когда путь остаётся прежним.                                                                                                                                                |
| `hide-settings`                                          | bool, дефолт `false`                                                                     | `true`                                                    | Скрывает часть ручных настроек в UI (агрегируется через OR по снапшотам провайдера).                                                                                                                                                                                       |
| `profile-title` (`profile_title` alias)                  | string, дефолт пусто                                                                     | `Premium NL`                                              | Заголовок профиля, который клиент показывает как отображаемое имя подписки. Принимается в meta и заголовках в формах `profile-title` и `profile_title` (регистр не важен).                                                                                                 |
| `installation-limit`                                     | int ≥ 0, дефолт `0` (= без лимита)                                                       | `3`                                                       | Ограничивает число активных установок. Превышение даёт `INSTALLATION_LIMIT_EXCEEDED` при выдаче новой установки.                                                                                                                                                           |
| `connection-limit`                                       | int ≥ 0, дефолт `0` (= без лимита)                                                       | `2`                                                       | Лимит одновременных VPN-соединений на установку. `1` фиксирует одно подключение, значения ≥ 2 применимы только если тариф провайдера/установки включает эту возможность (см. [feature matrix](/ru/funkcii/overview.md)). При превышении новые сессии блокируются сервером. |
| `balancer-method`                                        | `ping` \| `connections`, пусто = выключено                                               | `ping`                                                    | Включает перестановку узлов сервером: выбирается лидер по RTT (`ping`) или по загрузке (`connections`). Требует сбора метрик.                                                                                                                                              |
| `capabilities`                                           | array/string list, пусто = нет платных capabilities                                      | `["advanced_connection_control"]`                         | Декларация платных возможностей, согласованных для провайдера. Для ACC используется вместе с `acc-enabled` и `acc-*` полями.                                                                                                                                               |
| `subscription-userinfo`                                  | строка `upload=<bytes>; download=<bytes>; total=<bytes>; expire=<unix-seconds>`          | `upload=123; download=456; total=1024; expire=1800000000` | Единый способ передать расход/лимит трафика и дату окончания подписки.                                                                                                                                                                                                     |
| `upload` / `download` / `total` / `expire` (`expire-at`) | int64 ≥ 0                                                                                | `upload=123`, `expire-at=1800000000`                      | Те же quota/expiry данные отдельными ключами в `meta`/body строках/алиасных заголовках.                                                                                                                                                                                    |

### Миграции URL

* `new-url` всегда побеждает `new-domain`. Если заданы оба, используется только `new-url`.
* Если указан `new-url`, canonical URL сохраняется с ним; дальнейшие refresh-запросы и обновления подписки идут на новый адрес. Backend также трактует его хост как `new-domain` по умолчанию — провайдеру ничего дополнительно задавать не нужно.
* `new-domain` меняет только хост canonical URL, оставляя путь/схему исходного финального URL; используется только когда `new-url` пуст.
* При обоих полях пустых backend остаётся на текущем canonical URL.

### Зеркала

* Используются, когда основной запрос (preferred + canonical кандидаты) вернул ошибку/HTTP 4xx/5xx. После неуспеха всех основных кандидатов backend добавляет mirrors и пробует их по порядку без дополнительных ретраев основного URL.
* Если цепочка уже в режиме skip-primary (circuit breaker), первый mirror пробуется сразу.
* Формат: в заголовках список через запятую, в мета — массив строк.
* Рекомендуется указывать самые надёжные/быстрые зеркала первыми; все URL должны быть абсолютными без `userinfo` (`username:password@` в URL недопустимы).

### Что видит пользователь

* `support-url` / `manage-url` отображаются как кнопки/ссылки в карточке провайдера.
* `hide-settings` скрывает часть ручных настроек (параметры подключения) в клиенте.
* `installation-limit` / `connection-limit` влияют на разрешение подключения: при превышении новые установки или сессии блокируются сервером.
* `subscription-userinfo`/`upload`/`download`/`total`/`expire` позволяют клиенту показать срок действия подписки и статистику трафика.

## Примеры

### Только заголовки

```
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Support-URL: https://help.example.com
Manage-URL: https://account.example.com
X-Subscription-New-URL: https://new.example.com/sub
X-Subscription-Mirrors: https://m1.example.com/sub, https://m2.example.com/sub
Hide-Settings: true
Profile-Title: Premium NL
Profile_Title: Premium NL
Connection-Limit: 2
Subscription-Userinfo: upload=123456; download=654321; total=10737418240; expire=1800000000

vless://11111111-1111-1111-1111-111111111111@edge.example.com:443#Edge
```

Все указанные ключи берутся из заголовков и перекрывают значения внутри тела (если есть).

### Meta в теле

```json
{
  "links": [
    "vless://aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa@a.example.com:443#A",
    "vless://bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb@b.example.com:8443#B"
  ],
  "meta": {
    "support-url": "https://help.example.com",
    "manage-url": "https://account.example.com/billing",
    "mirrors": ["https://m1.example.com/sub", "https://m2.example.com/sub"],
    "new-domain": "new.example.com",
    "hide-settings": true,
    "profile-title": "Premium NL",
    "profile_title": "Premium NL",
    "installation-limit": 1,
    "connection-limit": 2,
    "capabilities": ["advanced_connection_control"],
    "balancer-method": "ping",
    "subscription-userinfo": "upload=123456; download=654321; total=10737418240; expire=1800000000",
    "upload": 123456,
    "download": 654321,
    "total": 10737418240,
    "expire-at": 1800000000
  }
}
```

## См. также

* [subscription/response-formats.md](/ru/kontrakt-podpiski/response-formats.md)
* [operations/mirrors-and-migration.md](/ru/uluchsheniya-posle-pervogo-zapuska/mirrors-and-migration.md)
* [features/overview.md](/ru/funkcii/overview.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.tumbler.app/ru/kontrakt-podpiski/metadata.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.