> 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/readme.md).

# Обзор

## Для кого

Эта документация для VPN-провайдеров и владельцев серверов, у которых уже есть ссылка подписки или endpoint, отдающий конфиги. Tumbler подключает такую подписку через мобильное приложение, а backend сам загружает, нормализует и доставляет конфигурацию клиенту.

## Основной сценарий

В большинстве случаев вам не нужно менять инфраструктуру.

1. У вас уже есть subscription URL, например `https://provider.example.com/sub/user-token`.
2. URL отдаёт конфиги: raw `vless://...`, base64-подписку, JSON `links`/`nodes`, Xray JSON или sing-box JSON.
3. Вы формируете ссылку добавления в Tumbler:

   ```
   tumbler://add?link=<url-encoded subscription URL>
   ```
4. Пользователь открывает ссылку или сканирует QR.
5. Приложение отправляет исходную ссылку в backend, backend сам скачивает подписку, проверяет формат, нормализует узлы и возвращает клиенту зашифрованный runtime payload.

Если нельзя раскрывать исходный subscription URL пользователю, используйте `crypt3`: провайдер отдаёт не raw HTTPS URL, а зашифрованный source link вида `schema://crypt3/<token>`, обёрнутый в тот же `tumbler://add?link=...`.

## С чего начать

* [Быстрый старт](/ru/nachat/quickstart.md) - если у вас уже есть subscription URL.
* [Ссылка или QR для добавления в Tumbler](/ru/nachat/add-link.md) - точный формат `tumbler://add?link=...`.
* [Форматы ответа](/ru/kontrakt-podpiski/response-formats.md) - что может возвращать ваш endpoint.
* [Примеры подписки](/ru/kontrakt-podpiski/examples.md) - минимальные raw VLESS и JSON примеры.

## Что настраивается потом

* Метаданные: название профиля, кнопки Support/Manage, лимиты, зеркала, новый URL, quota/expiry.
* Балансировка: порядок узлов по RTT или активным соединениям.
* Защита URL: `crypt3`, короткие токены, подписи, ограничения fetcher.
* **\[PAID]** Advanced Connection Control: лимиты по подписке, конфигу или группе, soft/hard режимы и callbacks.

## Что важно не перепутать

* Публичный add link для Tumbler: `tumbler://add?link=<url-encoded source>`.
* Source link внутри `link`: обычный `https://...` subscription URL или `schema://crypt3/<token>`.
* `tumbler://add/<url>` как path-формат не является текущим контрактом. Используйте query-параметр `link`.
* Термин пишется `crypt3`, не `cryp3`.

## Навигация

* [SUMMARY.md](https://github.com/evasionlab/tumbler.backend/blob/main/provider-docs/SUMMARY.md) - GitBook-навигация по provider journey.
* [glossary.md](/ru/glossary.md) - термины.
* [changelog.md](/ru/changelog.md) - изменения публичного контракта и документации.

## Правила публичного контракта

* Не описывайте внутренние таблицы, Redis-ключи, секреты и детали, не входящие в provider contract.
* Все ключи, HTTP-заголовки, JSON-поля и коды статусов указываются в оригинале.
* Платные возможности помечаются **\[PAID]**.
* При изменениях публичного контракта обновляйте [changelog.md](/ru/changelog.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/readme.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.