Покупка и жизненный цикл
Заказы и операции
| Идентификатор | Значение | Получение результата |
|---|---|---|
api_key_id | Интеграция и её баланс | GET /balance |
api_user_id | Строковый ID вашего клиента | Фильтры VPS, аренд и заказов |
order_id | Оплаченная покупка, продление или смена тарифа | GET /orders/{order_id} |
vm_id | VPS | GET /vms/{vm_id} |
rental_id | Аренда выделенного сервера | GET /dedicated/rentals/{rental_id} |
ip_id | Выделенный IP-адрес | GET /ips |
operation_id | Асинхронная команда VPS | GET /vms/{vm_id}/operations/{operation_id} |
operation_id для аренды | Асинхронная команда питания или переустановки дедика | GET /dedicated/rentals/{rental_id}/operations/{operation_id} |
Покупка списывает баланс интеграции при приёме заказа. Выделение ресурсов затем выполняется асинхронно. Расчёт цены не списывает баланс, не создаёт заказ и не резервирует ресурсы. HTTP 202 подтверждает приём запроса, а не его конечный результат.
| Статус заказа | Значение |
|---|---|
pending | Заказ сохранён, ожидает обработки |
processing | Обрабатывается |
completed | Оплаченное действие завершено; для покупки дедика — завершено резервирование |
failed | Действие не выполнено; проверьте ошибку и транзакции |
refunded | Сумма заказа возвращена на баланс интеграции |
review | Неопределённый или частичный результат, требующий выяснения |
При review или requires_review=true проверьте ресурс и обратитесь в поддержку перед новой платной или разрушительной командой. Ошибка либо неопределённый ответ не доказывают, что ресурс не был создан. Транзакции показывают реальные движения баланса; order_id может быть null при пополнении и других движениях без заказа.
После потери ответа используйте исходный Idempotency-Key и неизменные параметры. Проверяйте существующий заказ вместо новой покупки для восстановления результата. Вебхуки могут повторяться или не дойти, поэтому сохраняйте возможность запросить статус.
Очередь создания VPS
При нехватке ресурсов оплаченный заказ остаётся processing. Размер очереди возвращает общее количество ожидающих по локации/платформе для всех покупателей. Очередь заказа показывает его место, причину ожидания и can_cancel. Числа могут отставать до пяти секунд и не определяют время выдачи: при размещении могут пропускаться заказы, которым не хватает текущих ресурсов.
Отменить очередь можно до резервирования ресурсов и начала выдачи. После отмены исходная списанная сумма возвращается один раз: финансовый статус refunded, код creation_cancelled. Отправляются order.refunded и vm.creation_cancelled; порядок доставки не гарантируется. У второго события vm_id=null, есть order_id и operation_id. Это не удаление выданного VPS.
Передавайте order_id. Статус очереди описывает операцию выдачи отдельно от финансового заказа. До передачи на выдачу маршруты очереди возвращают 409 queue_not_ready: проверяйте заказ и повторяйте запрос, пока он pending или processing. Если создание уже началось, отмена возвращает 409 queue_cancel_unavailable. При потере ответа на отмену проверьте заказ или повторите тот же DELETE: Idempotency-Key не нужен, повторного возврата не будет.
Цена и продление VPS
До покупки выбирается семейство CPU: epyc — AMD EPYC, ryzen — AMD Ryzen, xeon — Intel Xeon. В одной локации могут использоваться разные модели одного семейства. cpu_display_name содержит название семейства; cpu_max_frequency_ghz равен null: точная модель и частота известны после выдачи VPS.
platform, cpu_display_name и cpu_max_frequency_ghz описывают физический CPU текущей ноды VPS и могут быть null, если сведения не заполнены. После переноса следующие запросы списка/деталей отражают новую ноду. cpu_display_name передаётся как сохранённая строка модели и может содержать число физических ядер/потоков; выделенные ресурсы VPS определяются по cpu_cores. Максимальная частота — характеристика CPU, а не текущий замер или гарантированная частота каждого vCPU. Получайте эти поля из списка/деталей VPS, а не из события создания или результата операции.
GET /plans возвращает datacenter у каждой локации. В тарифах дедиков, списках и деталях VPS и аренд дедиков также есть datacenter: название дата-центра локации или null, если оно не заполнено.
Цена зависит от локации, платформы, тарифа и доли CPU. Опубликованная месячная цена уже включает наценку интеграции. При покупке/продлении на несколько месяцев применяется текущая скидка за срок; итог получайте через расчёт, а не простым умножением месячной цены.
Сроки — календарные месяцы, а не блоки по 30 суток. Исходная длительность VPS рассчитывается при покупке; при выдаче дата окончания оплаты сдвигается с учётом ожидания и установки. После выдачи parameters.paid_until заказа содержит фактическую дату из результата создания; до выдачи она предварительная. Продление увеличивает оплаченный срок либо отсчитывается от текущего времени, если оплата уже истекла. Продлить можно в период ожидания до начала удаления.
Смена тарифа не может уменьшать ресурсы CPU, RAM, диск и включённый трафик. Без cpu_percent сохраняется текущая доля. Доплата — разница цен за остаток оплаченных календарных периодов по текущим ценам тарифов с исходной скидкой каждого периода, включая продления вперёд. Срок оплаты сохраняется. Расчёт возвращает максимальную цену для подтверждения через expected_amount_usd и новую месячную цену.
Cloud-init
Создание VPS, расчёт цены и переустановка ОС принимают необязательный cloud_init: JSON-объект cloud-config, не строку YAML. Пропустите поле или передайте null для стандартной установки.
{
"cloud_init": {
"packages": ["curl"],
"runcmd": [["sh", "-c", "echo ready > /root/cloud-init-ready"]]
}
}
Лимит объекта — 65536 байт после серверной JSON-сериализации, при которой не-ASCII символы экранируются. Поля users, packages, runcmd и write_files при наличии должны быть массивами. Сеть, hostname и основной доступ задаёт платформа. При создании по-прежнему нужен ровно один из password или ssh_public_key. При повторе покупки или команды передавайте тот же объект cloud-init.
guest_initialization содержит результат установки в деталях VPS, заказе покупки, результате операции переустановки и соответствующих вебхуках:
| Статус | error_code | Значение |
|---|---|---|
succeeded | null | Cloud-init завершился; это не подтверждает работоспособность приложения |
failed | cloud_init_failed | Ошибка пользовательской настройки; работающий VPS сохранён |
unknown | guest_initialization_timeout | Инициализация не подтверждена за 15 минут; VPS с пользовательской настройкой сохранён, если его работа подтверждена |
Поле может быть null, если результата нет. В деталях VPS отображается результат последней установки. Заказ может быть completed, а операция переустановки — succeeded, при инициализации failed или unknown: проверяйте оба результата. Ошибка пользовательской настройки сама по себе не отменяет покупку и не возвращает оплату. Инфраструктурные ошибки по-прежнему означают ошибку создания.
Содержимое cloud-init и вывод выполнения не передаются в публичных параметрах заказа и партнёрских вебхуках.
Приложения
Получите активный каталог приложений и выберите application_id. Передавайте его вместе с os_id при расчёте и покупке. Коды из supported_os соответствуют каталогу ОС. Ресурсы выбирайте по min_* и recommended_*: RAM в MiB, диск в GiB. Значение null означает, что требование не указано. Варианты группируются по app_code, выбираются по числовому id.
Нельзя сочетать приложение с ненулевым cloud_init, включая {}. Сервис серверов проверяет доступность и совместимость при создании; расчёт определяет только цену VPS, без подтверждения совместимости. При отклонении создания действует существующий возврат оплаты заказа. Отдельной доплаты за приложение нет.
Поле application в списке и деталях VPS, заказе покупки и результате переустановки содержит публичные сведения и контрольную сумму installer_sha256, без содержимого установщика. Заказ хранит снимок покупки, данные VPS — последнюю успешную установку. Обычная переустановка сохраняет установщик и проверяет совместимость ОС. Явный cloud_init, включая {}, заменяет его: application становится null. Выбор другого приложения при переустановке не поддерживается.
При installation_mode=background (игровые приложения) установка продолжается после выдачи VPS и начала оплаченного периода. guest_initialization.status=succeeded подтверждает только завершение базового cloud-init. Отдельного вебхука готовности приложения нет. Проверяйте systemctl status adapt-application-install.service и journalctl -u adapt-application-install.service внутри VPS. Приложению могут потребоваться начальная настройка, домен, токены или лицензии.
Rescue
Включение Rescue: PUT /vms/{vm_id}/rescue, заголовок Idempotency-Key и JSON:
{
"api_key_id": 1,
"password": "Temporary-Rescue-2026!"
}
Временный пароль обязателен: 5–128 символов, без CR, LF и NUL. VPS должен быть оплачен и иметь не менее 2048 МиБ RAM. Rescue перезагружает VPS в среду восстановления, сохраняя диски и сеть. После успешной операции подключайтесь как root по SSH к IP VPS, порт 22, с переданным паролем. Правила firewall продолжают действовать.
Включение и выключение возвращают HTTP 202 с ID операции в data.id. Проверяйте статус операции. Успешный результат содержит vm_id, status и rescue; поле rescue также доступно в деталях VPS:
{
"active": true,
"access": "ssh",
"requires_review": false,
"operation_id": 501,
"operation_status": "succeeded"
}
active означает сохранённый контекст Rescue, а не гарантию текущей доступности SSH. access принимает ssh, console или null. Всё состояние может быть null, если оно не получено. При активном Rescue недоступны смена тарифа, переустановка ОС и сброс пароля основной ОС.
Выключение Rescue: DELETE /vms/{vm_id}/rescue?api_key_id=1 с отдельным Idempotency-Key; тело и пароль не нужны. Восстанавливается загрузка обычной ОС, оплаченный VPS запускается. При истёкшей оплате или приостановке VPS остаётся выключенным. Выход доступен и из состояния error, если контекст Rescue сохранён.
При ошибке проверяйте error_code и requires_review. rescue_not_ready означает, что готовность Rescue не подтверждена: проверьте VPS и выйдите из Rescue. При rescue_memory_required нужен тариф с достаточным объёмом RAM; при rescue_iso_missing или rescue_not_configured обратитесь в поддержку. Потерянный запрос повторяйте с исходным ключом и параметрами.
Терминал VPS
Создайте ссылку на терминал через POST /vms/{vm_id}/terminal/link?api_key_id=1. VPS должна быть включена. В браузере открывается текстовая консоль ОС; приглашение входа определяется гостевой ОС. JSON-тело и Idempotency-Key не нужны. Открывайте data.url целиком; одноразовая ссылка действует пять минут до первого использования. Прежняя графическая консоль доступна отдельно.
Трафик и IPv4
Дополнительный трафик VPS и отдельно оплачиваемые IPv4 имеют фиксированные цены без наценки интеграции и скидок за срок.
- Трафик: целое количество единиц по 1024⁴ байт, только для текущего периода трафика. Расчёт возвращает
expected_period_idиperiod_ends_at; передайте ID периода в покупку, чтобы отклонить устаревший расчёт. Остаток дополнительного трафика не переносится. - Покупка IPv4: один дополнительный адрес на VPS, оплаченный на 1/3/6/12/24/36 календарных месяцев (по умолчанию 1) независимо от срока VPS. Не более 10 IPv4 на VPS, включая основной.
- Продление IPv4: выбранный срок в календарных месяцах, от более позднего из текущего времени и
paid_until, по текущей фиксированной цене. Доступно для оплачиваемых дополнительных или сохранённых IPv4; включённый основной IPv4 и IPv6 отдельно не продлеваются. - Сохранённые адреса:
GET /ips?api_key_id=1&attachment=unattached. Сохранение адреса продолжает его оплату даже без VPS.
Чтобы перенести дополнительный IPv4, снимите его с keep_ip=true, затем назначьте совместимому VPS того же клиента (api_user_id). Адрес должен оставаться оплаченным и свободным. Назначение не покупает адрес и не продлевает срок. Проверяйте guest_configuration_required и при необходимости меняйте сеть внутри гостевой ОС.
Снятие с keep_ip=false освобождает адрес. DELETE /ips/{ip_id} освобождает сохранённый IPv4 без привязки к VPS. Основной IPv4 нельзя снять с существующего VPS.
Аренда выделенного сервера
- Получите тарифы дедиков, доступность, варианты дисков и скидки за срок. Варианты разметки содержат
codeиname: отображайтеname(например,No Raid), передавайтеcode(separate). Для общей разметки используйте варианты уровня тарифа; для групп дисков, включая Storage, — варианты внутри каждой записиdisks[]. - Рассчитайте, затем купите аренду с
plan_id,os_id, выбранной разметкой, ID клиента и паролем либо публичным SSH-ключом. Физический сервер выбирает платформа. - Сохраните
order_id, затемrental_id.order.completedподтверждает резерв, а не готовность. - Дождитесь
dedicated.issuedлибо статуса арендыactive. Получите адреса и доступы в деталях аренды. Срок аренды начинается с выдачи.
Статусы аренды: preparing → active → overdue → cleaning → completed. Отменённая до выдачи аренда может завершиться как cancelled. cleaning означает начавшуюся очистку/освобождение; не обещайте продление на этом этапе.
Дополнительные IPv4 из extra_ipv4_count оплачиваются в составе аренды по фиксированной цене. Для итоговой суммы используйте расчёт продления дедика. Отдельный процесс покупки и продления VPS-адресов через /ips не является оплатой адресов аренды дедика.
Если администратор отменил аренду до выдачи, исходная покупка возвращается один раз на баланс интеграции; приходят order.refunded и dedicated.released. Обычное окончание срока или освобождение уже выданной услуги не означает автоматический возврат.
Разметка групп дисков
Для общей разметки передавайте disk_layout. Для групп дисков передавайте только disk_layouts: объект с выбором кода для каждого disks[].id.
{
"disk_layouts": {
"94dc1d25-4d4f-4c6b-a8e3-a226f66254a1": "raid1",
"dc8c3bfe-021d-4d40-adbe-55784a0b71e2": "raid6"
}
}
ID в примере условные: берите непрозрачные ID выбранного тарифа, не определяйте их по типу диска. У каждой группы свой default_disk_layout; клиент явно передаёт выбор. Пропущенные/лишние группы, неподдерживаемые коды, пустой объект и оба формата одновременно возвращают 422 до списания. В каталоге группового тарифа верхний disk_layouts=[], default_disk_layout=null. Список и детали аренды сохраняют выбранную карту и возвращают disk_layout=null; характеристики групп берите из снимка plan.disks аренды. Варианты в снимке остаются строковыми кодами. При повторе заказа выбор должен совпадать; порядок ключей объекта значения не имеет.
Для групп HDD доступны RAID 5 (от 3 дисков), RAID 6 (от 4) и RAID 10 (чётное число от 4). Передавайте вариант только если он указан в disks[].disk_layouts. Для NVMe/SSD и общей разметки эти три варианта недоступны.
Питание и переустановка
Получите статус аренды: power_state, поддержанные power_actions и признак reinstall. Управление доступно активной оплаченной аренде на подготовленном сервере. Первичная выдача остаётся ручной, в течение 72 часов. Автоматическая переустановка ОС для аренд с группами дисков, включая Storage, пока недоступна.
Управление питанием и переустановка ОС возвращают HTTP 202 с ID операции. Финансовый заказ не создаётся, баланс не списывается. Передавайте Idempotency-Key для каждой команды; после потери ответа повторите прежний ключ и неизменное тело. Следите за операцией, историей или соответствующим вебхуком.
Переустановка удаляет данные дисков и требует confirmed: true и os_id. Если password и ssh_public_key отсутствуют, сохраняются прежние доступы. Передача хотя бы одного поля заменяет весь комплект: укажите пароль, публичный SSH-ключ или оба. IP, владелец и оплаченный срок сохраняются. После успеха получите новые доступы в деталях аренды. Выполняющаяся операция или ошибка с неразрешённым requires_review блокирует следующие команды; обратитесь в поддержку. review_resolved_at фиксирует проверку администратором, не меняя исходный результат.
Автопродление и окончание оплаты
auto_renew по умолчанию false. Настройку можно передать при покупке или изменить через PATCH для VPS, аренды либо отдельно оплачиваемого IPv4. Само изменение флага не списывает деньги. У каждой услуги своя настройка.
| Услуга | Срок продления | Цена |
|---|---|---|
| VPS | Как в последней оплаченной покупке/продлении | Текущая цена тарифа, наценка интеграции и текущая скидка за срок |
| Аренда дедика | Как в последней оплаченной покупке/продлении | Текущая цена аренды, наценка, скидка за срок и стоимость дополнительных IPv4 |
| Отдельный IPv4 | Последний оплаченный срок в месяцах | Текущая месячная цена IPv4 × срок |
При включённом автопродлении Cloud API пытается продлить услугу с баланса интеграции по предупреждению за час до окончания оплаты. Если срок истёк, повторная попытка происходит по последнему предупреждению за час до удаления/освобождения. Недостаточный баланс не продлевает услугу. Пополнение баланса само по себе не запускает немедленную повторную попытку; при необходимости продлите вручную.
Неоплаченные VPS и платные IPv4 приостанавливаются; период ожидания — 24 часа. Без оплаты они удаляются/освобождаются. Аренда дедика переходит в overdue, а после ожидания — в очистку/освобождение. Обработка асинхронная: дедлайн не гарантирует завершение очистки ровно в эту секунду.
Предупреждения приходят партнёру через Вебхуки, включая vm.deleting_soon, ip.releasing_soon и dedicated.releasing_soon, даже при выключенном автопродлении или недостатке средств. Предупреждение не подтверждает успешное продление: проверяйте итоговый оплаченный срок.
Бекапы
Бекапы принадлежат отдельной услуге хранения и сохраняются после удаления исходной VPS. Находите их через список услуг с фильтром api_user_id или vm_id.
Создайте услугу для существующей VPS через POST /backup-services с новым Idempotency-Key:
{"api_key_id": 1, "vm_id": 101, "kind": "automatic", "auto_renew": false}
automatic создаёт первую копию при активации, затем ежедневно; хранятся последние 7 успешных копий. Для одной ручной копии с отдельной услугой хранения передайте kind: "manual". Оплаченный срок — календарный месяц от активации. К ценам из /plans не применяются наценка интеграции, доля CPU и скидка за срок.
- Автоматические бекапы оплачиваются заранее по месячной цене тарифа. При ошибке покупки оплата возвращается после удаления созданной услуги.
- Ручной бекап оплачивается после создания:
stored_size_bytes / 1073741824 × manual_backup_gb_month_price_usd, по ставке на момент заказа, с округлением до четырёх знаков USD. До получения размера сумма заказа равна нулю. При нехватке средств копия удаляется; если интеграции разрешён отрицательный баланс, списание выполняется в минус. GET /vms/{vm_id}/backup-estimateвозвращает оценку, а не окончательный оплачиваемый размер. Доступ к копиям открывается после подтверждения первой оплаты.
Все команды бекапов с Idempotency-Key возвращают HTTP 202 и заказ, включая бесплатное восстановление, экспорт и удаление. Проверяйте оплату и итоговый статус через /orders/{order_id}. Поля backup_service_id, backup_id и worker_operation_id появляются по мере получения данных; маршрут операции показывает выполнение, а не оплату. После таймаута повторяйте запрос с тем же ключом и телом.
Продление: POST /backup-services/{service_id}/renew, тело {"api_key_id": 1}. Срок — календарный месяц от более поздней даты: сейчас или текущий paid_until, по актуальным ценам бекапов. Для автоматических используется текущий тариф VPS, после её удаления — последний сохранённый тариф; для ручной копии — измеренный размер. PATCH услуги с {"api_key_id": 1, "auto_renew": true} включает попытку продления за 24 часа до окончания оплаты и последнюю попытку за час до удаления. После окончания оплаты есть 24 часа до удаления. Отключение автопродления не отменяет уже принятый заказ продления.
Восстановление и скачивание
POST /backups/{backup_id}/restore с {"api_key_id": 1, "vm_id": 101} перезаписывает диски исходной VPS. Для новой VPS используйте обычный POST /vms, передав backup_id вместо os_id; api_user_id должен совпадать с владельцем копии. Не передавайте пароль, SSH-ключ, приложение и cloud-init: ОС, доступы и программы берутся из копии. Новая VPS оплачивается по обычной цене тарифа с наценкой и скидкой за срок. Объёма диска должно хватать для всех дисков копии.
За восстановление отдельной платы нет. Оба способа используют общий лимит 3 принятых восстановления на услугу за скользящие 24 часа. Ожидающие и неуспешные попытки учитываются, повторы с тем же ключом — нет. При превышении возвращается 429 с detail.code=backup_limit_reached.
POST /backups/{backup_id}/exports с {"api_key_id": 1} готовит ZIP64-архив raw-дисков и конфигурации. Отдельной платы нет; лимит — 1 принятая подготовка на копию за скользящие 24 часа, с теми же правилами повторов. Получите worker_operation_id из заказа, затем запросите /backup-exports/{operation_id} и /backup-exports/{operation_id}/download. Файл хранится 24 часа после завершения, ссылка действует не более 1 часа и не дольше срока хранения файла. Повторная выдача ссылки не расходует лимит и не продлевает хранение. Число скачиваний не ограничивается.
Одну автоматическую копию можно удалить через DELETE /backups/{backup_id}. Для ручной удаляйте услугу через DELETE /backup-services/{service_id}; этот же маршрут удаляет все копии автоматической услуги. Передавайте api_key_id в query, Idempotency-Key — в заголовке. Удаление необратимо, остаток оплаченного срока не возвращается.
Команды VPS и удаление
Команды возвращают операцию: queued → running → succeeded / failed. Проверяйте операцию и текущее состояние ресурса; HTTP 202 — только приём запроса. Штатные shutdown/reboot отличаются от принудительных stop/reset. Переустановка удаляет данные системного диска; wipe_extra_disks=true также разрешает удаление дополнительных дисков.
Для изменения firewall сначала прочитайте правила и revision. Передавайте ревизию с каждой командой, при конфликте перечитывайте настройки. Перестановка требует полного набора ID правил по одному разу. Для открытия и закрытия SMTP-портов используйте отдельный маршрут PATCH /vms/{vm_id}/firewall/smtp.
При удалении VPS обязательно передайте keep_ips:
true: сохранить IPv4, включая бывший основной, как отдельно оплачиваемые адреса. Проверьтеheld_ipsрезультата операции и список адресов для сроков и настроек оплаты.false: освободить адреса вместе с VPS.
Удаление, освобождение адреса и неиспользованный срок не создают пропорциональный возврат. Сохраните нужные данные до удаления или переустановки.
IPv4 без VPS
Сначала вызовите расчёт, затем покупку с api_key_id, api_user_id, location_id, months и необязательным auto_renew (по умолчанию false). Доступны 1/3/6/12/24/36 календарных месяцев, цена — месячная ставка × срок без наценки и скидки. expected_amount_usd позволяет подтвердить рассчитанную сумму. Кластер и VPS не передаются.
После order.completed получите ip_id и paid_until из заказа; адрес доступен в GET /ips?attachment=unattached и принадлежит указанному клиенту. Получите ip.allocated, затем при необходимости назначьте адрес VPS этого же клиента. Повтор покупки с прежним Idempotency-Key не выделяет второй адрес и не списывает повторно.
Ручное продление принимает необязательный months; без него и при автопродлении используется последний оплаченный срок. Старые аренды на 30 дней переходят на один календарный месяц при следующем продлении, если months не передан. Продление идёт по актуальной цене. Покупка дополнительного IP через маршрут VPS принимает те же календарные сроки.
Календарные сроки IPv4
Месяцы прибавляются от текущего UTC-времени покупки, а при продлении — от max(текущее время, paid_until). Если такого дня в целевом месяце нет, используется его последний день: 31 января → 28 февраля, в високосном году → 29 февраля. Цена — месячная ставка × months, без скидки и наценки. Привязка и отвязка IP не меняют оплаченный срок и не списывают деньги повторно.