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

Клиент

Клиент появляется с первым запросом счёта или пробного периода и дальше живёт под вашим client_id. Всё о нём — GET /clients/{client_id}:

{
  "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//add/https%3A//sub.example.com/AbCdEf12",
        "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`	Срок идёт, но доступ приостановлен платформой

is_trial остаётся true и после конца срока: expired с is_trial: true — клиент попробовал и не купил, ему стоит предложить тариф. После оплаты is_trial становится false. subscription: null — подписки у клиента не было ни разу. Список всех клиентов с фильтром по статусу — GET /clients. Клиент, заблокированный платформой, отвечает 403 API_CLIENT_BLOCKED на всех запросах по клиенту, а в списке GET /clients у него trial_available: false.

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

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

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

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

Устройства

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

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

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

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

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

POST …/trial выдаёт пробный период. Он включён по умолчанию (trial_enabled в GET /account); платформа может его выключить — тогда ответ 403 TRIAL_DISABLED.

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

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

Клиент покупает у вас, а исполнитель услуги — платформа, поэтому пользовательское соглашение и политику конфиденциальности ведёт она. GET /documents отдаёт ссылки на готовые страницы под названием вашего сервиса (по умолчанию «VARGO», меняется запросом PATCH /account):

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

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

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

Клиент → ваш мини-апп или сайт → ваш сервер → VARGO Partner API

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

Начало

Как это работает

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

Клиент

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

Устройства

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

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

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

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

​Клиент

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

​Устройства

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

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

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

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

Клиент

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

Устройства

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

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

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

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