Документация API (интерфейс прикладного программирования) панели управления Invapi¶

В этой документации описан общий дизайн и принципы работы API, а также конкретные конечные точки. Также приведены примеры запросов к ним.

Информация

Панель управления invapi.hostkey.ru построена на основе этого API.

Запросы API¶

Запросы должны выполняться по протоколу HTTPS, чтобы гарантировать шифрование транзакций.

Для запросов необходимо использовать метод POST, если не указано иное.

Формат примеров API¶

Примеры в этой документации описаны с помощью сurl, HTTP-клиента командной строки. На компьютерах Linux и macOS обычно по умолчанию установлен curl, и он доступен для загрузки на всех популярных платформах, включая Windows.

Каждый пример разделен на несколько строк символом \, который совместим с bash. Типичный пример выглядит так:

Пример запроса POST:

curl -s "https://invapi.hostkey.ru/tags.php" -X POST \
--data "action=list" \
--data "token=$HOSTKEY_TOKEN" \
--data "id=ID сервера"

Параметр -X задает метод запроса. Для согласованности метод будет указан во всех примерах, даже если он явно не требуется для методов GET.

Примеры, для которых требуется объект JSON в теле запроса, передают требуемые данные через параметр --data.

Ответ на запросы происходит в формате JSON и в документации отформатирован для удобочитаемости.

Примечание

Чтобы использовать приведенные примеры, не подставляя каждый раз в них свой токен, вы можете добавить токен один раз в переменные окружения в вашей консоли. Например, на Linux это можно сделать с помощью команды:

HOSTKEY_TOKEN="token"

После этого токен будет автоматически подставляться в ваши запросы.

Примечание

Обратите внимание, что все значения в этой документации являются примерами. Не полагайтесь на идентификаторы операционных систем, тарифов и т.д., используемые в примерах. Используйте ваши значения серверов/сетей/доменов для получения значений или перед созданием ресурсов.

api_keys.php¶

Модуль управления API-ключами: создание, редактирование, удаление, просмотр истории и получение списков ключей для клиентов и серверов.

Метод	Описание
`add`	Создает новый API ключ для клиента или конкретного сервера. Требуется наличие активных серверов у клиента.
`delete`	Удаляет указанный API ключ из системы.
`edit`	Изменяет параметры существующего API ключа (название, IP, статус, срок действия).
`history`	Возвращает историю действий с API ключами (создание, изменение, удаление).
`list`	Возвращает список всех API ключей текущего клиента.
`list_for_server`	Возвращает список API ключей, привязанных к конкретному серверу.
`view`	Возвращает детальную информацию об одном API ключе.

auth.php¶

Модуль аутентификации и авторизации: управление сессиями, вход через WHMCS, API-ключи, SSO (Google, GitHub, VK), двухфакторная аутентификация и проверка токенов.

Метод	Описание
`info`	Возвращает информацию о текущем токене, включая роль, права доступа, список серверов, статус верификации и настройки биллинга.
`login`	Авторизация пользователя по API ключу. Возвращает токен сессии, список доступных серверов и права доступа.
`logout`	Очищает указанный токен доступа, завершая сессию пользователя.
`whmcslogin`	Авторизация через учетные данные WHMCS (email/password) или SSO. Поддерживает выбор биллинга и двухфакторную аутентификацию.

eq.php¶

Модуль управления оборудованием (eq.php): API для развертывания серверов, управления питанием, IPMI, резервными копиями, поиска и получения детальной информации о конфигурации оборудования.

Метод	Описание
`abort_reinstall`	Отменяет процесс переустановки сервера, удаляет соответствующие теги и восстанавливает VLAN.
`add_ipmi_admin`	Добавляет пользователя IPMI с правами администратора.
`add_ipmi_user`	Добавляет пользователя IPMI.
`announceip`	Анонсирует IP-адрес или подсеть через BGP.
`backup_get_schedule`	Возвращает текущее расписание резервного копирования для сервера.
`backup_list`	Возвращает список доступных резервных копий сервера.
`backup_save_schedule`	Сохраняет новое расписание резервного копирования.
`boot_dev`	Загружает сервер с указанного носителя (PXE или диск).
`check_backup_lock`	Проверяет наличие блокировки на создание бэкапа.
`check_pin`	Проверяет PIN-код для подтверждения действий.
`clear_pxe`	Очищает конфигурацию PXE для сервера.
`console`	Запрашивает доступ к консоли сервера.
`create_backup`	Инициирует создание резервной копии сервера.
`create_pxe`	Создает конфигурацию PXE для переустановки сервера.
`delete_backup`	Удаляет указанную резервную копию.
`deploy`	Развертывает сервер по ID или имени пресета.
`get_ipmi`	Возвращает IPMI адрес и модель сервера.
`get_traffic`	Возвращает данные о трафике IPv4 для сервера.
`getserversforannounce`	Возвращает список серверов, доступных для анонса IP.
`groups`	Возвращает группы, к которым принадлежит сервер.
`hard_off`	Жестко выключает сервер (отключение питания).
`history`	Возвращает историю событий сервера.
`list`	Возвращает список оборудования по различным критериям поиска.
`novnc`	Запрашивает доступ к NoVNC консоли.
`off`	Выключает сервер.
`on`	Включает сервер.
`order_instance`	Заказывает новый сервер или переустанавливает существующий.
`reboot`	Перезагружает сервер.
`recreate_novnc`	Пересоздает NoVNC консоль.
`reinstall`	Запускает процесс переустановки сервера.
`remove_ipmi_user`	Удаляет пользователя IPMI.
`request_backup_link`	Запрашивает ссылку для скачивания резервной копии.
`restore_backup`	Восстанавливает сервер из резервной копии.
`search`	Поиск оборудования по различным параметрам.
`sensors`	Возвращает данные с сенсоров сервера.
`set_pin`	Устанавливает PIN-код для подтверждения действий.
`show`	Возвращает детальную информацию о сервере и его оборудовании.
`status`	Возвращает текущий статус сервера.
`stop_novnc`	Останавливает NoVNC консоль.
`suspend`	Приостанавливает сервер.
`unified_server_search`	Единый поиск серверов по ID или имени.
`unit_reset`	Сбрасывает IPMI модуль сервера.
`unsuspend`	Снимает приостановку с сервера.
`update_servers`	Обновляет список серверов для токена.

eq_callback.php¶

Модуль обработки асинхронных колбэков от worker-задач для управления оборудованием, серверами и виртуальными машинами. Обрабатывает статусы выполнения задач (deploy, reinstall, backup, network operati

Метод	Описание
`check`	Проверяет текущий статус асинхронной задачи по ключу (key) и возвращает результат выполнения, контекст и отладочную информацию.

ip.php¶

Модуль управления IP-адресами и сетевой инфраструктурой: получение информации об IP, управление PTR-записями, отслеживание трафика, работа с подсетями и VLAN.

Метод	Описание
`get_client_ip`	Возвращает IP-адрес текущего клиента
`get_ip`	Возвращает полную информацию о конкретном IP-адресе (сеть, маска и т.д.)
`get_ptr`	Проверяет и возвращает PTR-запись для указанного IP
`get_traffic`	Возвращает статистику входящего и исходящего трафика для IP за указанный период
`list_free_ip`	Возвращает список свободных IP-адресов для указанной локации или подсети
`set_main`	Устанавливает указанный IP как основной для интерфейса сервера
`update_ptr`	Обновляет PTR-запись (обратное DNS) для указанного IP

iso.php¶

Модуль управления ISO-образами: загрузка, удаление, монтирование на серверы, обновление метаданных и просмотр истории операций.

Метод	Описание
`add`	Добавляет новый ISO-образ или обновляет существующий по имени. Требует права 'add'.
`del`	Удаляет ISO-образ. Доступно для сотрудников и владельцев приватных ISO.
`delete`	Альтернативный метод удаления ISO с проверкой приватности.
`history`	Возвращает историю операций с ISO-образами.
`list_iso`	Возвращает список доступных ISO-образов. Для клиентов требуется server_id.
`mount_iso`	Монтирует ISO-образ на указанный сервер. Возвращает ключ задачи.
`unmount_iso`	Размонтирует ISO-образ с указанного сервера. Возвращает ключ задачи.
`update`	Обновляет метаданные существующего ISO-образа.
`upload`	Загружает новый ISO-образ по URL. Для сотрудников требуется email и customer_id.
`uploaded`	Возвращает список загруженных ISO для клиента или сотрудника.

jenkins.php¶

Модуль интеграции с Jenkins для управления задачами: получение списка доступных задач и их выполнение для серверов.

Метод	Описание
`get_tasks`	Возвращает список доступных задач Jenkins, доступных для текущего пользователя или клиента.

jira.php¶

Модуль интеграции с Jira для создания тикетов поддержки по управлению серверами (питание, перезагрузка, KVM) и запросам на помощь продажам.

Метод	Описание
`request_PXEboot`	Создает тикет в Jira для ручной загрузки сервера с PXE, если отсутствует удаленное управление.
`request_assistance`	Создает тикет в Jira для отдела продаж с деталями отмены или изменения услуги.
`request_check`	Создает тикет в Jira для проверки и загрузки сервера в ОС при отсутствии удаленного управления.
`request_kvm`	Создает тикет в Jira для подключения IP KVM к серверу.
`request_poff`	Создает тикет в Jira для ручного выключения питания сервера.
`request_pon`	Создает тикет в Jira для ручного включения питания сервера.
`request_reboot`	Создает тикет в Jira для ручной перезагрузки сервера.

nat.php¶

Модуль управления статическим NAT: добавление и удаление правил проброса IP-адресов через MikroTik.

Метод	Описание
`add_static_nat`	Добавляет статический NAT passthrough для указанного сервера. Принимает ID сервера и ACL для IPMI.
`remove_static_nat`	Удаляет статический NAT passthrough для указанного сервера или белого IP.

net.php¶

Модуль управления сетевой инфраструктурой: добавление и удаление IP-адресов, блокировка трафика, управление состоянием сетевых портов, получение статистики и отображение графиков Cacti.

Метод	Описание
`add_ipv4`	Добавляет указанное количество IPv4 адресов к серверу на конкретный порт и VLAN. Поддерживает выбор конкретных IP или автоматический подбор свободных.
`block_ip`	Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Требует причину блокировки.
`get_status`	Возвращает текущий статус сетевого интерфейса сервера (up/down, скорость, дуплекс, MAC).
`port_off`	Отключает сетевой интерфейс сервера. Может добавлять тег блокировки с причиной.
`port_on`	Включает сетевой интерфейс сервера. Удаляет тег блокировки, если он не был установлен администратором.
`remove_ipv4`	Удаляет указанный IPv4 адрес или все адреса с сервера. Очищает PTR записи в DNS.
`show_cacti`	Возвращает данные или ссылку на график трафика для указанного порта сервера из системы мониторинга Cacti.
`show_ipv4_free`	Возвращает список доступных свободных IPv4 адресов для указанного сервера, порта и VLAN.
`unblock_ip`	Разблокирует ранее заблокированный IP-адрес на сервере. Требует прав администратора или совпадения с причиной блокировки.

os.php¶

Модуль управления операционными системами: предоставляет методы для добавления, удаления, обновления и получения списка ОС с фильтрацией по совместимости оборудования и лицензиям.

Метод	Описание
`list`	Возвращает список доступных операционных систем с фильтрацией по типу оборудования (VM, BM, GPU), лицензиям и локации. Поддерживает фильтрацию для конкретного сервера или пресета.

pdns.php¶

Модуль управления DNS-записями и зонами: добавление, удаление и просмотр доменов, поддоменов и зон, а также получение информации о callback-URL.

Метод	Описание
`add_dns`	Добавляет новую DNS-запись в указанную зону.
`add_domain`	Добавляет новый домен в систему DNS для указанного клиента.
`delete_dns`	Удаляет указанную DNS-запись.
`delete_domain`	Удаляет домен и все связанные с ним записи.
`get_cb_url`	Возвращает URL для callback-уведомлений.
`list_domains`	Возвращает список доменов клиента.
`list_zones`	Возвращает список DNS-зон.
`view_zone`	Возвращает детали указанной DNS-зоны.

presets.php¶

Модуль управления пресетами серверов: получение списков, группировка, поиск подходящих серверов и детализация конфигураций с ценами в разных валютах.

Метод	Описание
`groups`	Возвращает список групп пресетов
`info`	Возвращает список пресетов для реселлеров с ценами в указанных валютах
`list`	Возвращает список доступных пресетов с фильтрацией по локации и правам доступа
`search`	Ищет подходящие серверы для конкретного пресета по имени
`show`	Возвращает детальную информацию о пресете по ID или имени

rhr.php¶

Модуль управления заявками на удаленные работы (Remote Hands Requests): создание, фильтрация, обновление статусов и коммуникация по заявкам.

Метод	Описание
`add`	Создает новую заявку на удаленную работу (RHR) с указанием типа и оборудования.
`chat`	Добавляет видимое клиенту сообщение в историю заявки.
`discard`	Рекурсивно меняет статус заявки на отмененную или закрытую.
`list`	Возвращает список доступных задач RHR с фильтрацией по локации, статусу и дате.

s3.php¶

Модуль управления S3-хранилищем: создание и удаление аккаунтов, управление бакетами и файлами, получение статистики использования, управление тарифными планами и биллингом.

Метод	Описание
`create_account`	Создает бесплатный S3 аккаунт для клиента с указанным планом и локацией, создает бакет и инициализирует счетчики.
`create_bucket`	Создает новый бакет в существующем S3 аккаунте.
`create_order`	Создает оплачиваемый заказ на S3 хранилище, создает сервис в биллинге и аккаунт пользователя.
`delete_account`	Полностью удаляет S3 аккаунт пользователя и все связанные с ним данные.
`delete_bucket`	Удаляет указанный бакет из S3 аккаунта.
`delete_file`	Удаляет указанный файл из бакета S3.
`delete_payment_account`	Устанавливает дату прекращения обслуживания для оплачиваемого S3 аккаунта.
`get_buckets`	Возвращает список бакетов пользователя через AWS API, включая информацию о трафике и снапшотах.
`get_buckets_rmq`	Возвращает список бакетов через очередь сообщений (RMQ), включая детальную статистику использования и ключи доступа.
`get_files`	Возвращает список файлов и папок в указанном бакете с поддержкой пагинации и поиска.
`get_users`	Возвращает список S3 пользователей с фильтрацией по плану, локации, email и статистикой трафика.
`history`	Возвращает историю изменений для указанного тарифного плана.
`list_plans`	Возвращает список доступных тарифных планов S3 хранилища.
`show_key`	Возвращает расшифрованный ключ доступа (access_key или secret_key) для S3 аккаунта.

software.php¶

Модуль управления программным обеспечением: предоставляет методы для получения списка доступного ПО с фильтрацией по характеристикам сервера или пресета, а также подбор совместимых пресетов и операцио

Метод	Описание
`list`	Возвращает список программного обеспечения, подходящего для конкретного сервера (id) или пресета (instance_id), с учетом лицензий, характеристик оборудования и промо-акций.

stocks.php¶

Модуль управления серверами на складе: предоставление списков доступных серверов с фильтрацией по локациям и группам, а также детализированная информация о конкретном сервере.

Метод	Описание
`list`	Возвращает список доступных серверов на складе с возможностью фильтрации по локации и группе.
`show`	Возвращает детальную информацию о конкретном сервере по его идентификатору.

tags.php¶

Модуль управления метками (tags) для компонентов инфраструктуры: добавление, удаление, очистка, поиск и отображение списков тегов для серверов и переменных.

Метод	Описание
`add`	Добавляет пользовательскую метку к серверу или компоненту. Поддерживает массовое добавление через id_list.
`clear`	Очищает все или неэссенциальные метки от компонента. Для клиентов доступны только публичные метки.
`get`	Получает метки для компонента. (Реализация в коде пуста, метод в whitelist)
`list`	Возвращает список всех меток для указанного сервера или компонента.
`remove`	Удаляет метку по имени с компонента. Поддерживает массовое удаление через id_list.
`search`	Ищет компоненты, соответствующие конкретной метке и значению.
`search_user`	Ищет оборудование пользователя по значению метки. Используется в глобальной форме поиска.
`show`	Показывает возможные метки для компонента. (Реализация в коде пуста, метод в whitelist)

traffic_plans.php¶

Модуль управления тарифными планами трафика: создание, удаление, обновление и получение списка доступных планов с фильтрацией по серверу или локации и конвертацией цен.

Метод	Описание
`list`	Возвращает список подходящих тарифных планов трафика для указанного сервера (id) или локации (location). Поддерживает фильтрацию по типу оборудования и конвертацию цен в EUR/USD/RUB.

vm.php¶

Модуль управления виртуальными машинами (VM), предоставляющий API для создания, получения, удаления и восстановления снапшотов, а также загрузки статистики.

Метод	Описание
`create_snapshot`	Инициирует создание снапшота для указанной виртуальной машины. Возвращает ключ задачи для отслеживания статуса.
`get_snapshot`	Возвращает список снапшотов и настройки для указанной виртуальной машины.
`load_stats`	Инициирует загрузку статистики использования ресурсов для виртуальной машины.
`remove_snapshot`	Инициирует удаление снапшота с указанным именем.
`restore_snapshot`	Инициирует восстановление состояния виртуальной машины из снапшота.
`update_restore_settings`	Обновляет настройки автоматического восстановления и ротации снапшотов для указанной виртуальной машины.

whmcs.php¶

Модуль интеграции с WHMCS для управления клиентами, счетами, кредитом, отменами заказов и биллинговыми данными серверов.

Метод	Описание
`add_contact`	Добавляет новый контакт к существующему клиенту в биллинге.
`apply_credit`	Применяет кредит с баланса клиента к оплате указанного счета.
`create_addfunds`	Создает счет для пополнения баланса (Add Funds).
`delete_cancellation_request`	Удаляет активный запрос на отмену сервера и восстанавливает счет.
`delete_contact`	Удаляет контакт из аккаунта клиента.
`download_invoice`	Генерирует и возвращает PDF файл счета.
`generate_due_invoice`	Генерирует следующий счет для оплаты сервера.
`get_billing_data`	Получает синхронизированные данные биллинга для сервера.
`get_cancellation_requests`	Возвращает список активных запросов на отмену серверов.
`get_client`	Возвращает информацию об авторизованном клиенте или по ID.
`get_clientgroups`	Возвращает список групп клиентов в биллинге.
`get_contacts`	Возвращает список дополнительных контактов клиента.
`get_invoice`	Возвращает данные конкретного счета.
`get_invoices`	Возвращает список счетов клиента.
`get_related_invoices`	Возвращает счета, связанные с сервером или аккаунтом.
`getcredits`	Возвращает историю кредитов клиента.
`getpaymentgw`	Возвращает доступные методы оплаты для счета.
`mass_pay`	Оплачивает несколько счетов одним платежом.
`request_cancellation`	Инициирует процесс отмены сервера с расчетом возврата средств.
`request_subscription_cancellation`	Инициирует процесс отмены банковской подписки для указанного сервера через создание тикета в JIRA. Проверяет наличие активной подписки и статус предыдущих запросов.
`reset_password`	Инициирует сброс пароля или устанавливает новый с 2FA.
`transactions`	Возвращает историю транзакций клиента.
`update_client`	Обновляет данные профиля клиента в биллинге.
`update_contact`	Обновляет данные контакта клиента.