API для разработчиков

VDSok Client API — REST-интерфейс поверх HTTPS с JSON-телами. Через него доступно всё, что клиент делает в кабинете, кроме тикетов, выделенных серверов, суб-аккаунтов и редактирования профиля: баланс и счета, каталог VDS, серверы (заказ, продление, питание, переустановка, IP, PTR, SSH-ключи, удаление с возвратом), домены, API-ключи и вебхуки.

Базовый URL

Все пути в этом руководстве относительны:

https://vdsok.guru/api/v1

Версия живёт в пути. Ломающие изменения уйдут в /v2; v1 только растёт: новые поля и эндпоинты могут появиться в любой момент, поэтому неизвестные поля в ответах игнорируйте.

Соглашения

• Только JSON. Тело POST/PUT/PATCH не в application/json отклоняется с 415, тело больше 64 КБ — с 413.
• Время — RFC 3339 в UTC с суффиксом Z: 2026-09-15T10:00:00Z.
• Деньги — десятичная строка с 2–4 знаками после точки, никогда не float, всегда рядом с полем currency (ISO 4217).
• server_id — id виртуальной машины в панели, то же число, что кабинет показывает в URL.
• Каждый ответ несёт X-Request-ID; указывайте его в обращениях в поддержку.

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

• Создайте ключ в кабинете: Настройки → API (/my/api). Ключ показывается один раз.
• Вызовите GET /me — это самый дешёвый способ проверить ключ и увидеть его скоупы и лимиты.
• Дальше: аутентификация, ошибки, сценарий работы с серверами.

Каждый запрос несёт заголовок Authorization: Bearer <ключ>. Ключ начинается с vk_live_ (боевой) или vk_test_ (тестовый, см. Sandbox).

Ключи создаёт владелец аккаунта в кабинете (/my/api): имя, режим live/test, набор скоупов, необязательный список разрешённых IP/CIDR и окно действия (not_before/expires_at). Создание подтверждается кодом TOTP или паролем; секрет показывается один раз. Ключи не зависят от сессий кабинета: смена пароля, «выйти везде» и настройка 2FA их не трогают; бан аккаунта отзывает все ключи. Через API ключи не создаются — только просматриваются (GET /keys) и отзывается свой ключ.

Скоупы

Каждая операция перечисляет требуемые скоупы в x-scopes спецификации; пустой список означает «любой валидный ключ» (каталог, /me). Совсем без ключа доступны только GET /health (всегда 200 со status: ok | disabled — это проба доступности, а не защищённая ручка) и GET /openapi.json. Нехватка скоупа → 403 insufficient_scope, в details.required — чего не хватило.

Пресеты

Пресеты в кабинете — просто наборы скоупов, их можно править чекбоксами после выбора.

Kill switch

DELETE /keys/{key_id} отзывает только тот ключ, которым сделан запрос, независимо от его скоупов. Так утёкший ключ можно погасить откуда угодно (из CI, с сервера), не выдавая каждому ключу право уничтожить всю интеграцию. Остальные ключи отзываются в кабинете. Работает и для тестовых ключей.

Тестовый ключ (vk_test_…) создаётся в том же кабинете, что и боевой, и ходит на тот же базовый URL — отдельного стенда нет.

Что делает тестовый ключ:

• Не двигает деньги: заказ, продление, пополнение, оплата счёта и удаление возвращают правдоподобный ответ, но баланс не меняется, VM и домены не создаются, платёжные шлюзы не вызываются.
• Заказ сервера возвращает фейковый сервер с id >= 9000000000. Он живёт 24 часа и виден в GET /servers только этому ключу; над ним можно вызывать статус, питание, переустановку, IP и удаление — всё тоже имитируется.
• Каждый ответ тестовому ключу несёт заголовок X-Sandbox: true. Проверяйте его в тестах, чтобы не спутать режимы.
• Идемпотентность, лимиты и ошибки валидации работают как в live: 402, 409, 429 можно получить и в песочнице.

Поведение каждой операции под тестовым ключом описано в x-sandbox спецификации:

Если тестовые ключи выключены на стороне VDSok, любой запрос отвечает 403 sandbox_disabled.

У API одна форма ошибки — на любой статус, включая 404/405/413/500 уровня приложения:

{
  "error": {
    "code": "insufficient_funds",
    "message": "Balance 4.10 USD is below the required 5.90 USD",
    "request_id": "9f1c2a9d-4b7e-4a21-8d3f-0c6e5b2a1d44",
    "details": {"required": "5.90", "balance": "4.10", "shortfall": "1.80", "currency": "USD"}
  }
}

• code — машинный код из закрытого списка ниже. Ветвитесь по нему, а не по message.
• message — человекочитаемый английский текст, не для парсинга; формулировки могут меняться.
• request_id — тот же, что в заголовке X-Request-ID; указывайте его в поддержку.
• details — дополнение, зависящее от кода: required (скоупы), fields (ошибки валидации по полям), денежные цифры для insufficient_funds, status для service_state.

Список кодов закрытый по каждому статусу, но клиент должен терпеть неизвестные коды и обрабатывать их по HTTP-статусу — так добавление кода не ломает интеграции.

Что повторять: 429, 502, 503, 504 — безопасно для GET и для мутаций с Idempotency-Key. Остальные мутации без ключа идемпотентности не повторяйте вслепую.

По умолчанию — 120 запросов в минуту на ключ плюс отдельная корзина 20 в минуту для дорогих вызовов. Лимиты считаются на ключ (не на аккаунт и не на IP), окно фиксированное — 60 секунд. Сотрудники VDSok могут поднять лимиты конкретному ключу; текущий потолок и остаток приходят в заголовках X-RateLimit-Limit и X-RateLimit-Remaining каждого ответа, а настройки конкретного ключа видны в GET /keys/{id}. Чтения в кабинете в счёт API не идут.

Дорогие вызовы помечены x-expensive: true в спецификации:

• GET /servers/{server_id}/status и GET /servers/{server_id}?include=live — живой опрос панели;
• GET /domains/availability — запрос к регистратору;
• GET /catalog/quote;
• POST /servers, POST /servers/{server_id}/ips, POST /balance/topup;
• GET /invoices/{invoice_id}/pdf;
• POST /webhooks/{webhook_id}/test, POST /webhooks/deliveries/{delivery_id}/redeliver.

Отдельно: POST /servers/{server_id}/actions/reset-password — не больше 5 раз за 5 минут на сервер. Запросы с невалидным ключом ограничены 30 в минуту на IP — против перебора.

Заголовки

При 429 rate_limited в details указаны bucket (normal/expensive) и limit. Правильная реакция — подождать Retry-After и повторить, а не долбить в цикле: окно фиксированное, раньше оно не откроется.

Списки с потенциально большим числом элементов (/servers, /invoices, /transactions, /orders, /domains, /webhooks/{id}/deliveries) отдают страницу и курсор:

{"data": [ … ], "next_cursor": "eyJpZCI6MjAwMSwic2lnIjoi…"}

• limit — от 1 до 100, по умолчанию 50.
• next_cursor — передайте обратно как ?cursor=, чтобы получить следующую страницу; null означает, что это последняя.
• Курсоры непрозрачные и подписанные: не собирайте их руками и не парсите — испорченный курсор даёт 400 invalid_cursor. Курсор привязан к набору фильтров: меняете status — начинайте с первой страницы.
• Порядок фиксированный: новые сначала. Добавленные во время обхода элементы могут попасть в начало, но дубликатов и пропусков внутри обхода нет.

Короткие справочники (/catalog/*, /servers/{id}/ips, /ssh-keys, /keys, /webhooks) возвращают {"data": [...]} целиком, без курсора.

Операции, которые двигают деньги или трогают внешние системы, помечены x-idempotent: true и требуют заголовок Idempotency-Key: POST /balance/topup, POST /invoices/{id}/pay, POST /servers, DELETE /servers/{id}, POST /servers/{id}/renew, POST /servers/{id}/ips, POST /domains, POST /domains/{id}/renew, POST /domains/transfers.

Ключ — любая строка 16..128 символов, уникальная для логической операции; UUID v4 подходит. Генерируйте его до первой попытки и переиспользуйте при повторах — в этом весь смысл. Ключ запоминается на 7 дней вместе с дайджестом эндпоинта и тела:

Итог операции сохраняется всегда, включая ответы 5xx, — иначе повтор бесконечно получал бы idempotency_in_progress. Поэтому повтор никогда не спишет дважды. Заказ сервера с таймаутом панели (202 provisioning) при повторе с тем же ключом вернёт тот же 202 с тем же invoice_id — дальше опрашивайте GET /orders/{invoice_id}.

Деньги

Все суммы — строки вида "5.90", "0.0083", "-12.00" (шаблон ^-?[0-9]+\.[0-9]{2,4}$), рядом всегда есть currency — ISO 4217 код валюты аккаунта (например, USD). Float в JSON не используется никогда: 0.1 + 0.2 в двоичной арифметике не равно 0.3, а в биллинге такая погрешность превращается в расхождение на счёте.

• Разбирайте суммы в десятичный тип: Decimal в Python, BigInt в минимальных единицах или decimal.js в Node, bcmath/BigDecimal в PHP.
• В теле запросов (amount при пополнении) присылайте строку с двумя знаками: "25.00". Число 25 тоже примется, но 25.005 — нет.
• Часовые цены (price_hourly) имеют до 4 знаков: "0.0083".
• Транзакции несут amount по модулю и отдельное поле direction (credit/debit); Money со знаком встречается только в корректировках.

Даты

Все моменты времени — RFC 3339 в UTC с суффиксом Z: 2026-09-15T10:00:00Z. Поля, которые могут быть пустыми (next_due_at, expires_at, paid_at), приходят как null, а не как пустая строка или 0000-00-00.

• В запросах (since/until у /transactions) тоже присылайте RFC 3339 с Z или смещением.
• X-RateLimit-Reset и X-Webhook-Timestamp — unix-секунды, не миллисекунды.
• Возвраты при удалении считаются по целым дням неиспользованного периода (days_left в RefundQuote), сравнивайте свои расчёты в днях, а не в секундах.

Ниже — жизненный цикл одного VDS от каталога до удаления. Всё то же, что делает кабинет, с теми же проверками и ценами. server_id везде — id виртуальной машины в панели (id в ответах /servers).

Статусы сервера (status): active — работает или хотя бы не остановлен биллингом; stopped — выключен клиентом; suspended — отключён за неуплату или сотрудником; pending_cancel — одобрена заявка на отмену в конце периода; cancelled — удалён клиентом или по заявке; terminated — удалён после долгой неуплаты. Флаги flags.blocked (заблокирован сотрудником, любая мутация → 403 server_blocked), flags.expired, flags.is_test уточняют, что можно сделать.

Пока над сервером идёт заказ, удаление или смена IP, параллельная мутация того же объекта отвечает 409 operation_in_progress — дождитесь и повторите.

Домены регистрируются на контактные данные из профиля аккаунта — те же, что использует кабинет; через API их не изменить. Статусы (status): pending — регистратор принял заявку, домен активируется на следующей синхронизации; active; expired; transfer_pending; cancelled. blocked: true — домен заблокирован сотрудником, мутации отвечают 403 domain_blocked. locked — трансфер-лок у регистратора.

Все денежные операции с доменами (POST /domains, /domains/{id}/renew, /domains/transfers) требуют Idempotency-Key и скоуп domains:order; чтения — domains:read; NS, privacy и автопродление — domains:manage.

Все услуги оплачиваются с баланса аккаунта в его валюте (currency). Пополнение идёт через платёжный шлюз по ссылке; API не принимает карты и не хранит платёжные данные. Заказ, продление и покупка IP списывают с баланса синхронно, поэтому перед ними стоит проверить GET /balance или GET /catalog/quote → balance_sufficient.

Вебхук — это POST от VDSok на ваш https:// URL при событии в аккаунте. Подписки создаются только боевым ключом со скоупом webhooks:manage; тестовому ключу все ручки /webhooks* отвечают 403 sandbox_not_supported. URL должен быть на публичном адресе, редиректы не выполняются.

Каталог событий

Актуальный список с описаниями отдаёт GET /webhooks/events.

Конверт

{
  "id": "evt_01J7ZK3Q9X4R",
  "type": "server.suspended",
  "created_at": "2026-09-15T10:00:00Z",
  "livemode": true,
  "account_id": 57,
  "api_version": "1",
  "data": {
    "object": {"id": 2001, "name": "web-01", "status": "suspended", "...": "full Server object"},
    "previous": {"status": "active"}
  },
  "resource": "/api/v1/servers/2001"
}

data.object — полный снимок объекта в том же виде, что отдаёт REST; data.previous — изменившиеся поля или null; resource — путь объекта в API. Конверт сериализуется один раз при постановке в очередь: повторы и переотправки шлют те же байты, поэтому id и created_at не меняются. А вот X-Webhook-Timestamp — это время конкретной попытки, поэтому подпись на каждой попытке считается заново: дедуплицируйте по X-Webhook-Id, а не по подписи.

Заголовки доставки

Доставка и повторы

Ответьте любым 2xx в течение 10 секунд — тело ответа игнорируется. Обрабатывайте событие асинхронно: примите, поставьте в свою очередь, ответьте 200. Иначе — повторы через 60 с, 5 мин, 15 мин, 1 ч и 6 ч; после 6-й неудачи доставка помечается dead. 20 неудач подряд автоматически выключают подписку (причина попадает в disabled_reason текстом) и шлют письмо; включить обратно — PATCH /webhooks/{id} с {"active": true}. Журнал: доставленные записи хранятся 14 дней, мёртвые — 30.

Официальные SDK покрывают весь v1 и следуют той же спецификации, что и этот сайт (в Node-пакете типы генерируются из неё напрямую). Общее для всех трёх:

• конструктор (apiKey, {baseUrl, timeout = 30 s, maxRetries = 2}); заголовки Authorization, Accept, User-Agent: vdsok-sdk-<lang>/<ver>;
• автоматические повторы на 429/502/503/504 с учётом Retry-After — только для GET и мутаций с Idempotency-Key; на денежных ручках SDK сам генерирует ключ идемпотентности и отдаёт его вызывающему;
• единая ошибка ApiError {status, code, message, requestId, details} и RateLimitInfo из заголовков. В PHP машинный код лежит в errorCode, а не в code: у \Exception уже есть унаследованное $code (HTTP-статус), переобъявить его нельзя;
• итераторы пагинации (for server in client.servers.list() обходит все страницы);
• Webhooks.verify(secret, headers, rawBody, tolerance = 300) и construct_event() — проверка подписи из раздела вебхуков;
• группы account, balance, invoices, catalog, servers, domains, ssh_keys, keys, webhooks; деньги — строками/Decimal, даты — в нативные типы.

Версии SDK 1.x соответствуют API v1; ломающие изменения API выйдут только вместе с /v2 и новой мажорной версией SDK. Исходники и issue-трекер — на GitHub в организации vdsok (sdk-node, sdk-python, sdk-php).

Изменения API документируются здесь и в поле info.version спецификации. В v1 всё добавляется только совместимо: новые поля, новые эндпоинты, новые коды ошибок и события вебхуков. Клиент обязан игнорировать неизвестные поля и обрабатывать неизвестные коды по HTTP-статусу.

1.0.0 — 2026-09-15

• Первый публичный выпуск Client API v1: /me, аккаунт, баланс и транзакции, пополнение, счета (список, PDF, оплата с баланса, платёжная ссылка), каталог (тарифы, ОС, локации, зоны, котировка), серверы (заказ, статус, питание, переустановка, сброс пароля, продление, удаление с возвратом, заметки и автопродление), заказы, дополнительные IP и PTR, SSH-ключи, домены (доступность, регистрация, продление, NS, privacy, трансфер), API-ключи (просмотр и kill switch), вебхуки (подписки, журнал, повтор, тест).
• Ключи vk_live_/vk_test_, скоупы и пресеты, IP-списки, окна действия.
• Идемпотентность на денежных операциях, курсорная пагинация, лимиты 120/20 в минуту.
• Sandbox: тестовые ключи читают реальные данные и имитируют записи.
• 14 типов событий вебхуков с HMAC-SHA256 подписью и повторами.
• SDK: @vdsok/sdk (Node), vdsok (Python), vdsok/sdk (PHP).

Машиночитаемое описание API — документ OpenAPI 3.1, тот же, из которого собраны этот сайт и SDK. Он доступен без ключа:

• Скачать openapi.json — кэшируемая копия; живой документ отдаёт GET /api/v1/openapi.json.
• Интерактивный справочник — все операции, схемы, примеры запросов и ответов, с возможностью выполнить запрос своим ключом прямо из браузера.

В документе используются расширения: x-scopes (требуемые скоупы), x-idempotent (нужен Idempotency-Key), x-expensive (считается в корзину 20/мин), x-sandbox (real | fake | forbidden — поведение под тестовым ключом). Из спецификации можно сгенерировать клиент под любой язык — openapi-typescript, openapi-generator, oapi-codegen — или подключить её в Postman/Insomnia.