> ## 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 — Хостинг (VPS)

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

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

## Аккаунт

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

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

### Каталог

`GET /vps/catalog` · scope `vps:read` — тарифы, локации, ОС, периоды.

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

`POST /vps/quote` · scope `vps:read`

```json theme={"system"}
{ "plan_code": "vps-2", "period_months": 3, "os_code": "ubuntu-22" }
```

```json theme={"system"}
{ "plan_code":"vps-2","period_months":3,"os_code":"ubuntu-22","price_usd":"28.61","os_supported":true }
```

## Серверы

| Метод | Путь                    | Scope      | Описание                            |
| ----- | ----------------------- | ---------- | ----------------------------------- |
| GET   | `/vps`                  | `vps:read` | Список VPS (пагинация, `?user_id=`) |
| GET   | `/vps/{id}`             | `vps:read` | Карточка VPS                        |
| GET   | `/vps/{id}/credentials` | `vps:read` | IP, порт, root-логин/пароль         |
| GET   | `/vps/{id}/console`     | `vps:read` | Ссылка на веб-консоль               |

<Note>
  `credentials` и `password` возвращают расшифрованные секреты с заголовком `Cache-Control: no-store`. Не логируйте и не кэшируйте их.
</Note>

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

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

### Купить VPS

`POST /vps` · scope `vps:buy` · **деньги** · async → `202`

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/hosting/api/v1/vps" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: vps-2026-06-09-001" \
  -H "Content-Type: application/json" \
  -d '{"plan_code":"vps-2","location_code":"de","os_code":"ubuntu-22","period_months":1}'
```

```json theme={"system"}
{ "batch_id": "checkout:5678", "accepted": 1, "status": "pending" }
```

Operator указывает `user_id` в теле. Провижининг идёт фоном; статус — `GET /batches/checkout:5678`.

### Продлить VPS

`POST /vps/{id}/renew` · scope `vps:buy` · **деньги** · тело `{ "period_months": 3 }`

```json theme={"system"}
{ "vps_id": 77, "charged_usd": "28.61", "expires_at": "2026-09-09T..." }
```

### Bulk

| Метод | Путь               | Scope              | Описание                                              |
| ----- | ------------------ | ------------------ | ----------------------------------------------------- |
| POST  | `/vps/buy:bulk`    | `vps:buy` (деньги) | Массовая покупка `{items:[...]}` → `202`              |
| POST  | `/vps/renew:bulk`  | `vps:buy` (деньги) | Массовое продление `{items:[{vps_id,period_months}]}` |
| POST  | `/vps/status:bulk` | `vps:read`         | Статусы `{ids:[...]}`                                 |

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

scope `vps:write`. Не двигают баланс, идемпотентность не требуется.

| Метод  | Путь                       | Описание                                       |
| ------ | -------------------------- | ---------------------------------------------- |
| POST   | `/vps/{id}/power/{action}` | `reboot` · `start` · `stop` · `power-toggle`   |
| POST   | `/vps/{id}/reinstall`      | Переустановка ОС `{os_code}`                   |
| POST   | `/vps/{id}/password`       | Сменить root-пароль (вернёт новый, `no-store`) |
| DELETE | `/vps/{id}`                | Удалить сервер                                 |

```bash theme={"system"}
curl -X POST "https://panel.scamprojecttest.xyz/hosting/api/v1/vps/77/power/reboot" \
  -H "Authorization: Bearer $KEY"
```

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

`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#операторские-эндпоинты).