Перейти к содержанию

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

eq.php

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

Метод Описание
abort_reinstall Прекращает процесс переустановки сервера, удаляет связанные теги (reinstall_start, autodeploy_start, autodeploy_timeout) и восстанавливает настройки VLAN.
add_ipmi_admin Создает пользователя с правами администратора для управления через IPMI. Если пользователь уже существует, возвращает его данные.
add_ipmi_user Добавляет нового пользователя или администратора в систему управления IPMI сервера. Если указан admin_user, создается учетная запись с правами администратора.
announceip Выполняет анонс указанной подсети или конкретного IP-адреса для сервера через BGP.
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. Включает настройку параметров загрузки, SSH-ключей и скриптов post-install.
delete_backup Удаляет указанный бэкап сервера. Требуется наличие прав доступа к серверу.
deploy Запускает процесс развертывания (деплоя) выбранного оборудования или пресета на основе предоставленных параметров конфигурации.
get_ipmi Возвращает список доступных IPMI интерфейсов сервера, включая их IP-адреса и модель (vendor).
get_traffic Возвращает данные об использовании IPv4 трафика для указанного сервера
get_upgrade_key Возвращает ключ апгрейда (upgrade_key), привязанный к конкретному инвойсу через теги оборудования.
getserversforannounce Возвращает список активных (rent, power_off) серверов пользователя, которые прошли проверку на соответствие лимитам масок подсетей (/23 и /24).
groups Возвращает список групп для указанного сервера
hard_off Отправляет запрос на принудительное (жесткое) выключение оборудования по указанному ID.
history Возвращает историю событий сервера.
list Возвращает список оборудования по различным критериям поиска.
off Выключает сервер.
on Включает сервер.
order_instance Запуск процесса заказа нового сервера или переустановки существующего (reinstall) с выбором ОС, софта и параметров сети.
ovirt_novnc Запрашивает открытие консоли NoVNC для сервера, работающего на гипервизоре oVirt. Требует наличия прав доступа к серверу.
reboot Отправляет запрос на перезагрузку оборудования по указанному ID. Если запрос выполняется успешно, возвращается callback для отслеживания задачи.
reinstall Создает ключ для процесса переустановки сервера и подготавливает этап создания PXE-конфигурации.
remove_ipmi_user Удаляет дополнительные учетные записи пользователей IPMI для указанного сервера.
request_backup_link Запрашивает генерацию временной ссылки для скачивания резервной копии сервера.
restore_backup Запускает процесс восстановления сервера из указанного бэкапа. Операция асинхронная, возвращает callback для отслеживания статуса.
search Возвращает список доступного оборудования (серверов, VPS и др.) на основе заданных фильтров. Поддерживает поиск по ID, IP, MAC-адресу, владельцу, локации, типу и другим параметрам.
sensors Возвращает текущие показания датчиков для указанного сервера.
set_pin Устанавливает PIN-код для операций.
show Возвращает полные данные о сервере, включая аппаратную конфигурацию (hardware), операционную систему, IP-адреса, интерфейсы и IPMI.
status Возвращает текущий статус сервера и данные о его состоянии через IPMI/консоль
status_check Возвращает текущий статус оборудования (доступность, состояние компонентов)
suspend Запрашивает приостановку (suspend) или разблокировку (unsuspend) VPS/сервера. Требуется наличие прав доступа и проверка на блокировки.
traffic_add Увеличивает лимит исходящего трафика для сервера и создает соответствующий инвойс в WHMCS.
unified_server_search Единый поиск серверов по запросу.
unit_reset Запрашивает сброс устройства (IPMI reset) для указанного сервера.
unsuspend Запрос на снятие блокировки (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-хранилище, регистрирует пользователя, создает бакет и оформляет платеж.
delete_account Полностью удаляет S3 аккаунт пользователя, включая аудит действий и логирование истории. Требует указания ID клиента (для админов) или использует текущего пользователя, а также s3uid целевого аккаунта.
delete_bucket Удаляет указанный бакет S3. Проверяет права доступа и принадлежность бакета пользователю.
delete_file Удаляет указанный файл из S3-бакета. Требует валидации токена и проверки прав доступа к 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-плана или сущности по 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 Обновляет данные контакта клиента.
question_mark
Я могу вам чем-то помочь?
question_mark
ИИ Помощник ×