Документация 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 ключ аккаунта, а не конкретного сервера (и наоборот), поэтому при ошибках авторизации метода попробуйте переключить тип API-ключа.

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`	Подтверждает код двухфакторной аутентификации, отправленный на email или телефон пользователя. Требует действующего токена сессии.
`2fa_resend`	Повторно отправляет код двухфакторной аутентификации на привязанный канал связи (email или SMS). Требует валидного токена сессии.
`billing_list`	Возвращает список доступых биллинговых систем (WHMCS) для текущего домена развертывания. Если передан валидный токен, возвращает биллинг, привязанный к пользователю, иначе — все доступные.
`email_check`	Валидация email клиента, отправка кода подтверждения или проверка введенного кода. Используется для верификации адреса электронной почты.
`flip_tag`	Переключает состояние указанного тега для текущего клиента. Если тег существует, он удаляется. Если не существует, он создается. Доступен только для разрешенных тегов (например, 'auto_credit' для клиентов).
`get_log`	Возвращает лог событий авторизации за указанный период или по токену.
`get_log_details`	Возвращает подробную информацию о записи лога авторизации по указанному токену пользователя. Требует валидного токена сессии и права доступа auth/get_log.
`github_init`	Возвращает параметры для инициализации процесса авторизации через GitHub (client_id и redirect_uri).
`github_signin`	Завершает процесс авторизации через GitHub OAuth. Обменивает код на токен, получает данные пользователя и привязывает аккаунт GitHub к текущей сессии или создает новую SSO-связь.
`google_signin`	Обработка входа через Google SSO. Привязывает аккаунт Google к текущей сессии или возвращает хеш для последующего входа.
`info`	Возвращает детальную информацию о текущем токене: роль, права доступа, список серверов, статус верификации, настройки биллинга и приватные IP-диапазоны.
`login`	Возвращает токен доступа и информацию о клиенте на основе предоставленного API-ключа. Проверяет права доступа, привязку к IP и наличие активных серверов.
`logout`	Очищает токен доступа пользователя, завершая текущую сессию.
`session_reset`	Принудительно завершает все активные сессии пользователя по email и токену сброса, очищает связанные теги и перенаправляет на страницу входа.
`set_tag`	Устанавливает или удаляет указанный тег для текущего пользователя. Доступен только для администраторов или для тега 'auto_credit' для клиентов.
`tg_verify`	Привязывает указанный username Telegram к аккаунту текущего пользователя и возвращает ссылку на бота уведомлений.
`vk_init`	Возвращает данные для инициализации OAuth потока с VK ID.
`vk_signin`	Обработка колбэка от VK ID после авторизации. Обменивает код на токен, проверяет state и code_verifier, привязывает SSO-хеш к аккаунту клиента или перенаправляет на страницу входа с SSO-параметрами.
`whmcslogin`	Выполняет вход в систему с использованием учетных данных WHMCS (email/пароль) или SSO. Возвращает токен сессии, информацию о пользователе, права доступа и статус 2FA.

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`	Инициирует заказ нового сервера из пресета или переустановку (reinstall) существующего сервера. Выполняет проверку баланса, лицензий, совместимости ОС и создает задачу в очереди деплоя.
`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-запись (обратное DNS-имя) для указанного IP-адреса, привязанного к серверу.
`get_traffic`	Возвращает статистику входящего и исходящего трафика для указанного IP-адреса за заданный период. Поддерживает режим сводки или детализации по временным меткам.
`list_free_ip`	Возвращает список неиспользуемых IP-адресов для указанной локации или подсети. Для клиентов используется ID подсети, для администраторов — код локации.
`set_main`	Устанавливает указанный IP-адрес как основной для интерфейса сервера. Обновляет данные биллинга в WHMCS, если применимо.
`update_ptr`	Устанавливает обратную DNS запись (PTR) для указанного 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 адресов к серверу или назначает конкретные IP-адреса. Поддерживает автоматический поиск свободных IP в VLAN или ручное указание списка.
`block_ip`	Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Требует аутентификации.
`get_status`	Возвращает текущий статус и конфигурацию сетевого порта сервера. Требует аутентификации.
`port_off`	Отключает указанный сетевой порт сервера и добавляет тег блокировки с указанной причиной.
`port_on`	Включает указанный сетевой порт сервера, снимая блокировку (tag 'block'), если она не установлена администратором.
`remove_ipv4`	Удаляет указанный IPv4 адрес с сервера. Если передан флаг remove_all, удаляет все адреса.
`show_cacti`	Возвращает данные графика мониторинга трафика для указанного сервера и порта из системы Cacti.
`show_ipv4_free`	Возвращает список доступных IPv4 адресов для указанного сервера и интерфейса в заданной VLAN. Требует аутентификации.
`unblock_ip`	Снимает блокировку с указанного IP-адреса на сервере. Требует проверки прав доступа.

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-хранилище для указанного пользователя. Требуется валидный s3uid текущего клиента.
`create_order`	Создает новый заказ на S3-хранилище для клиента. Валидирует тарифный план, проверяет лимиты бесплатных аккаунтов или кредиты, создает пользователя S3, бакет и сервис биллинга.
`delete_account`	Полностью удаляет S3 аккаунт пользователя. Требует указания идентификатора клиента (для администратора) или используется ID текущего пользователя, а также s3uid целевого аккаунта.
`delete_bucket`	Удаляет указанный бакет S3. Проверяет права доступа и принадлежность бакета пользователю.
`delete_file`	Удаляет указанный файл из S3-бакета. Требует валидации токена и проверки прав доступа клиента.
`delete_payment_account`	Инициирует отмену платного S3-аккаунта. Устанавливает дату отмены для сервиса, связанный с указанным s3uid.
`get_buckets`	Возвращает список бакетов для указанного S3-аккаунта, включая информацию об использовании хранилища, квоте, метриках и ключах доступа. Использует асинхронный запрос через очередь задач.
`get_buckets_rmq`	Возвращает список бакетов пользователя S3, информацию об использовании хранилища, квоте, метриках трафика и ключах доступа. Использует очередь сообщений (RMQ) для получения актуальных данных.
`get_files`	Возвращает список файлов и папок в указанном S3-бакете с поддержкой пагинации и поиска.
`get_users`	Возвращает список пользователей S3 с информацией о трафике, использовании хранилища и статусе сервиса. Поддерживает фильтрацию по ID клиента, ID плана, email, billing, s3uid, bucket_name, storage_type. Для администраторов доступны сортировка и пагинация.
`history`	Возвращает историю изменений или событий, связанных с указанным тарифным планом S3.
`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`	Обновляет данные контакта клиента.