White Label API

Выпускайте ключи доступа для своих клиентов под вашим брендом: из бота, сайта или CRM. Каждый ключ — готовая ссылка-подписка, которая открывается в клиенте в один клик.

Base URLhttps://freelifeip.com/api/wl

Попробовать 7 дней бесплатно Смотреть эндпоинты

Быстрый старт

Начните бесплатно

Пробный период: 7 дней и 3 ключа без оплаты, один раз на аккаунт. Дальше — пакет на странице White Label.

Откройте консоль

Консоль партнёра открывается сразу. В ней ваш X-API-Key, квота и статистика.

Выпустите ключ

Один запрос — и у клиента есть ссылка-подписка с вашим названием в приложении.

Первый ключ

curl -X POST https://freelifeip.com/api/wl/issue-key \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "tg_123456", "days": 30}'

Выпускать ключи можно и без кода — кнопкой в партнёрской консоли. API нужен, когда выдачу ключей хочется автоматизировать.

Аутентификация

Каждый запрос передаёт ключ партнёра в заголовке X-API-Key. Ключ выдаётся в партнёрской консоли после оплаты пакета.

Храните ключ только на сервере. Не встраивайте его в мобильное приложение, фронтенд или публичный репозиторий: с ним можно выпускать ключи из вашей квоты.

Тело запросов и ответов — JSON. Все даты — ISO 8601 в UTC.

Лимиты и квота

Квота — сколько ключей может быть активно одновременно. Равна пакету, который оплачен последним. Отозванные ключи место в квоте освобождают.
Срок ключа — от 1 до 30 дней за один запрос. Срок не выходит за конец оплаченного периода пакета: если до его конца 10 дней, ключ на 30 дней получит 10.
Продление — через extend-key. Ссылка-подписка у клиента при этом не меняется.
Устройства — до 5 одновременных подключений на один ключ.
После окончания пакета выпуск и продление возвращают 402. Ключи клиентов действуют до своей даты, а она не позже конца пакета — продлите пакет вовремя, чтобы клиенты не отключились.

Эндпоинты

POST/api/wl/issue-key

Выпускает новый ключ и возвращает ссылку-подписку для клиента.

Тело запроса

Поле	Тип	Описание
`client_id`	string	Ваш идентификатор клиента (id в Telegram, номер заказа). Показывается в консоли. По умолчанию `sub_client`.
`days`	integer	Срок в днях, 1–30. По умолчанию 30.
`email`	string	Email клиента, необязательно.

Ответ 200

JSON

{
  "status": "success",
  "key_uuid": "8f1c2e4a-…",
  "user_uuid": "b7d9…",
  "expires_at": "2026-10-25T12:00:00",
  "subscription_url": "https://freelifeip.com/sub/…",
  "deeplink_happ": "happ://import/…",
  "deeplink_karing": "karing://install-config?…",
  "web_connect_happ": "https://freelifeip.com/connect/happ/…",
  "web_connect_karing": "https://freelifeip.com/connect/karing/…",
  "auth_username": "…",
  "auth_password": "…",
  "configs": { /* те же ссылки и готовая строка hysteria2 */ }
}

Клиенту достаточно отдать subscription_url, диплинк или безопасную веб-ссылку: приложение само подтянет настройки. Для инлайн-кнопок в Telegram-ботах используйте web_connect_happ / web_connect_karing (Telegram API запрещает протоколы вроде happ:// в кнопках). key_uuid сохраните у себя — он нужен для продления и отзыва.

POST/api/wl/extend-key

Продлевает ключ. Дни добавляются к текущему сроку, а если ключ уже истёк — к сегодняшнему дню. Ссылка-подписка не меняется.

Тело запроса

Поле	Тип	Описание
`key_uuid`обяз.	string	Идентификатор из ответа issue-key.
`days`	integer	1–30, по умолчанию 30.

Ответ 200

JSON

{
  "status": "extended",
  "key_uuid": "8f1c2e4a-…",
  "expires_at": "2026-11-24T12:00:00",
  "capped_by_plan": false
}

capped_by_plan: true означает, что срок урезан до конца оплаченного периода вашего пакета.

POST/api/wl/revoke-key

Отзывает ключ и сразу отключает все устройства клиента. Отозванный ключ продлить нельзя — только выпустить новый.

Тело запроса

Поле	Тип	Описание
`key_uuid`	string	Идентификатор ключа. Либо `user_uuid` из ответа issue-key.

Ответ 200

JSON

{ "status": "revoked", "key_uuid": "8f1c2e4a-…", "disconnected": 1 }

GET/api/wl/stats

Состояние партнёрского аккаунта: пакет, квота, срок, выпущенные ключи и трафик.

Ответ 200

JSON

{
  "partner_name": "Acme Net",
  "tier": "indie",
  "key_quota": 100,
  "plan_expires_at": "2026-10-25T12:00:00",
  "max_issue_days": 30,
  "total_issued_keys": 42,
  "active_keys": 37,
  "total_bytes": 128849018880,
  "total_gb": 120.0,
  "billing_mode": "prepaid",
  "rate_usd": null
}

GET/api/wl/keys

Все ваши ключи одним списком: статус, срок, трафик за месяц и за всё время. Удобно раз в несколько минут синхронизировать к себе и показывать каждому клиенту его расход.

Параметры запроса

Параметр	Тип	Описание
`month`	string	`YYYY-MM`, UTC. По умолчанию — текущий месяц.

Ответ 200

JSON

{
  "month": "2026-10",
  "is_final": false,
  "summary": { "keys_total": 42, "keys_status_active": 37, "active_in_month": 30, "month_gb": 512.4, "rate_usd": 0.8, "amount_usd": 24.0 },
  "keys": [
    { "key_uuid": "8f1c2e4a-…", "client_id": "tg_123456", "status": "active", "is_online": true,
      "expires_at": "…", "last_connected_at": "…", "active_in_month": true,
      "month_bytes": …, "month_gb": 12.5, "total_bytes": …, "total_gb": 40.1, "over_fair_use": false }
  ]
}

В списке все ключи, включая отозванные и ни разу не подключённые. Подробно по одному ключу, с разбивкой по дням, — key-usage.

GET/api/wl/key-usage

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

Параметры запроса

Параметр	Тип	Описание
`key_uuid`обяз.	string	Идентификатор из ответа issue-key.
`from`	date	`YYYY-MM-DD`, UTC. По умолчанию — 1-е число текущего месяца.
`to`	date	`YYYY-MM-DD` включительно, UTC. По умолчанию — сегодня. Период не длиннее 366 дней.

Ответ 200

JSON

{
  "key_uuid": "8f1c2e4a-…",
  "client_id": "tg_123456",
  "status": "active",
  "is_online": true,
  "created_at": "2026-10-01T09:12:00",
  "expires_at": "2026-10-31T09:12:00",
  "first_connected_at": "2026-10-01T09:20:30",
  "last_connected_at": "2026-10-02T21:40:00",
  "active_this_month": true,
  "lifetime": { "bytes_up": …, "bytes_down": …, "total_bytes": 5368709120, "total_gb": 5.0 },
  "period": { "from": "2026-10-01", "to": "2026-10-02", "bytes_up": …, "bytes_down": …, "total_bytes": …, "total_gb": 5.0 },
  "daily": [
    { "date": "2026-10-01", "bytes_up": …, "bytes_down": …, "total_bytes": … }
  ]
}

bytes_up — отправлено устройством клиента, bytes_down — получено. Статистика обновляется примерно раз в 30 секунд. Дни без трафика в daily не попадают.

GET/api/wl/billing

Расчёт за календарный месяц (UTC): какие ключи подключались и сколько трафика прошло через каждый. Для партнёров на постоплате — сумма к оплате. Месяц, который ещё идёт, считается на текущий момент (is_final: false).

Параметры запроса

Параметр	Тип	Описание
`month`	string	`YYYY-MM`. По умолчанию — текущий месяц.

Ответ 200

JSON

{
  "partner_name": "Acme Net",
  "month": "2026-10",
  "period_start": "2026-10-01T00:00:00",
  "period_end": "2026-11-01T00:00:00",
  "is_final": false,
  "billing_mode": "postpaid",
  "currency": "USD",
  "rate_usd": 0.8,
  "active_keys": 2,
  "amount_usd": 1.6,
  "fair_use_gb": 1000,
  "over_fair_use_keys": 0,
  "keys": [
    { "key_uuid": "8f1c2e4a-…", "client_id": "tg_123456", "bytes_up": …, "bytes_down": …,
      "total_bytes": …, "total_gb": 5.0, "first_seen_at": "…", "last_seen_at": "…", "over_fair_use": false }
  ]
}

Ключ попадает в расчёт, если в этом месяце через него прошёл трафик. Выпущенные, но ни разу не подключённые ключи в расчёт не входят. У партнёров на предоплате rate_usd и amount_usd равны null: пакет уже оплачен, список нужен для аналитики.

Пример интеграции

Выпуск ключа из вашего бэкенда: например, после оплаты у вас в боте.

import os, requests

API = "https://freelifeip.com/api/wl"
HEADERS = {"X-API-Key": os.environ["FREELIFE_API_KEY"]}

def issue_key(client_id: str, days: int = 30) -> dict:
    r = requests.post(f"{API}/issue-key", headers=HEADERS,
                      json={"client_id": client_id, "days": days}, timeout=15)
    r.raise_for_status()
    return r.json()

key = issue_key("tg_123456")
print(key["subscription_url"], key["key_uuid"])

const API = "https://freelifeip.com/api/wl";

async function issueKey(clientId, days = 30) {
  const res = await fetch(`${API}/issue-key`, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.FREELIFE_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ client_id: clientId, days }),
  });
  if (!res.ok) throw new Error(`${res.status}: ${(await res.json()).detail}`);
  return res.json();
}

const key = await issueKey("tg_123456");
console.log(key.subscription_url, key.key_uuid);

# выпуск
curl -X POST https://freelifeip.com/api/wl/issue-key \
  -H "X-API-Key: $FREELIFE_API_KEY" -H "Content-Type: application/json" \
  -d '{"client_id": "tg_123456", "days": 30}'

# продление
curl -X POST https://freelifeip.com/api/wl/extend-key \
  -H "X-API-Key: $FREELIFE_API_KEY" -H "Content-Type: application/json" \
  -d '{"key_uuid": "8f1c2e4a-…", "days": 30}'

# отзыв
curl -X POST https://freelifeip.com/api/wl/revoke-key \
  -H "X-API-Key: $FREELIFE_API_KEY" -H "Content-Type: application/json" \
  -d '{"key_uuid": "8f1c2e4a-…"}'

# статистика
curl https://freelifeip.com/api/wl/stats -H "X-API-Key: $FREELIFE_API_KEY"

# все ключи с трафиком за месяц
curl "https://freelifeip.com/api/wl/keys?month=2026-10" -H "X-API-Key: $FREELIFE_API_KEY"

# трафик одного ключа за октябрь
curl "https://freelifeip.com/api/wl/key-usage?key_uuid=8f1c2e4a-…&from=2026-10-01&to=2026-10-31" \
  -H "X-API-Key: $FREELIFE_API_KEY"

# расчёт за месяц
curl "https://freelifeip.com/api/wl/billing?month=2026-10" -H "X-API-Key: $FREELIFE_API_KEY"

Коды ошибок

Ошибки приходят как {"detail": "описание"}.

Код	Когда
`400`	Неверный запрос: нет `key_uuid`, `days` не число, дата или месяц не в формате `YYYY-MM-DD` / `YYYY-MM`.
`401`	Нет заголовка `X-API-Key` или ключ неверный.
`402`	Оплаченный период пакета закончился. Продлите пакет в консоли.
`403`	Ключ принадлежит другому партнёру.
`404`	Ключ не найден.
`409`	Попытка продлить отозванный ключ.
`429`	Квота исчерпана: активных ключей столько же, сколько в пакете. Отзовите неиспользуемые или возьмите пакет больше.

Клиентские приложения

Ссылка-подписка работает в Happ (iOS, Android) и Karing (Android, Windows, macOS). В ответе issue-key есть диплинки для обоих — клиент нажимает и сразу подключается. В приложении отображается название вашего бренда из консоли.

Тарифы

Оплата помесячно. Квота — число одновременно активных ключей.

100 ключей

12 000 ₽ / мес

500 ключей

45 000 ₽ / мес

1000 ключей

80 000 ₽ / мес

Выбрать пакет