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

# Клиент и подключение

> Подписка клиента, экран подключения, устройства, документы и мини-апп

## Клиент

Клиент появляется с первым счётом или пробным периодом и дальше живёт под вашим `client_id`. Всё о нём — [`GET /clients/{client_id}`](/api/get-client):

```json theme={"dark"}
{
  "client_id": "user-42",
  "created_at": "2026-09-25T12:00:00Z",
  "subscription": {
    "status": "active",
    "is_trial": false,
    "expires_at": "2026-10-25T12:00:00Z",
    "days_left": 30,
    "subscription_url": "https://sub.example.com/AbCdEf12",
    "connect": [
      {
        "app_id": "happ",
        "app_name": "Happ",
        "connect_url": "https://sub.example.com/r?url=happ%3A%2F%2Fadd%2F…",
        "qr_payload": "https://sub.example.com/AbCdEf12",
        "supports_manual_url": true
      }
    ],
    "devices_limit": 3
  },
  "trial_available": false
}
```

| `subscription.status` | Что значит |
| - | - |
| `active` | Действует. У пробной подписки `is_trial: true` |
| `expired` | Срок вышел. Продление возобновляет подписку с момента оплаты, ссылка та же |
| `suspended` | Срок идёт, но доступ приостановлен платформой |

`subscription: null` — подписки у клиента не было ни разу. Список всех клиентов с фильтром по статусу — [`GET /clients`](/api/list-clients).

Клиент, заблокированный платформой, отвечает `403 API_CLIENT_BLOCKED` на всех ручках клиента, а `trial_available` у него `false`.

## Экран подключения

После оплаты клиенту нужно две вещи: приложение и подписка в нём.

1. **Приложение.** [`GET /apps`](/api/apps) отдаёт платформы, приложения со ссылками на установку и рекомендованное приложение (`recommended_app_id`). Ключ в `downloads` — `platform_id`.
2. **Подписка в приложении.** Для каждого приложения в `subscription.connect` уже собраны:
   * `connect_url` — адрес для кнопки «Открыть в приложении». Это https-страница, которая открывает приложение с подпиской: Telegram и браузеры не открывают ссылки приложений напрямую.
   * `qr_payload` — строка для QR-кода, если клиент подключает другое устройство.
   * `supports_manual_url` — приложение принимает `subscription_url`, вставленную вручную.

`subscription_url` отдаётся и у истёкшей подписки: после продления ссылка та же, переподключать ничего не нужно.

## Устройства

* [`GET …/devices`](/api/list-devices) — подключённые устройства и лимит `devices_limit` (`null` — без ограничения). Без подписки список пуст. Если платформа не ответила — `503 SERVICE_UNAVAILABLE`: пустой список всегда значит «устройств нет», а не сбой.
* [`DELETE …/devices/{device_id}`](/api/delete-device) — отключить устройство и освободить место под новое. `device_id` — HWID из списка; в пути он URL-кодируется (`encodeURIComponent` в JavaScript, `urllib.parse.quote(device_id, safe="")` в Python).
* Места не хватает — докупить устройства счётом с `purpose: devices`, см. [Тарифы и деньги](/pricing).

## Перевыпуск ссылки

Ссылка подписки утекла или клиент передал её посторонним — [`POST …/rotate-link`](/api/rotate-link). Старая ссылка перестаёт работать сразу на всех устройствах, клиент добавляет новую подписку в приложение заново.

* Не чаще раза в час на клиента: иначе `429 LINK_ROTATE_TOO_SOON`, пауза — в заголовке `Retry-After`.
* Нужна действующая подписка — иначе `400 NO_ACTIVE_SUBSCRIPTION`.

## Пробный период

[`POST …/trial`](/api/start-trial) выдаёт пробный период, если он включён вашему аккаунту (`trial_enabled` в [`GET /account`](/api/account)); включает его платформа по запросу менеджеру.

* Клиента нет — заводится.
* Выдаётся один раз: если у клиента уже была подписка — `409 TRIAL_ALREADY_USED`. Проверить заранее — `trial_available` у клиента.
* Суточный лимит пробных периодов на аккаунт — `429 TRIAL_DAILY_LIMIT`.
* `503 SERVICE_UNAVAILABLE` — пробный период не выдан, запрос можно повторить.

## Документы клиента

Клиент покупает у вас, а исполнитель услуги — платформа, поэтому пользовательское соглашение и политику конфиденциальности ведёт она. [`GET /documents`](/api/documents) отдаёт ссылки на готовые страницы под названием вашего сервиса:

```json theme={"dark"}
{
  "documents": [
    {"type": "terms_of_service", "title": "Пользовательское соглашение", "url": "https://api.vargopartners.com/…/terms"},
    {"type": "privacy_policy", "title": "Политика конфиденциальности", "url": "https://api.vargopartners.com/…/privacy"}
  ]
}
```

Покажите обе ссылки клиенту до оплаты — рядом с кнопкой «Оплатить». Страницы открываются без ключа, текст на них обновляет платформа — у себя хранить копию не нужно.

## Мини-апп и сайт

```text theme={"dark"}
Клиент → ваш мини-апп или сайт → ваш сервер → VARGO Partner API
```

* Ключ хранится только на сервере. Мини-апп и сайт ходят к вашему серверу, а тот — к API.
* Клиента в мини-аппе Telegram узнавайте на своём сервере по подписанным данным запуска (`initData`) и передавайте в API его id как `client_id`.
* Кнопку оплаты открывайте ссылкой `payment_url`, кнопку подключения — `connect_url`: обе — обычные https-адреса.