Документация 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, LDAP, API-ключи и SSO (Google, GitHub, VK), верификация 2FA, SMS и email, а также управление тегами клиентов.

Метод	Описание
`2fa_check`	Проверяет код двухфакторной аутентификации, переданный в параметре user_token.
`2fa_resend`	Запрашивает повторную отправку кода 2FA на привязанный метод.
`billing_list`	Возвращает список доступных биллинговых систем (WHMCS) для текущего домена или пользователя.
`email_check`	Инициализирует или проверяет верификацию email адреса пользователя.
`flip_tag`	Устанавливает или удаляет тег у клиента (например, auto_credit).
`get_log`	Возвращает лог событий авторизации за указанный период или по токену.
`get_log_details`	Возвращает подробную информацию о конкретном событии лога по токену.
`github_init`	Возвращает данные для инициализации OAuth потока с GitHub.
`github_signin`	Обработка OAuth кода от GitHub для входа или привязки аккаунта.
`google_signin`	Обработка JWT токена от Google для входа или привязки аккаунта.
`info`	Возвращает информацию о текущей сессии, правах доступа, серверах и биллинге.
`login`	Авторизация клиента или сервера по API ключу.
`logout`	Очищает текущий токен сессии.
`session_reset`	Сбрасывает все активные сессии пользователя по email и токену сброса.
`set_tag`	Устанавливает или удаляет тег у клиента с возможностью указания значения.
`tg_verify`	Привязывает Telegram username к аккаунту пользователя.
`vk_init`	Возвращает данные для инициализации OAuth потока с VK ID.
`vk_signin`	Обработка OAuth кода от VK для входа или привязки аккаунта.
`whmcslogin`	Основной метод входа через учетные данные WHMCS (email/password) или SSO.

eq.php¶

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

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

eq_callback.php¶

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

Метод	Описание
`check`	Проверяет текущий статус задачи по ключу (key) и возвращает контекст выполнения, если задача завершена или находится на промежуточном этапе.
`reinstall`	Обработчик колбэка от worker-а после завершения операции переустановки (reinstall). Обновляет статус сервера, очищает временные теги, отправляет письмо клиенту с данными доступа и обновляет биллинг.

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-образ или обновляет существующий по имени.
`delete`	Удаляет ISO-образ по ID.
`list_iso`	Возвращает список доступных ISO-образов.
`mount_iso`	Монтирует ISO-образ на указанный сервер.
`unmount_iso`	Размонтирует ISO-образ с указанного сервера.
`upload`	Загружает ISO-образ по URL.
`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. Поддерживает выбор конкретных адресов или автоматический подбор свободных.
`block_ip`	Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Принимает причину блокировки и флаг blackhole.
`get_status`	Возвращает текущий статус сетевого интерфейса (порт) для указанного сервера. Автоматически определяет порт, если не указан явно.
`port_off`	Отключает указанный сетевой порт сервера. Если передан параметр reason, добавляется тег блокировки с указанной причиной.
`port_on`	Включает указанный сетевой порт сервера, снимая блокировку (tag 'block'), если она была наложена пользователем.
`remove_ipv4`	Удаляет один или все IPv4 адреса с указанного сервера. Очищает PTR-записи в DNS.
`show_cacti`	Возвращает данные графиков мониторинга Cacti для указанного сервера и порта.
`show_ipv4_free`	Возвращает список доступных свободных IPv4 адресов для указанного сервера, порта и VLAN. Поддерживает фильтрацию по тегам и периоду свежести.
`unblock_ip`	Разблокирует указанный IP-адрес на сервере, удаляя правила блокировки в BIRD и снимая теги блокировки.

os.php¶

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

Метод	Описание
`list`	Возвращает список операционных систем. При указании id или instance_id фильтрует ОС по совместимости с оборудованием или пресетом. Возвращает также список исключенных ОС.

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`	Возвращает список пресетов с ценами в указанных валютах по умолчанию EUR и RUB
`list`	Возвращает список доступных пресетов серверов с фильтрацией по локации и правам доступа
`search`	Поиск подходящих серверов для конкретного пресета по имени, области видимости и локации.
`show`	Возвращает информацию о пресете по ID или имени. Поддерживает фильтрацию и лимиты.

rhr.php¶

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

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

s3.php¶

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

Метод	Описание
`cancel_payment_account_deletion`	Отменяет запланированное удаление оплаченного 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`	Возвращает список бакетов S3 для указанного пользователя, включая информацию об использовании хранилища, пропускной способности, снапшотах и ключи доступа.
`get_buckets_rmq`	Возвращает список бакетов S3 для указанного пользователя, включая информацию об использовании хранилища, пропускной способности, снапшоты и учетные данные доступа.
`get_files`	Возвращает список файлов и папок в указанном S3 бакете с поддержкой пагинации и поиска.
`get_users`	Возвращает список S3-аккаунтов с информацией о сервисе, трафике и использовании хранилища. Для администраторов поддерживает фильтрацию и пагинацию.
`history`	Возвращает историю изменений для указанного S3-плана или аккаунта по ID.
`list_plans`	Возвращает список доступных тарифных планов S3. Для клиентов скрывает неактивные планы (если нет тега s3_test), для администраторов может вернуть конкретный план по ID.
`show_key`	Возвращает расшифрованный ключ доступа (access_key или secret_key) для указанного S3-аккаунта.

software.php¶

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

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

stocks.php¶

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

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

tags.php¶

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

Метод	Описание
`add`	Добавляет пользовательский тег к серверу или компоненту. Поддерживает добавление к одному ID или списку ID через параметр id_list. Для клиентов доступны только определенные теги.
`clear`	Очищает все или неэссенциальные метки от компонента. Для клиентов доступны только публичные метки.
`get`	Получает метки для компонента. (Реализация в коде пуста, метод в whitelist)
`list`	Возвращает список тегов для указанного сервера или компонента. Для клиентов доступны только публичные теги.
`remove`	Удаляет указанный тег с компонента (сервера) по имени тега. Поддерживает удаление с одного ID или списка ID через 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`	Обновляет данные контакта клиента.