# KILLA PROXY & VPN — полная документация

> Один API для VPN-подписок, серверных и резидентных прокси: узнать цену, купить, продлить и управлять — из своего бота или панели.

Этот файл — вся документация PROXY & VPN одним текстом, специально для чтения нейросетью: справочник методов, параметры, примеры запросов и ответов, описания полей, коды ошибок, сценарии интеграции и правила работы. Больше ничего открывать не нужно.

- Версия API: `v1`
- Базовый адрес: `https://proxy.killa.cc/api/v1`
- Документация обновлена: 2026-11-03
- Человеческая версия: https://proxy-docs.killa.cc
- Машинное описание OpenAPI 3.1: https://proxy-docs.killa.cc/openapi.json

## Коротко для интеграции

- Все запросы идут на `https://proxy.killa.cc/api/v1`, тело и ответы — JSON.
- Токен передаётся в каждом запросе: заголовок `Authorization: Bearer <token>`.
- Для запросов с телом нужен заголовок `Content-Type: application/json`.
- Успешный ответ: `{"ok": true, "data": { ... }}`. Полезные поля лежат внутри `data`.
- Ответ с ошибкой: `{"ok": false, "error": {"code": "...", "message": "...", "details": null}}`.
- Поле `details` в ответе есть всегда: `null`, когда уточнять нечего.
- Всегда проверяй поле `ok`. При `ok: false` логику строй на `error.code`, а `error.message` показывай человеку как текст.

Разделы справочника:

- **VPN** (Подписки и устройства клиентов) — методов: 10. Продавай VPN-подписки под своим брендом: клиент получает ссылку, добавляет её в приложение — и подключается.
- **Серверные прокси** (Выделенные и общие IPv4, IPv6) — методов: 6. Прокси с фиксированным IP: выбираешь страну, тип адреса и срок — получаешь готовые данные для подключения.
- **Резидентные прокси** (Трафик, локации, прокси-листы) — методов: 12. Продаёшь трафик в гигабайтах, а клиент сам собирает прокси-лист под нужные страны, города и провайдеров.
- **Аккаунт** (Баланс и расходы) — методов: 1. Всё, что касается самого аккаунта: сколько денег на балансе и сколько ушло через API.

Полный список методов:

- `GET /vpn/quote` — Цены на VPN (бесплатно, ничего не меняет)
- `POST /vpn/buy` — Купить подписку (спишет деньги с баланса)
- `GET /vpn/info` — Информация о подписке (бесплатно, ничего не меняет)
- `POST /vpn/renew` — Продлить подписку (спишет деньги с баланса)
- `GET /vpn/hwid/devices` — Список устройств (бесплатно, ничего не меняет)
- `POST /vpn/hwid/reset` — Сбросить одно устройство (меняет состояние, денег не спишет)
- `POST /vpn/hwid/reset-all` — Сбросить все устройства (меняет состояние, денег не спишет)
- `GET /vpn/hwid/quote` — Цены на увеличение лимита (бесплатно, ничего не меняет)
- `POST /vpn/hwid/increase` — Увеличить лимит устройств (спишет деньги с баланса)
- `POST /vpn/delete` — Удалить подписку (необратимо)
- `GET /dedicated/quote` — Посчитать стоимость (бесплатно, ничего не меняет)
- `GET /dedicated/country` — Список стран (бесплатно, ничего не меняет)
- `GET /dedicated/count` — Сколько прокси доступно (бесплатно, ничего не меняет)
- `POST /dedicated/buy` — Купить прокси (спишет деньги с баланса)
- `GET /dedicated/prolong/quote` — Стоимость продления (бесплатно, ничего не меняет)
- `POST /dedicated/prolong` — Продлить прокси (спишет деньги с баланса)
- `GET /residential/traffic/quote` — Посчитать стоимость трафика (бесплатно, ничего не меняет)
- `POST /residential/traffic/buy` — Купить трафик (спишет деньги с баланса)
- `POST /residential/traffic/add` — Пополнить трафик (спишет деньги с баланса)
- `GET /residential/traffic/balance` — Остаток трафика (бесплатно, ничего не меняет)
- `POST /residential/locations/{level}` — Локации (бесплатно, ничего не меняет)
- `POST /residential/proxies/generate` — Сгенерировать прокси-лист (бесплатно, ничего не меняет)
- `POST /residential/proxies/rotate-ip` — Сменить IP (меняет состояние, денег не спишет)
- `GET /residential/whitelist` — Разрешённые IP (бесплатно, ничего не меняет)
- `POST /residential/whitelist/add` — Добавить IP (меняет состояние, денег не спишет)
- `POST /residential/whitelist/remove` — Убрать IP (меняет состояние, денег не спишет)
- `GET /residential/password` — Текущий пароль (бесплатно, ничего не меняет)
- `POST /residential/password/reset` — Сбросить пароль (меняет состояние, денег не спишет)
- `GET /balance` — Баланс (бесплатно, ничего не меняет)

## Правила работы

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

### Токен

Токен — это пароль к твоему балансу. Взять его можно в боте: **Профиль → API**.

- Передавай токен в заголовке каждого запроса: `Authorization: Bearer <token>`.
- Для запросов с JSON-телом добавляй `Content-Type: application/json`.
- Не передавай токен в адресе запроса, не пиши в логи, не сохраняй в репозитории и не отправляй в чаты. Храни его в переменных окружения или хранилище секретов.
- Если токен утёк — сразу сбрось его: **Профиль → API → Сбросить токен**. Старый перестаёт работать сразу, новый нужно обновить во всех интеграциях.

### Формат ответа

Ответ API — JSON с полем `ok`. Успех:

```json
{
  "ok": true,
  "data": {}
}
```

Ошибка:

```json
{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Bad request",
    "details": null
  }
}
```

- Всегда проверяй `ok`.
- При `ok: false` строй логику на `error.code`, а `error.message` показывай как текст. Все коды собраны на странице [Ошибки](https://proxy-docs.killa.cc/errors).

### Что хранить у себя

Все дальнейшие действия идут по идентификаторам из ответа на покупку — сохраняй их в своей базе:

- **VPN** — `uuid` подписки: все действия — только по нему, списка подписок в API нет. Клиенту отдай ссылку `subscriptionUrl`.
- **Серверные прокси** — `ids` каждой прокси (нужны для продления) вместе с данными доступа `ip`, `port`, `username`, `password` и датой окончания `date_end` — после продления приходит новая.
- **Резидентные прокси** — `subuser_id` клиента: дальше все методы работают только через него.

### Деньги и повторы

- Цену показывай через quote-методы: они возвращают итоговую сумму до списания.
- У каждого метода в справочнике есть метка: **бесплатно**, **меняет доступ**, **спишет деньги** или **необратимо**.
- Покупки и продления не повторяй «вслепую». Если запрос оборвался по сети или таймауту:
  1. Проверь баланс — возможно, списание уже прошло.
  2. Проверь состояние услуги — например, `/vpn/info` или `/residential/traffic/balance`.
  3. Сомневаешься — напиши в [поддержку](https://proxy-docs.killa.cc/support).

### Таймауты

- Ставь клиентский таймаут 30–60 секунд.
- Чтение и quote можно аккуратно повторять: через 10–30 секунд, не больше 1–3 попыток.
- `400` не повторяй — исправь запрос. На `401` проверь токен или сбрось его.

### Нейтральные подписки

Страница VPN-подписки, которую видит твой клиент, — без упоминаний нашего проекта. Продавай под своим брендом.

### Частые вопросы

#### Зачем нужны quote-методы?

Quote возвращает итоговую стоимость **до списания**. Удобно, чтобы показать цену клиенту и проверить, хватает ли баланса.

#### Что будет, если токен утёк?

Считай токен паролем. Сразу сбрось его в боте: **Профиль → API → Сбросить токен**. Старый токен перестанет работать.

#### Почему приходит 401 Unauthorized?

- Не передан заголовок `Authorization`.
- Неверный формат: нужен `Authorization: Bearer <token>`.
- Токен был сброшен или заменён.

#### Почему приходит 400 Bad Request?

Обычно это неверные или отсутствующие параметры. Проверь поля, типы (строка, число, массив) и обязательные параметры в описании метода.

#### Что означает 5xx?

Ошибка на стороне сервиса или поставщика. Обычно помогает повторить запрос позже.

#### Можно ли безопасно повторить покупку?

Не повторяй покупку или продление «вслепую». Если запрос упал по таймауту или сети — проверь баланс и состояние услуги. Если сомневаешься — напиши в [поддержку](https://proxy-docs.killa.cc/support).

## Сценарии интеграции

Готовые пути «от и до»: в каком порядке вызывать методы для типовых задач.

### Подключить через нейросеть

> Дай нейросети один адрес — она прочитает всю документацию и напишет интеграцию.

#### Один файл вместо всего сайта

Вся документация собрана в один текстовый файл: `https://proxy-docs.killa.cc/llms-full.txt`. В нём все методы, параметры, примеры запросов и ответов, описания полей, коды ошибок и правила работы. Нейросети этого файла достаточно — больше ничего открывать не нужно.

#### Скопируй и вставь нейросети

```text
Прочитай https://proxy-docs.killa.cc/llms-full.txt —
это полная документация PROXY & VPN API.

Напиши на <язык и фреймворк> клиент для задачи:
<что нужно сделать>.

Требования:
- токен бери из переменной окружения;
- цену показывай через quote-метод до покупки;
- ошибки разбирай по таблице кодов из документации;
- запросы, которые списывают деньги, не повторяй
  вслепую после обрыва связи.
```

Замени то, что в угловых скобках, на своё — остальное менять не нужно.

#### Готовый клиент из описания

Если удобнее генератор кода, Postman или Insomnia — бери машинное описание `https://proxy-docs.killa.cc/openapi.json` в формате OpenAPI 3.1. Там те же методы, параметры и схемы ответов.

#### Проверь первым делом

Попроси вызвать метод, который ничего не меняет и не стоит денег: если ответ пришёл — токен и адрес настроены верно.

**Метод:** `GET /balance` — Баланс (подробно — в разделе «GET /balance»)

### Первый запрос за 2 минуты

> Проверишь баланс и узнаешь цены — без единой покупки.

#### Получи токен

Открой бота: **Профиль → API** и скопируй токен. Там же кнопка **Сбросить токен** — после сброса старый перестаёт работать сразу.

> **Совет.**
> В примерах на этом сайте вместо токена — `YOUR_TOKEN`: для пробы замени его на свой. В своём сервисе храни токен в переменной окружения или хранилище секретов, а не в коде.

#### Передавай токен в заголовке

Все запросы идут на `https://proxy.killa.cc/api/v1`, токен — в заголовке `Authorization: Bearer <token>`. Тело запросов и ответы — JSON.

#### Проверь баланс

Самый безопасный первый запрос: ничего не меняет и ничего не стоит.

**Метод:** `GET /balance` — Баланс (подробно — в разделе «GET /balance»)

#### Узнай цены

Перед покупкой всегда считай цену: quote-методы возвращают итоговую сумму до списания.

**Метод:** `GET /vpn/quote` — Цены на VPN (подробно — в разделе «GET /vpn/quote»)

#### Что дальше

Выбери, что продаёшь: [VPN](https://proxy-docs.killa.cc/scenarios/sell-vpn), [серверные прокси](https://proxy-docs.killa.cc/scenarios/dedicated) или [резидентные прокси](https://proxy-docs.killa.cc/scenarios/residential).

### Продать VPN клиенту

> От цены до ссылки у клиента — четыре шага.

#### Узнай цены

Покажи клиенту тарифы. В покупку передаются только периоды из этого ответа.

**Метод:** `GET /vpn/quote` — Цены на VPN (подробно — в разделе «GET /vpn/quote»)

#### Купи подписку

Клиент оплатил у тебя — купи ему подписку. Цена спишется с твоего баланса.

**Метод:** `POST /vpn/buy` — Купить подписку (подробно — в разделе «POST /vpn/buy»). Значения для этого шага: `{"period_months": 1}`

> **Внимание.**
> Если запрос оборвался, не повторяй покупку «вслепую». Сначала проверь баланс — возможно, подписка уже куплена.

#### Сохрани uuid и отдай ссылку

В ответе — `uuid` и `subscriptionUrl`. `uuid` сохрани у себя: списка подписок в API нет, и все дальнейшие действия — только по нему. Клиенту отдай ссылку — он добавит её в VPN-приложение.

#### Показывай состояние

Статус, срок и лимиты — по запросу. Например, когда клиент открывает у тебя свой профиль.

**Метод:** `GET /vpn/info` — Информация о подписке (подробно — в разделе «GET /vpn/info»)

### Продлить VPN и напомнить о сроке

> Следи за сроком, напоминай заранее и продлевай одним запросом.

#### Узнай срок

`expireAt` — дата окончания, `status` — состояние подписки. Напомни клиенту о продлении заранее, пока подписка активна.

**Метод:** `GET /vpn/info` — Информация о подписке (подробно — в разделе «GET /vpn/info»)

#### Продли

Если подписка ещё действует, период добавится к дате окончания. Если уже истекла — отсчёт пойдёт от текущего дня.

**Метод:** `POST /vpn/renew` — Продлить подписку (подробно — в разделе «POST /vpn/renew»). Значения для этого шага: `{"period_months": 3}`

> **Совет.**
> Пробную подписку продлевают так же — обычным месячным периодом. После этого она становится полноценной.

### Устройства клиента

> Клиент не может подключить новый телефон? Разберёшься за минуту.

#### Посмотри устройства

Сравни `connected` и `device_limit`: если они равны, лимит занят.

**Метод:** `GET /vpn/hwid/devices` — Список устройств (подробно — в разделе «GET /vpn/hwid/devices»)

#### Отвяжи лишнее

Отвяжи старое устройство по его `hwid` — место освободится.

**Метод:** `POST /vpn/hwid/reset` — Сбросить одно устройство (подробно — в разделе «POST /vpn/hwid/reset»)

#### Или отвяжи все сразу

Когда проще начать с чистого листа.

**Метод:** `POST /vpn/hwid/reset-all` — Сбросить все устройства (подробно — в разделе «POST /vpn/hwid/reset-all»)

#### Узнай цену большего лимита

Если устройств действительно нужно больше — покажи клиенту варианты.

**Метод:** `GET /vpn/hwid/quote` — Цены на увеличение лимита (подробно — в разделе «GET /vpn/hwid/quote»)

#### Увеличь лимит

Оплата разовая: лимит увеличивается навсегда и сохраняется при продлениях.

**Метод:** `POST /vpn/hwid/increase` — Увеличить лимит устройств (подробно — в разделе «POST /vpn/hwid/increase»). Значения для этого шага: `{"delta": 2}`

### Серверные прокси: купить и продлить

> Страна, тип адреса, срок — и клиент получает готовые данные для подключения.

#### Выбери страну

**Метод:** `GET /dedicated/country` — Список стран (подробно — в разделе «GET /dedicated/country»)

#### Проверь наличие

Перед крупной покупкой убедись, что нужное количество есть.

**Метод:** `GET /dedicated/count` — Сколько прокси доступно (подробно — в разделе «GET /dedicated/count»)

#### Посчитай цену

**Метод:** `GET /dedicated/quote` — Посчитать стоимость (подробно — в разделе «GET /dedicated/quote»)

#### Купи

Сохрани `ids` каждой прокси — они нужны для продления. Клиенту отдай `ip`, `port`, `username` и `password`: прокси работают и по HTTP(S), и по SOCKS5.

**Метод:** `POST /dedicated/buy` — Купить прокси (подробно — в разделе «POST /dedicated/buy»)

#### Посчитай продление

**Метод:** `GET /dedicated/prolong/quote` — Стоимость продления (подробно — в разделе «GET /dedicated/prolong/quote»)

#### Продли

**Метод:** `POST /dedicated/prolong` — Продлить прокси (подробно — в разделе «POST /dedicated/prolong»)

### Резидентные прокси: трафик и прокси-лист

> Продаёшь гигабайты — клиент сам собирает прокси под нужные локации.

#### Посчитай цену трафика

Скидка, если она есть, видна прямо в ответе.

**Метод:** `GET /residential/traffic/quote` — Посчитать стоимость трафика (подробно — в разделе «GET /residential/traffic/quote»)

#### Купи трафик

Первая покупка клиента в пуле — с его `telegram_id`. В ответе `subuser_id`: сохрани его, дальше всё работает только через него.

**Метод:** `POST /residential/traffic/buy` — Купить трафик (подробно — в разделе «POST /residential/traffic/buy»)

#### Подбери локации

Страны, регионы, города, индексы или провайдеры — для фильтров прокси-листа.

**Метод:** `POST /residential/locations/{level}` — Локации (подробно — в разделе «POST /residential/locations/{level}»)

#### Собери прокси-лист

**Метод:** `POST /residential/proxies/generate` — Сгенерировать прокси-лист (подробно — в разделе «POST /residential/proxies/generate»)

#### Дай доступ по IP

Логин и пароль приходят в ответе на покупку. Если клиенту удобнее без пароля — добавь его IP.

**Метод:** `POST /residential/whitelist/add` — Добавить IP (подробно — в разделе «POST /residential/whitelist/add»)

#### Следи за остатком

**Метод:** `GET /residential/traffic/balance` — Остаток трафика (подробно — в разделе «GET /residential/traffic/balance»)

#### Пополни

**Метод:** `POST /residential/traffic/add` — Пополнить трафик (подробно — в разделе «POST /residential/traffic/add»)

## Справочник методов

### VPN — Подписки и устройства клиентов

Продавай VPN-подписки под своим брендом: клиент получает ссылку, добавляет её в приложение — и подключается.

Коротко: Покупка и продление подписок; Платный пробный тариф; Контроль устройств клиента.

**Подписка — это ссылка.** Клиент получает ссылку подписки `subscriptionUrl` и добавляет её в VPN-приложение. Страница подписки нейтральная — без упоминаний нашего проекта, поэтому продавать можно под своим брендом.

**Всё по uuid.** `uuid` приходит в ответе на покупку, и дальше все действия — только по нему. Списка всех подписок в API нет, поэтому храни `uuid` у себя. Чужой или несуществующий `uuid` вернёт `404 not_found`.

**Статусы.** `ACTIVE` — активна, `DISABLED` — отключена, `LIMITED` — ограничена, `EXPIRED` — истекла.

**Тарифы.** Месячные периоды и платный пробный тариф `trial` — цены и условия в `/vpn/quote`. Пробную подписку продлевают обычным месячным периодом, и она становится полноценной.

**Устройства.** У подписки есть лимит устройств. Устройства можно посмотреть и отвязать, а лимит — увеличить: оплата разовая, лимит сохраняется при продлениях.

#### GET /vpn/quote — Цены на VPN

Идентификатор в документации: `vpn.quote`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/quote`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Возвращает цены на месячные тарифы и условия платного пробного тарифа.

**Когда нужен.** Чтобы показать клиенту цены и передать в покупку только допустимый период.

##### Параметры

_Параметров нет._

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/vpn/quote' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "1": 200,
    "3": 500,
    "6": 900,
    "12": 1500,
    "trial": {
      "price_rub": 5,
      "days": 3,
      "traffic_limit_gb": 5
    }
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.1` | number | Цена за период: ключ — число месяцев, значение — цена, ₽. Только эти периоды принимают покупка и продление. |
| `data.trial` | object | Платный пробный тариф. |
| `data.trial.price_rub` | number | Цена пробного тарифа, ₽. |
| `data.trial.days` | int | Срок пробного тарифа, дней. |
| `data.trial.traffic_limit_gb` | int | Лимит трафика пробного тарифа, ГБ. |

**Обычно вызывают следом:** `POST /vpn/buy`.

#### POST /vpn/buy — Купить подписку

Идентификатор в документации: `vpn.buy`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/buy`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Создаёт новую подписку и списывает её цену с баланса. В ответе — `uuid` и ссылка подписки для клиента.

**Когда нужен.** Когда клиент оплатил VPN у тебя и ему нужна новая подписка.

> **Важно.** Передай **одно** из двух полей — `period_months` или `plan`. Оба сразу нельзя. Старые интеграции с `period_months` работают без изменений.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `period_months` | в теле | int | нет | Период в месяцах. Только значения из `/vpn/quote`. |  |  |
| `plan` | в теле | string | нет | Платный пробный тариф — значение `"trial"`. Срок и лимит трафика — в `/vpn/quote`. |  |  |

Тариф: 1 мес → `{"period_months":1}`, 3 мес → `{"period_months":3}`, 6 мес → `{"period_months":6}`, 12 мес → `{"period_months":12}`, Пробный → `{"plan":"trial"}`.

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/buy' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"period_months":1}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "plan": "months",
    "period_months": 1,
    "traffic_limit_gb": null,
    "price_rub": 200,
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "subscriptionUrl": "https://vpn.tunnelgate.org/xxxxxxxxxxxxxxxx",
    "expireAt": "2026-03-25T10:00:00.000Z",
    "expireAt_date": "25.03.2026"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.plan` | string | Какой тариф куплен: `months` — месячный. |
| `data.period_months` | int | Период в месяцах. |
| `data.traffic_limit_gb` | int \| null | Лимит трафика, ГБ. `null` — без лимита. |
| `data.price_rub` | number | Списано с баланса, ₽. |
| `data.uuid` | string | Идентификатор подписки. **Сохрани его** — все дальнейшие действия только по нему. |
| `data.subscriptionUrl` | string | Ссылка подписки — её получает клиент. |
| `data.expireAt` | string | Дата окончания в UTC, формат ISO 8601. |
| `data.expireAt_date` | string | Та же дата в виде ДД.ММ.ГГГГ — удобно показать клиенту. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `insufficient_funds` (Не хватает денег), `plan_unavailable` (Тариф недоступен).

**Обычно вызывают следом:** `GET /vpn/info`, `POST /vpn/renew`.

#### GET /vpn/info — Информация о подписке

Идентификатор в документации: `vpn.info`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/info`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает статус, срок, ссылку, лимит трафика и лимит устройств подписки.

**Когда нужен.** Чтобы показать клиенту состояние подписки или проверить, прошло ли продление после сетевого сбоя.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в строке запроса | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/vpn/info?uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "ACTIVE",
    "expireAt": "2026-06-25T10:00:00.000Z",
    "expireAt_date": "25.06.2026",
    "subscriptionUrl": "https://vpn.tunnelgate.org/xxxxxxxxxxxxxxxx",
    "trafficLimitBytes": 0,
    "hwidDeviceLimit": 5
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.status` | string | `ACTIVE` — активна, `DISABLED` — отключена, `LIMITED` — ограничена, `EXPIRED` — истекла. |
| `data.expireAt` | string | Дата окончания в UTC, формат ISO 8601. |
| `data.expireAt_date` | string | Та же дата в виде ДД.ММ.ГГГГ. |
| `data.subscriptionUrl` | string | Ссылка подписки. |
| `data.trafficLimitBytes` | int | Лимит трафика в байтах. `0` — без лимита. |
| `data.hwidDeviceLimit` | int | Сколько устройств можно подключить. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /vpn/renew`, `GET /vpn/hwid/devices`.

#### POST /vpn/renew — Продлить подписку

Идентификатор в документации: `vpn.renew`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/renew`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Продлевает подписку на выбранный период и списывает его цену с баланса.

**Когда нужен.** Когда клиент оплатил продление.

> **Важно.** Если подписка ещё действует, период добавляется к дате окончания. Если уже истекла — отсчёт идёт от текущего дня.

> **Совет.** Пробную подписку продлевают обычным месячным периодом — она становится полноценной. Значение `"trial"` здесь не принимается.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в теле | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |
| `period_months` | в теле | int | да | Период в месяцах. Только значения из `/vpn/quote`. | `3` | `1` — 1 мес, `3` — 3 мес, `6` — 6 мес, `12` — 12 мес |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/renew' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","period_months":3}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "period_months": 3,
    "price_rub": 500,
    "subscriptionUrl": "https://vpn.tunnelgate.org/xxxxxxxxxxxxxxxx",
    "expireAt": "2026-06-25T10:00:00.000Z",
    "expireAt_date": "25.06.2026"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.period_months` | int | На сколько месяцев продлено. |
| `data.price_rub` | number | Списано с баланса, ₽. |
| `data.subscriptionUrl` | string | Ссылка подписки. |
| `data.expireAt` | string | Новая дата окончания в UTC, формат ISO 8601. |
| `data.expireAt_date` | string | Та же дата в виде ДД.ММ.ГГГГ. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено), `insufficient_funds` (Не хватает денег).

**Обычно вызывают следом:** `GET /vpn/info`.

#### GET /vpn/hwid/devices — Список устройств

Идентификатор в документации: `vpn.hwid-devices`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/hwid/devices`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает подключённые устройства и лимит подписки.

**Когда нужен.** Когда клиент пишет, что не может подключить новое устройство, — проверить, не занят ли лимит.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в строке запроса | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/vpn/hwid/devices?uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "device_limit": 5,
    "connected": 1,
    "devices": [
      {
        "hwid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "userUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "platform": "Windows",
        "osVersion": "10.0.19045",
        "deviceModel": "Home-PC_x86_64",
        "userAgent": "Happ/1.5.2/Windows",
        "createdAt": "2026-01-21T14:42:27.559Z",
        "updatedAt": "2026-01-21T14:42:27.558Z"
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.device_limit` | int | Лимит устройств. |
| `data.connected` | int | Сколько устройств привязано к подписке. |
| `data.devices` | array | Список устройств. |
| `data.devices[].hwid` | string | Идентификатор устройства — нужен для сброса. |
| `data.devices[].platform` | string | Платформа: Windows, Android, iOS и т. д. |
| `data.devices[].osVersion` | string | Версия системы. |
| `data.devices[].deviceModel` | string | Модель устройства. |
| `data.devices[].userAgent` | string | Приложение и его версия. |
| `data.devices[].createdAt` | string | Когда устройство появилось в подписке, UTC. |
| `data.devices[].updatedAt` | string | Когда запись об устройстве обновлялась в последний раз, UTC. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /vpn/hwid/reset`, `POST /vpn/hwid/increase`.

#### POST /vpn/hwid/reset — Сбросить одно устройство

Идентификатор в документации: `vpn.hwid-reset`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/hwid/reset`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Отвязывает одно устройство от подписки и освобождает место под новое.

**Когда нужен.** Клиент сменил телефон или компьютер, и лимит устройств занят.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в теле | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |
| `hwid` | в теле | string | да | HWID устройства из списка устройств. (подсказка: hwid устройства) | `"abcdef123456"` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/hwid/reset' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","hwid":"abcdef123456"}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "hwid": "abcdef123456",
    "deleted": true
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.hwid` | string | Какое устройство отвязано. |
| `data.deleted` | bool | `true` — устройство отвязано. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `GET /vpn/hwid/devices`.

#### POST /vpn/hwid/reset-all — Сбросить все устройства

Идентификатор в документации: `vpn.hwid-reset-all`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/hwid/reset-all`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Отвязывает от подписки все устройства сразу.

**Когда нужен.** Когда проще начать с чистого листа: клиент сменил устройства и не помнит, какие из старых ещё заняты.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в теле | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/hwid/reset-all' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "deleted_all": true
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.deleted_all` | bool | `true` — все устройства отвязаны. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `GET /vpn/hwid/devices`.

#### GET /vpn/hwid/quote — Цены на увеличение лимита

Идентификатор в документации: `vpn.hwid-quote`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/hwid/quote`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Возвращает, на сколько устройств можно увеличить лимит и сколько это стоит.

**Когда нужен.** Чтобы показать клиенту варианты перед увеличением лимита.

##### Параметры

_Параметров нет._

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/vpn/hwid/quote' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "1": 200,
    "2": 350,
    "3": 500,
    "5": 750,
    "10": 1300
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.1` | number | Ключ — на сколько устройств увеличить лимит, значение — цена, ₽. |

**Обычно вызывают следом:** `POST /vpn/hwid/increase`.

#### POST /vpn/hwid/increase — Увеличить лимит устройств

Идентификатор в документации: `vpn.hwid-increase`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/hwid/increase`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Увеличивает лимит устройств подписки и списывает цену с баланса.

**Когда нужен.** Клиенту нужно подключить больше устройств, чем позволяет лимит.

> **Важно.** Оплата разовая: лимит увеличивается навсегда и сохраняется при продлениях.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в теле | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |
| `delta` | в теле | int | да | На сколько увеличить лимит. Только значения из `/vpn/hwid/quote`. | `2` | `1` — +1, `2` — +2, `3` — +3, `5` — +5, `10` — +10 |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/hwid/increase' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","delta":2}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "current_limit": 5,
    "delta": 2,
    "target_limit": 7,
    "price_rub": 350
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.current_limit` | int | Лимит до увеличения. |
| `data.delta` | int | На сколько увеличен. |
| `data.target_limit` | int | Новый лимит. |
| `data.price_rub` | number | Списано с баланса, ₽. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено), `insufficient_funds` (Не хватает денег).

**Обычно вызывают следом:** `GET /vpn/hwid/devices`.

#### POST /vpn/delete — Удалить подписку

Идентификатор в документации: `vpn.delete`. Полный адрес: `https://proxy.killa.cc/api/v1/vpn/delete`.
Стоимость вызова: необратимо.

**Что делает.** Удаляет подписку. Клиент теряет доступ, вернуть подписку нельзя.

**Когда нужен.** Только если подписка больше не нужна совсем. Чтобы отвязать устройства, удалять её не нужно — для этого есть сброс устройств.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `uuid` | в теле | string | да | UUID подписки. (подсказка: uuid подписки) | `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/vpn/delete' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "deleted": true
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.deleted` | bool | `true` — подписка удалена. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

### Серверные прокси — Выделенные и общие IPv4, IPv6

Прокси с фиксированным IP: выбираешь страну, тип адреса и срок — получаешь готовые данные для подключения.

Коротко: IPv4 и IPv6, общие и выделенные; HTTP(S) и SOCKS5 одновременно; Продление по ID прокси.

**Тип адреса — ipv.** `3` — IPv4 Shared (общий), `4` — IPv4 Private (выделенный), `6` — IPv6 Private (выделенный).

**Сроки — period, в днях.** IPv4: 7 · 14 · 30 · 60 · 90. IPv6: 3 · 7 · 14 · 30 · 60 · 90. Продление: 3 · 7 · 14 · 30 · 60 · 90.

**Протоколы.** `port_type: auto` — прокси понимают HTTP(S) и SOCKS5 одновременно. Протокол выбирается на стороне клиента, переключать ничего не нужно.

**ID прокси.** В ответе на покупку у каждой прокси есть `ids` — он нужен для продления. Храни его вместе с данными доступа.

#### GET /dedicated/quote — Посчитать стоимость

Идентификатор в документации: `dedicated.quote`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/quote`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Считает цену покупки: за всё количество и за одну прокси.

**Когда нужен.** Перед покупкой — показать цену и проверить, хватит ли баланса.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `ipv` | в строке запроса | int | да | Тип адреса. | `4` | `3` — IPv4 Shared, `4` — IPv4 Private, `6` — IPv6 |
| `period` | в строке запроса | int | да | Срок в днях. (единица: дн) | `30` | зависит от `ipv`: при `ipv = 3` → `7`, `14`, `30`, `60`, `90`; при `ipv = 4` → `7`, `14`, `30`, `60`, `90`; при `ipv = 6` → `3`, `7`, `14`, `30`, `60`, `90` |
| `count` | в строке запроса | int | да | Количество прокси. (подсказка: количество) | `10` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/dedicated/quote?ipv=4&period=30&count=10' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "period": 30,
    "count": 10,
    "ipv": 4,
    "price": 1800,
    "price_single": 180
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.price` | number | Цена за всё количество, ₽. |
| `data.price_single` | number | Цена за одну прокси, ₽. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `GET /dedicated/country`, `POST /dedicated/buy`.

#### GET /dedicated/country — Список стран

Идентификатор в документации: `dedicated.country`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/country`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Возвращает страны, в которых можно купить прокси выбранного типа.

**Когда нужен.** Чтобы показать клиенту выбор страны и взять `country_code` для покупки.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `ipv` | в строке запроса | int | да | Тип адреса. | `4` | `3` — IPv4 Shared, `4` — IPv4 Private, `6` — IPv6 |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/dedicated/country?ipv=4' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "ipv": 4,
    "countries": [
      {
        "country_code": "ua",
        "title": "🇺🇦 Украина"
      },
      {
        "country_code": "us",
        "title": "🇺🇸 США"
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.countries` | array | Доступные страны. |
| `data.countries[].country_code` | string | Код страны — передаётся в покупку и в `/dedicated/count`. |
| `data.countries[].title` | string | Название с флагом — можно показать клиенту как есть. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `GET /dedicated/count`.

#### GET /dedicated/count — Сколько прокси доступно

Идентификатор в документации: `dedicated.count`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/count`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает, сколько прокси выбранного типа есть в стране прямо сейчас.

**Когда нужен.** Перед крупной покупкой — убедиться, что нужное количество есть в наличии.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `country_code` | в строке запроса | string | да | Код страны из `/dedicated/country`. (подсказка: ru) | `"ru"` |  |
| `ipv` | в строке запроса | int | да | Тип адреса. | `4` | `3` — IPv4 Shared, `4` — IPv4 Private, `6` — IPv6 |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/dedicated/count?country_code=ru&ipv=4' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "country_code": "ru",
    "ipv": 4,
    "count": 1233
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.count` | int | Сколько прокси доступно. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `POST /dedicated/buy`.

#### POST /dedicated/buy — Купить прокси

Идентификатор в документации: `dedicated.buy`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/buy`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Покупает прокси и списывает их цену с баланса. В ответе — готовые данные для подключения.

**Когда нужен.** Когда клиент оплатил прокси у тебя.

> **Важно.** `port_type: auto` — прокси понимают HTTP(S) и SOCKS5 одновременно. Переключать ничего не нужно: протокол выбирается на стороне клиента.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `country_code` | в теле | string | да | Код страны из `/dedicated/country`. (подсказка: ru) | `"ru"` |  |
| `ipv` | в теле | int | да | Тип адреса. | `4` | `3` — IPv4 Shared, `4` — IPv4 Private, `6` — IPv6 |
| `period` | в теле | int | да | Срок в днях. (единица: дн) | `30` | зависит от `ipv`: при `ipv = 3` → `7`, `14`, `30`, `60`, `90`; при `ipv = 4` → `7`, `14`, `30`, `60`, `90`; при `ipv = 6` → `3`, `7`, `14`, `30`, `60`, `90` |
| `count` | в теле | int | да | Количество прокси. (подсказка: количество) | `1` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/dedicated/buy' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"country_code":"ru","ipv":4,"period":30,"count":1}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "check_id": "b_8300069",
    "order_id": 13765429,
    "price_rub": 180,
    "port_type": "auto",
    "proxies": [
      {
        "ids": 36400089,
        "ip": "203.0.113.24",
        "port": "10900",
        "username": "username",
        "password": "password",
        "date_end": "2026-01-16 05:42:18"
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.check_id` | string | Номер покупки. |
| `data.order_id` | int | Номер заказа. |
| `data.price_rub` | number | Списано с баланса, ₽. |
| `data.port_type` | string | `auto` — HTTP(S) и SOCKS5 одновременно. |
| `data.proxies` | array | Купленные прокси. |
| `data.proxies[].ids` | int | ID прокси — нужен для продления. |
| `data.proxies[].ip` | string | IP-адрес. |
| `data.proxies[].port` | string | Порт. |
| `data.proxies[].username` | string | Логин. |
| `data.proxies[].password` | string | Пароль. |
| `data.proxies[].date_end` | string | Дата окончания, формат ГГГГ-ММ-ДД чч:мм:сс. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `insufficient_funds` (Не хватает денег).

**Обычно вызывают следом:** `GET /dedicated/prolong/quote`.

#### GET /dedicated/prolong/quote — Стоимость продления

Идентификатор в документации: `dedicated.prolong-quote`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/prolong/quote`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Считает цену продления для списка прокси: общую и по каждой.

**Когда нужен.** Перед продлением — показать цену клиенту.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `ids` | в строке запроса | int[] | да | ID прокси из ответа на покупку, через запятую. (подсказка: 36400089, 36400090) | `[36400089,36400090]` |  |
| `period` | в строке запроса | int | да | Срок продления в днях. (единица: дн) | `3` | `3`, `7`, `14`, `30`, `60`, `90` |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/dedicated/prolong/quote?ids=36400089&ids=36400090&period=3' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "period": 3,
    "total_price_rub": 8.9,
    "items": [
      {
        "ids": 36400089,
        "ipv": 6,
        "price_rub": 4.45
      },
      {
        "ids": 36400090,
        "ipv": 6,
        "price_rub": 4.45
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.total_price_rub` | number | Цена продления всех прокси, ₽. |
| `data.items` | array | Цена по каждой прокси. |
| `data.items[].ids` | int | ID прокси. |
| `data.items[].ipv` | int | Тип адреса. |
| `data.items[].price_rub` | number | Цена продления этой прокси, ₽. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `POST /dedicated/prolong`.

#### POST /dedicated/prolong — Продлить прокси

Идентификатор в документации: `dedicated.prolong`. Полный адрес: `https://proxy.killa.cc/api/v1/dedicated/prolong`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Продлевает прокси на выбранный срок и списывает цену с баланса.

**Когда нужен.** Когда клиент оплатил продление.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `ids` | в теле | int[] | да | Список ID прокси из ответа на покупку. В поле ниже — через запятую. (подсказка: 36400089, 36400090) | `[36400089,36400090]` |  |
| `period` | в теле | int | да | Срок продления в днях. (единица: дн) | `3` | `3`, `7`, `14`, `30`, `60`, `90` |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/dedicated/prolong' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ids":[36400089,36400090],"period":3}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "period": 3,
    "total_price_rub": 8.9,
    "items": [
      {
        "ids": 36400089,
        "date_end": "2026-01-19 05:42:18"
      },
      {
        "ids": 36400090,
        "date_end": "2026-01-19 05:42:18"
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.total_price_rub` | number | Списано с баланса, ₽. |
| `data.items[].ids` | int | ID прокси. |
| `data.items[].date_end` | string | Новая дата окончания. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `insufficient_funds` (Не хватает денег).

### Резидентные прокси — Трафик, локации, прокси-листы

Продаёшь трафик в гигабайтах, а клиент сам собирает прокси-лист под нужные страны, города и провайдеров.

Коротко: Трафик по гигабайтам; Страны, города, провайдеры; Доступ по паролю или по IP.

**Пулы — pool_type.** `residential` — резидентные, `datacenter` — датацентр, `mobile` — мобильные, `residential_premium` — премиум резидентные.

**Ключ — subuser_id.** `telegram_id` клиента передаётся только при первой покупке — чтобы привязать подписку к клиенту. В ответе приходит `subuser_id`, и дальше все методы работают только с ним. Чужой или несуществующий `subuser_id` вернёт `404 not_found`.

**Одна подписка на пул.** Для пары `telegram_id` + `pool_type` подписка создаётся один раз: повторная покупка вернёт `409 already_exists`. Пополняй её через `/residential/traffic/add`.

**Прокси-лист.** Протокол `http` или `socks5`. Тип `sticky` держит IP `session_ttl` минут, `rotating` меняет IP на каждом запросе. Формат строк: `1` — `hostname:port:login:password`, `2` — `login:password@hostname:port`, `3` — `hostname:port`.

#### GET /residential/traffic/quote — Посчитать стоимость трафика

Идентификатор в документации: `residential.traffic-quote`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/traffic/quote`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Считает цену трафика с учётом скидки.

**Когда нужен.** Перед покупкой или пополнением — показать цену клиенту.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `pool_type` | в строке запроса | string | да | Тип пула. | `"residential"` | `residential` — Резидентные, `datacenter` — Датацентр, `mobile` — Мобильные, `residential_premium` — Премиум |
| `gb` | в строке запроса | int | да | Объём, ГБ. (подсказка: объём, ГБ) | `100` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/residential/traffic/quote?pool_type=residential&gb=100' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "pool_type": "residential",
    "gb": 100,
    "price_per_gb_rub": 99,
    "subtotal_rub": 9900,
    "discount_percent": 5,
    "discount_rub": 495,
    "price_rub": 9405
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.price_per_gb_rub` | number | Цена за 1 ГБ, ₽. |
| `data.subtotal_rub` | number | Цена без скидки, ₽. |
| `data.discount_percent` | int | Скидка, %. |
| `data.discount_rub` | number | Скидка, ₽. |
| `data.price_rub` | number | Итоговая цена, ₽. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `POST /residential/traffic/buy`.

#### POST /residential/traffic/buy — Купить трафик

Идентификатор в документации: `residential.traffic-buy`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/traffic/buy`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Создаёт подписку клиента на пул и начисляет трафик. В ответе — `subuser_id`, логин и пароль.

**Когда нужен.** Первая покупка клиента в этом пуле. Дальше пополняй через `/residential/traffic/add`.

> **Внимание.** Для пары `telegram_id` + `pool_type` подписка создаётся один раз. Повторная покупка вернёт `409 already_exists` — для пополнения есть `/residential/traffic/add`.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `pool_type` | в теле | string | да | Тип пула. | `"residential"` | `residential` — Резидентные, `datacenter` — Датацентр, `mobile` — Мобильные, `residential_premium` — Премиум |
| `gb` | в теле | int | да | Объём, ГБ. (подсказка: объём, ГБ) | `100` |  |
| `telegram_id` | в теле | int | да | Telegram ID конечного клиента. (подсказка: Telegram ID клиента) | `123456789` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/traffic/buy' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pool_type":"residential","gb":100,"telegram_id":123456789}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential",
      "login": "user_login",
      "password": "user_password"
    },
    "price_rub": 9405,
    "price_per_gb_rub": 99,
    "subtotal_rub": 9900,
    "discount_percent": 5,
    "discount_rub": 495,
    "traffic_added_gb": 100,
    "traffic_balance_gb": 100
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.subuser.subuser_id` | int | Идентификатор клиента. **Сохрани его** — дальше все методы работают только с ним. |
| `data.subuser.login` | string | Логин для прокси. |
| `data.subuser.password` | string | Пароль для прокси. |
| `data.price_rub` | number | Списано с баланса, ₽. |
| `data.traffic_added_gb` | int | Сколько трафика начислено, ГБ. |
| `data.traffic_balance_gb` | number | Остаток трафика после покупки, ГБ. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `insufficient_funds` (Не хватает денег), `already_exists` (409 — Уже существует).

**Обычно вызывают следом:** `POST /residential/locations/{level}`, `POST /residential/proxies/generate`.

#### POST /residential/traffic/add — Пополнить трафик

Идентификатор в документации: `residential.traffic-add`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/traffic/add`.
Стоимость вызова: спишет деньги с баланса.

**Что делает.** Начисляет клиенту дополнительный трафик и списывает цену с баланса.

**Когда нужен.** Трафик заканчивается или клиент докупает объём.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |
| `gb` | в теле | int | да | Объём, ГБ. (подсказка: объём, ГБ) | `100` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/traffic/add' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345,"gb":100}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "price_rub": 9405,
    "price_per_gb_rub": 99,
    "subtotal_rub": 9900,
    "discount_percent": 5,
    "discount_rub": 495,
    "traffic_added_gb": 100,
    "traffic_balance_gb": 200
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.price_rub` | number | Списано с баланса, ₽. |
| `data.traffic_added_gb` | int | Сколько трафика начислено, ГБ. |
| `data.traffic_balance_gb` | number | Остаток трафика после пополнения, ГБ. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено), `insufficient_funds` (Не хватает денег).

**Обычно вызывают следом:** `GET /residential/traffic/balance`.

#### GET /residential/traffic/balance — Остаток трафика

Идентификатор в документации: `residential.traffic-balance`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/traffic/balance`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает, сколько трафика осталось у клиента.

**Когда нужен.** Чтобы вовремя предложить клиенту пополнение.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в строке запроса | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/residential/traffic/balance?subuser_id=12345' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "traffic_gb": 8.5
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.subuser` | object | Клиент: `subuser_id`, `telegram_id`, `pool_type`. |
| `data.traffic_gb` | number | Остаток трафика, ГБ. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /residential/traffic/add`.

#### POST /residential/locations/{level} — Локации

Идентификатор в документации: `residential.locations`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/locations/{level}`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Возвращает доступные страны, регионы, города, почтовые индексы или провайдеров (ASN) — для фильтров прокси-листа.

**Когда нужен.** Чтобы клиент выбрал, откуда нужны адреса, перед генерацией прокси-листа.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `level` | в адресе | string | да | Что получить | `"cities"` | `countries` — Страны, `states` — Регионы, `cities` — Города, `zipcodes` — Индексы, `asns` — ASN |
| `pool_type` | в теле | string | да | Тип пула. | `"residential"` | `residential` — Резидентные, `datacenter` — Датацентр, `mobile` — Мобильные, `residential_premium` — Премиум |
| `countries` | в теле | string[] | да | Список стран. В поле ниже — через запятую. (только для `states`, `cities`, `zipcodes`, `asns`; подсказка: US, DE) | `["US"]` |  |
| `states` | в теле | string[] | нет | Фильтр по штатам и регионам — список. В поле ниже — через запятую. (только для `cities`, `zipcodes`, `asns`; подсказка: California) | `["California"]` |  |
| `cities` | в теле | string[] | нет | Фильтр по городам — список. В поле ниже — через запятую. (только для `zipcodes`, `asns`; подсказка: Los Angeles) |  |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/locations/cities' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"pool_type":"residential","countries":["US"]}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "pool_type": "residential",
    "countries": [
      "us"
    ],
    "states": [
      "california"
    ],
    "items": [
      {
        "code": "alameda",
        "name": "Alameda",
        "count": 16
      },
      {
        "code": "alhambra",
        "name": "Alhambra",
        "count": 9
      }
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.countries` | array | Какие страны применены как фильтр. |
| `data.states` | array | Какие регионы применены как фильтр. |
| `data.items` | array | Найденные локации. Формат один для всех уровней. |
| `data.items[].code` | string | Код — его передают в генерацию прокси-листа. |
| `data.items[].name` | string | Название для показа клиенту. |
| `data.items[].count` | int | Количество доступных адресов в локации. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос).

**Обычно вызывают следом:** `POST /residential/proxies/generate`.

#### POST /residential/proxies/generate — Сгенерировать прокси-лист

Идентификатор в документации: `residential.proxies-generate`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/proxies/generate`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Собирает прокси-лист клиента: адреса через домен и через IP в выбранном формате.

**Когда нужен.** Когда клиенту нужны строки для подключения. Генерация бесплатна — трафик расходуется, когда клиент работает через прокси.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |
| `countries` | в теле | string[] | да | Список стран. В поле ниже — через запятую. (подсказка: ru, de) | `["ru"]` |  |
| `protocol` | в теле | string | нет | Протокол. По умолчанию `http`. |  | `http`, `socks5`; можно не указывать |
| `type` | в теле | string | нет | `sticky` — IP держится `session_ttl` минут, `rotating` — новый IP на каждый запрос. |  | `sticky`, `rotating`; можно не указывать |
| `session_ttl` | в теле | int | нет | Время жизни сессии в минутах. Только для `type = sticky`. (подсказка: минуты) |  |  |
| `anonymous` | в теле | bool | нет | Анонимность. |  | `true` — Да, `false` — Нет; можно не указывать |
| `quantity` | в теле | int | нет | Сколько строк сгенерировать. По умолчанию `1`. (подсказка: 1) | `2` |  |
| `format_id` | в теле | int | нет | Формат строк: `1` — `hostname:port:login:password`, `2` — `login:password@hostname:port`, `3` — `hostname:port`. |  | `1` — host:port:login:pass, `2` — login:pass@host:port, `3` — host:port; можно не указывать |
| `states` | в теле | string[] | нет | Фильтр по штатам и регионам. (подсказка: California) |  |  |
| `cities` | в теле | string[] | нет | Фильтр по городам. (подсказка: Los Angeles) |  |  |
| `zipcodes` | в теле | string[] | нет | Фильтр по почтовым индексам. (подсказка: 90001) |  |  |
| `asns` | в теле | string[] | нет | Фильтр по провайдерам (ASN). (подсказка: AS7922) |  |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/proxies/generate' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345,"countries":["ru"]}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "params": {
      "countries": "ru",
      "cities": "",
      "states": "",
      "zipcodes": "",
      "asns": "",
      "anonymous": "0",
      "type": "sticky",
      "protocol": "http",
      "format": "hostname:port:login:password",
      "quantity": "2",
      "session_ttl": "10"
    },
    "domain": "gw.tunnelgate.org:10000:login:password\n\ngw.tunnelgate.org:10001:login:password",
    "ip": "74.81.81.81:10000:login:password\n\n74.81.81.81:10001:login:password"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.params` | object | С какими параметрами собран лист — значения строками. |
| `data.domain` | string | Прокси-лист с адресом через домен. Строки разделены пустой строкой. |
| `data.ip` | string | Тот же лист с адресом через IP. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /residential/whitelist/add`, `POST /residential/proxies/rotate-ip`.

#### POST /residential/proxies/rotate-ip — Сменить IP

Идентификатор в документации: `residential.proxies-rotate-ip`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/proxies/rotate-ip`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Меняет IP у sticky-сессий клиента.

**Когда нужен.** IP в sticky-сессии перестал подходить и нужен новый, не дожидаясь `session_ttl`.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/proxies/rotate-ip' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "rotated": true,
    "result": {
      "login": "examplelogin",
      "status": "ok",
      "message": "ok",
      "elapsed": "00:00:00.0018686"
    }
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.rotated` | bool | `true` — IP сменён. |
| `data.result` | object | Ответ поставщика: логин, статус, сообщение, время выполнения. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

#### GET /residential/whitelist — Разрешённые IP

Идентификатор в документации: `residential.whitelist`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/whitelist`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает IP-адреса, с которых клиент подключается к прокси без логина и пароля.

**Когда нужен.** Чтобы проверить, какие адреса уже добавлены.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в строке запроса | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/residential/whitelist?subuser_id=12345' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "allowed_ips": [
      "1.2.3.4",
      "5.6.7.8"
    ]
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.allowed_ips` | array | Разрешённые IP-адреса. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /residential/whitelist/add`.

#### POST /residential/whitelist/add — Добавить IP

Идентификатор в документации: `residential.whitelist-add`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/whitelist/add`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Разрешает подключаться к прокси с этого IP без логина и пароля.

**Когда нужен.** Клиенту удобнее доступ по IP — например, для формата строк `hostname:port`.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |
| `ip` | в теле | string | да | IP-адрес. (подсказка: 1.2.3.4) | `"1.2.3.4"` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/whitelist/add' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345,"ip":"1.2.3.4"}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "ip": "1.2.3.4"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.ip` | string | Добавленный IP. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `GET /residential/whitelist`.

#### POST /residential/whitelist/remove — Убрать IP

Идентификатор в документации: `residential.whitelist-remove`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/whitelist/remove`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Запрещает подключение без пароля с этого IP.

**Когда нужен.** Клиент сменил адрес или доступ по IP больше не нужен.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |
| `ip` | в теле | string | да | IP-адрес. (подсказка: 1.2.3.4) | `"1.2.3.4"` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/whitelist/remove' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345,"ip":"1.2.3.4"}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "ip": "1.2.3.4"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.ip` | string | Убранный IP. |

**Возможные ошибки:** `invalid_request` (400 — Неверный запрос), `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `GET /residential/whitelist`.

#### GET /residential/password — Текущий пароль

Идентификатор в документации: `residential.password`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/password`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Возвращает логин и текущий пароль клиента для прокси.

**Когда нужен.** Клиент потерял данные для подключения.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в строке запроса | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/residential/password?subuser_id=12345' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "login": "login",
    "password": "current_password"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.login` | string | Логин. |
| `data.password` | string | Текущий пароль. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

**Обычно вызывают следом:** `POST /residential/password/reset`.

#### POST /residential/password/reset — Сбросить пароль

Идентификатор в документации: `residential.password-reset`. Полный адрес: `https://proxy.killa.cc/api/v1/residential/password/reset`.
Стоимость вызова: меняет состояние, денег не спишет.

**Что делает.** Выдаёт клиенту новый пароль для прокси.

**Когда нужен.** Пароль мог утечь. После сброса обнови пароль у клиента.

##### Параметры

| Параметр | Где | Тип | Обяз. | Описание | Пример | Допустимые значения |
|---|---|---|---|---|---|---|
| `subuser_id` | в теле | int | да | Идентификатор клиента. (подсказка: subuser_id) | `12345` |  |

##### Пример запроса

```bash
curl -s -X POST 'https://proxy.killa.cc/api/v1/residential/password/reset' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"subuser_id":12345}'
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "subuser": {
      "subuser_id": 12345,
      "telegram_id": 123456789,
      "pool_type": "residential"
    },
    "login": "login",
    "password": "new_password"
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.login` | string | Логин. |
| `data.password` | string | Новый пароль. |

**Возможные ошибки:** `not_found` (404 — Не найдено).

### Аккаунт — Баланс и расходы

Всё, что касается самого аккаунта: сколько денег на балансе и сколько ушло через API.

**Покупки — от имени владельца токена.** Доступ к API строго в рамках аккаунта владельца токена. Покупки и списания выполняются от его имени.

#### GET /balance — Баланс

Идентификатор в документации: `account.balance`. Полный адрес: `https://proxy.killa.cc/api/v1/balance`.
Стоимость вызова: бесплатно, ничего не меняет.

**Что делает.** Показывает, сколько денег на балансе и сколько всего потрачено через API.

**Когда нужен.** Перед покупкой — убедиться, что денег хватит. После сетевого сбоя — проверить, прошло ли списание.

##### Параметры

_Параметров нет._

##### Пример запроса

```bash
curl -s 'https://proxy.killa.cc/api/v1/balance' \
  -H "Authorization: Bearer $TOKEN"
```

##### Пример ответа

```json
{
  "ok": true,
  "data": {
    "balance_rub": 1234.56,
    "api_spent_rub": 1234.56
  }
}
```

##### Поля ответа

| Поле | Тип | Описание |
|---|---|---|
| `data.balance_rub` | number | Баланс, ₽. |
| `data.api_spent_rub` | number | Сколько всего потрачено через API, ₽. |

**Обычно вызывают следом:** `GET /vpn/quote`, `GET /dedicated/quote`, `GET /residential/traffic/quote`.

## Коды ошибок

> Что пошло не так и что с этим делать. Вставь ответ API в разбор — и получишь объяснение.

### Как устроена ошибка

При ошибке `ok` равно `false`, а в `error` — код, текст и подробности:

```json
{
  "ok": false,
  "error": {
    "code": "invalid_token",
    "message": "Unauthorized",
    "details": null
  }
}
```

Строй логику на `error.code`, а `error.message` показывай людям. `invalid_token` и `internal_error` может вернуть любой метод.

### Повторять или нет

- `provider_error` и ответы 5xx — повтори через 10–30 секунд, не больше 1–3 попыток.
- `400` — не повторяй, исправь запрос.
- `401` — проверь токен или сбрось его и обнови в интеграции.
- Покупки и продления повторяй только после проверки баланса и состояния услуги.

| Код | HTTP | Что значит | Когда приходит | Что делать | Повтор |
|---|---|---|---|---|---|
| `invalid_token` | 401 | Токен не принят | Нет заголовка `Authorization`, неверный формат (нужно `Bearer <token>`) или токен сброшен. | Проверь заголовок. Если токен сбрасывали — возьми новый в боте: **Профиль → API**. | не повторять |
| `invalid_request` | 400 | Неверный запрос | Не хватает обязательного параметра, неверный тип или значение не из допустимых. | Сверь параметры с описанием метода. Тот же запрос повторять бесполезно. | не повторять |
| `not_found` | 404 | Не найдено | `uuid` или `subuser_id` не существует или принадлежит другому владельцу токена. | Проверь идентификатор — нужен тот, что вернулся в ответе на покупку. | не повторять |
| `already_exists` | 409 | Уже существует | Резидентная подписка для этой пары `telegram_id` + `pool_type` уже есть. | Пополняй существующую подписку через `/residential/traffic/add`. | не повторять |
| `insufficient_funds` | — | Не хватает денег | На балансе меньше, чем стоит покупка. | Пополни баланс в боте или уменьши объём покупки. | после пополнения баланса |
| `plan_unavailable` | — | Тариф недоступен | Тариф временно отключён — например, пробный VPN. | Выбери другой тариф или попробуй позже. | позже |
| `provider_error` | — | Сбой у поставщика | Временная ошибка на стороне поставщика услуги. | Повтори через 10–30 секунд, не больше 1–3 попыток. Покупку повторяй только после проверки баланса и состояния услуги. | повтор через 10–30 с |
| `internal_error` | — | Внутренняя ошибка | Сбой внутри сервиса. | Аккуратно повтори позже. Покупку повторяй только после проверки баланса и состояния услуги. Если ошибка повторяется — напиши в поддержку. | повтор через 10–30 с |

### HTTP-статусы

| Статус | Что значит | Пояснение |
|---|---|---|
| 200 | Успех | Смотри поле `ok` и данные в `data`. |
| 400 | Неверный запрос | Исправь параметры, типы и формат. Не повторяй тот же запрос. |
| 401 | Токен не принят | Проверь `Authorization`, при необходимости сбрось токен в боте. |
| 404 | Не найдено | Чужой или несуществующий `uuid` / `subuser_id`. |
| 409 | Уже существует | Повторная покупка резидентной подписки для той же пары. |
| 5xx | Сбой сервиса или поставщика | Повтори позже: через 10–30 секунд, 1–3 попытки. Покупку и продление — только после проверки баланса. |

## Что нового

> Изменения API и документации.

### 03.11.2026 · Документация для нейросетей

- **Вся документация одним файлом** — кнопка «Скачать документацию» на главной или адрес `/llms-full.txt`: методы, параметры, примеры запросов и ответов, коды ошибок и правила. Приложи файл к чату с нейросетью или дай ей ссылку — она напишет интеграцию сама.
- **Описание OpenAPI 3.1** — `/openapi.json`: готовый клиент из генератора кода, импорт в Postman и Insomnia.
- **Сценарий «Подключить через нейросеть»** — с готовым текстом запроса, который остаётся только скопировать.

### 26.09.2026 · Новая документация

- **Сценарии «от и до»** — как продать VPN, выдать серверные прокси и собрать резидентный прокси-лист.
- **Метки у методов** — сразу видно, какой запрос бесплатный, какой меняет доступ, а какой спишет деньги.
- **Примеры под твой запрос** — выбери значения параметров в справочнике, и код на cURL, Python, Node.js и PHP соберётся сам.
- **Разбор ответа** — вставь ответ API на странице [Ошибки](https://proxy-docs.killa.cc/errors) и получи объяснение.
- **Поиск по всему** — по методам, полям, кодам ошибок и сценариям: `Ctrl K` или `/`.
- **Телефон** — отдельный удобный режим. Сайт можно добавить на экран как приложение и читать без интернета.

API не менялся: все интеграции работают как раньше.

## Поддержка

> Чем точнее данные — тем быстрее решение.

### Что подготовить

- твой Telegram ID или @username;
- метод и параметры запроса;
- полный ответ с ошибкой (`ok: false`).

Проще всего собрать обращение ниже: форма сложит всё в одно сообщение, останется вставить его в чат поддержки.