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

# API — Прокси

> REST API бота прокси: каталог, цена, подписки, доступы, покупка статики, продление

Базовый URL: `https://panel.scamprojecttest.xyz/proxy/api/v1`. Общие правила (авторизация, лимиты, ошибки, идемпотентность) — в [обзоре](/api).

<Note>
  В v1 доступны покупка **статичных** прокси (ISP/Datacenter), продление и все операции чтения. Покупка ротационных (residential/mobile) через API пока не выведена — она требует интерактивного подбора гео в боте.
</Note>

## Аккаунт

| Метод | Путь                       | Scope        | Описание                            |
| ----- | -------------------------- | ------------ | ----------------------------------- |
| GET   | `/users/me`                | `proxy:read` | Профиль ключа и пользователя        |
| GET   | `/users/{user_id}/balance` | `proxy:read` | Баланс                              |
| GET   | `/transactions`            | `proxy:read` | Транзакции (пагинация, `?user_id=`) |
| GET   | `/referrals`               | `proxy:read` | Реферальная статистика              |

## Каталог и расчёт

### Каталог

`GET /proxy/catalog` · scope `proxy:read`

```json theme={"system"}
{ "categories": [
  { "category":"isp","label":"ISP","unit":"IP","kind":"static","live":true,"sample_price_usd":"2.50" },
  { "category":"residential","label":"Резидентные","unit":"GB","kind":"rotating","live":true,"sample_price_usd":"2.00" }
] }
```

Цена тиражная (чем больше объём, тем дешевле за единицу); `sample_price_usd` — цена первого тира. Актуальные тиры считай через `/proxy/quote`.

### Расчёт цены

`POST /proxy/quote` · scope `proxy:read` · тело `{ "category":"isp", "quantity":5 }`

```json theme={"system"}
{ "category":"isp","quantity":5,"unit":"IP","price_usd":"12.50","available":true }
```

## Подписки

| Метод | Путь                                    | Scope        | Описание                        |
| ----- | --------------------------------------- | ------------ | ------------------------------- |
| GET   | `/proxy/subscriptions`                  | `proxy:read` | Список (пагинация, `?user_id=`) |
| GET   | `/proxy/subscriptions/{id}`             | `proxy:read` | Карточка подписки               |
| GET   | `/proxy/subscriptions/{id}/credentials` | `proxy:read` | Доступы                         |

Ответ `credentials` зависит от типа:

```json theme={"system"}
// статичные
{ "subscription_id": 9, "kind": "static",
  "static_proxies": [ { "ip":"1.2.3.4","port_http":8080,"port_socks":1080,"login":"u","password":"p" } ] }

// ротационные
{ "subscription_id": 9, "kind": "rotating",
  "upstream_login":"u","upstream_endpoint":"gw.example:7000","upstream_password":"p" }
```

<Note>
  Доступы возвращаются с `Cache-Control: no-store` — не кэшируй и не логируй их.
</Note>

## Покупка и продление (деньги)

<Warning>
  Требуют `API_MONEY_ENABLED`, scope `proxy:buy`, заголовок `Idempotency-Key` и (если включена) подпись `X-Signature`.
</Warning>

### Купить статичные прокси

`POST /proxy/static` · scope `proxy:buy` · **деньги**

| Поле           | Тип           | Описание                           |
| -------------- | ------------- | ---------------------------------- |
| `category`     | строка        | `isp` или `datacenter`             |
| `country_name` | строка (1–64) | Страна (название или ISO-код)      |
| `quantity`     | число 1–500   | Количество IP                      |
| `auto_renew`   | bool          | Автопродление (по умолчанию false) |
| `user_id`      | число         | Обязателен для operator-ключа      |

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/proxy/api/v1/proxy/static" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: prx-2026-06-09-001" \
  -H "Content-Type: application/json" \
  -d '{"category":"isp","country_name":"United States","quantity":5}'
```

```json theme={"system"}
{ "status":"ok","subscription_id":9,"order_id":120,"price_usd":"12.50","quantity":5,"country":"US" }
```

Поле `status`: `ok` (выдано), `provisioning` (выдаётся), `insufficient` (`402`, не хватает баланса), `provider_misconfig` (`503`), `bad_request` (`400`).

### Продлить подписку

`POST /proxy/subscriptions/{id}/renew` · scope `proxy:buy` · **деньги**

```json theme={"system"}
{ "subscription_id":9,"status":"ok","price_usd":"12.50","new_expires_at":"2026-07-09T..." }
```

## Управление (write)

### Автопродление

`POST /proxy/subscriptions/{id}/auto-renew` · scope `proxy:write` · тело `{ "auto_renew": true }`. Возвращает обновлённую карточку подписки.

## Пополнение баланса (деньги)

`POST /deposits` · scope `deposits:write` · **деньги** → `201`. Тело и поведение — как в [доменах](/api/domains). Статус: `GET /deposits/{provider}/{external_id}`.

## Операторские эндпоинты

Только operator (`admin:*`): `/admin/users/{id}/balance`, `/admin/users/{id}/ban`, `/admin/deposits/{tx}/mark-completed`, `/admin/deposits/{tx}/mark-failed` — см. [домены](/api/domains#операторские-эндпоинты).