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

Документация 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 Запрашивает повторную отправку кода двухфакторной аутентификации для пользователя. Если пользователь находится в режиме отладки, код возвращается в ответе.
billing_list Возвращает список доступных платежных систем (биллингов), доступных для текущего пользователя или администратора.
email_check Проверяет валидность email, отправляет код верификации или проверяет уже существующий код/токен для подтверждения адреса.
flip_tag Создает или удаляет указанный тег у пользователя. Если тег уже существует, он будет удален; если не существует — создан.
get_log Возвращает лог событий авторизации за указанный период или по токену.
get_log_details Возвращает подробную информацию о событиях аутентификации для текущего пользователя (через user_token)
github_init Возвращает необходимые данные для инициализации авторизации через GitHub (client_id и redirect_uri)
github_signin Выполняет обмен кода авторизации на access token GitHub и связывает аккаунт с пользователем (SSO). Если токен уже привязан, перенаправляет на страницу 'уже использовано', если нет — выполняет привязку.
google_signin Выполняет вход в систему с использованием Google ID Token. Если токен уже привязан к пользователю, метод связывает текущую сессию с этим аккаунтом.
info Возвращает подробную информацию о текущей сессии пользователя, включая роль, права доступа (permissions), данные клиента и список активных серверов.
login Авторизация через API-ключ клиента. Возвращает токен доступа, роль пользователя и список доступных серверов.
logout Очищает текущий токен доступа (access token)
session_reset Завершает все активные сессии пользователя, соответствующие предоставленному токену сброса, и очищает связанные теги.
set_tag Создает или удаляет тег у клиента. Позволяет устанавливать значения для определенных параметров (например, auto_credit) или просто переключать наличие тега.
tg_verify Привязывает Telegram username пользователя к его аккаунту и возвращает ссылку на бота для уведомлений.
vk_init Инициирует процесс авторизации через VK, генерируя временные параметры (code_challenge, state) и сохраняя их для последующей проверки при выполнении входа.
vk_signin Выполняет авторизацию пользователя через OAuth2 протокол VK. Обменивает код на токен и связывает аккаунт с пользователем.
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 для сервера. Если пользователь является администратором, используются предоставленные учетные данные.
announceip Выполняет анонсирование (announcement) указанной подсети или сервера для управления маршрутизацией трафика.
backup_get_schedule Возвращает текущее расписание резервного копирования для указанного сервера
backup_list Возвращает список доступных резервных копий для указанного сервера
backup_save_schedule Сохраняет настроенное расписание резервного копирования для указанного сервера
boot_dev Запрашивает перезагрузку сервера для загрузки с указанного носителя (PXE или диск) в зависимости от режима загрузки.
check_backup_lock Проверяет, заблокирован ли процесс резервного копирования для указанного сервера.
check_pin Проверяет PIN-код для операций.
clear_pxe Очищает текущую PXE конфигурацию для указанного хоста
console Запрашивает запуск консоли управления сервером через IPMI/NoVNC.
create_backup Инициирует процесс создания резервной копии для указанного сервера. Операция выполняется асинхронно.
create_pxe Запрашивает создание PXE-конфигурации для последующей переустановки ОС на сервере. Поддерживает настройку hostname, SSH-ключей и скриптов post-install.
delete_backup Удаляет указанный бэкап сервера по его имени
deploy Запускает процесс развертывания (деплоя) выбранного оборудования или пресета на основе предоставленных параметров конфигурации.
get_ipmi Возвращает IP-адрес и модель интерфейса IPMI для указанного сервера. Может содержать несколько интерфейсов.
get_traffic Возвращает данные об использовании IPv4 трафика для указанного сервера
get_upgrade_key Возвращает ключ для выполнения операции апгрейда, привязанный к конкретному счету (invoice_id). Если теги с ключом не найдены, возвращается пустая строка.
getserversforannounce Возвращает список активных серверов пользователя, которые прошли проверку на ограничения по маскам подсетей (mask_23/mask_24) и доступны для анонсирования IP.
groups Возвращает список групп для конкретного сервера
hard_off Отправляет команду на принудительное (жесткое) выключение оборудования через IPMI/BMC.
history Возвращает историю событий сервера.
list Возвращает список доступного или арендованного оборудования с фильтрацией по различным параметрам (локация, статус, тип и др.)
off Выключает сервер.
on Включает сервер.
order_instance Запуск процесса развертывания нового сервера из пресета или переустановки существующего сервера с выбором ОС и дополнительного ПО.
ovirt_novnc Запрашивает доступ к консоли NoVNC для сервера через oVirt. Требует авторизации и наличия прав доступа.
reboot Отправляет запрос на перезагрузку указанного оборудования через IPMI или системные средства.
reinstall Создает ключ для начала этапа переустановки сервера и ставит задачу в очередь (stage: create_pxe).
remove_ipmi_user Удаляет дополнительные учетные записи пользователей IPMI для указанного сервера.
request_backup_link Запрашивает генерацию временной ссылки для скачивания резервной копии сервера.
restore_backup Запускает процесс восстановления сервера из существующего бэкапа по имени файла.
search Возвращает список доступных серверов по различным фильтрам (группа, локация, статус, тип и др.)
sensors Возвращает данные о состоянии сенсоров для указанного сервера через IPMI.
set_pin Устанавливает PIN-код для операций.
show Возвращает подробную информацию о сервере, включая аппаратное обеспечение (hwconfig), текущий статус, IP-адреса, интерфейсы и IPMI.
status Возвращает текущий статус сервера и данные о его состоянии
status_check Выполняет проверку текущего состояния оборудования (статусов) через внутренние механизмы системы.
suspend Запрашивает приостановку (suspend) или разблокировку (unsuspend) VPS/сервера. Если действие suspend, сервер будет заблокирован.
traffic_add Создает инвойс на оплату дополнительного исходящего трафика для сервера. После оплаты лимит будет увеличен.
unified_server_search Единый поиск серверов по запросу.
unit_reset Запрашивает сброс настроек IPMI для указанного сервера. Если операция требует подтверждения, возвращается callback.
unsuspend Разблокирует сервер (unsuspend), если он был временно приостановлен.
update_servers Обновляет список активных и ожидающих оплаты серверов для пользователя, включая проверку статусов в WHMCS и обработку пребил-заказов.

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 Отменяет процесс удаления сервиса (cancellation) для S3 аккаунта, восстанавливая его статус.
create_account Создает новый S3 аккаунт (bucket) для клиента, привязывает его к тарифному плану и создает заказ в биллинговой системе.
create_bucket Создает новый S3 bucket для пользователя. Проверяет принадлежность s3uid текущему клиенту и создает корзину через API провайдера.
create_order Создает новый S3 аккаунт, бакет и привязывает его к тарифному плану с автоматической оплатой через биллинг.
delete_account Удаляет S3 аккаунт пользователя, выполняя аудит действий и логирование в историю.
delete_bucket Удаляет указанную корзину (bucket) из хранилища S3, если она принадлежит пользователю.
delete_file Удаляет указанный файл из S3 бакета пользователя
delete_payment_account Запрашивает отмену сервиса S3 и последующее удаление платежного аккаунта. Возвращает информацию о дате отмены.
get_buckets Возвращает список S3 бакетов пользователя, включая информацию об использовании (bandwidth) и снимках (snapshots)
get_buckets_rmq Возвращает список бакетов пользователя, информацию об их использовании (usage), данные биллинга, метрики и учетные данные доступа к S3.
get_files Возвращает список файлов и папок в указанном бакете с поддержкой пагинации и поиска.
get_users Возвращает список пользователей S3 с детализацией по трафику, хранилищу и данным сервиса (billing/status)
history Возвращает историю событий, связанных с конкретным S3 аккаунтом или пользователем
list_plans Возвращает список доступных S3 планов с учетом прав пользователя и локации. Для администраторов возвращает полный список, для клиентов — только активные планы с ценами в их валюте.
show_key Возвращает расшифрованный секретный ключ или ключ доступа для указанного S3 аккаунта

software.php

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

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

stocks.php

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

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

tags.php

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

Метод Описание
add Добавляет пользовательский тег к серверу или компоненту. Поддерживает массовое добавление через список ID.
clear Очищает все или неэссенциальные метки от компонента. Для клиентов доступны только публичные метки.
get Получает метки для компонента. (Реализация в коде пуста, метод в whitelist)
list Возвращает список тегов для конкретного сервера или компонента. Для клиентов доступно ограничение по типу компонента (eq, vars).
remove Удаляет тег по его имени для конкретного компонента или удаляет все указанные теги из списка 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 Добавляет дополнительного контактного пользователя для существующего клиента в WHMCS. Если тип не указан, создается случайный контакт.
apply_credit Применяет сумму кредита (баланса) для оплаты конкретного инвойса в WHMCS. Если статус инвойса меняется на 'Paid', автоматически очищаются теги о перерасходе трафика.
create_addfunds Создает инвойс в WHMCS для пополнения баланса клиента на указанную сумму. Если включена опция subscribe, активируется автоматическое продление.
delete_cancellation_request Удаляет запрос на отмену для конкретного сервера, восстанавливая статус инвойса или позволяя создать новый.
delete_contact Удаляет дополнительный контакт, привязанный к клиенту в WHMCS.
download_invoice Возвращает PDF-файл инвойса в формате base64 для скачивания или просмотра.
generate_due_invoice Генерирует следующий счет для сервера в WHMCS, учитывая текущий цикл оплаты и наличие активных аддонов. Блокируется, если у клиента есть неоплаченные счета или если срок следующего платежа еще не наступил.
get_billing_data Возвращает детальную информацию о биллинговых данных конкретного сервера (синхронизированные данные из WHMCS)
get_cancellation_requests Возвращает список активных запросов на отмену для конкретного сервера или пользователя с учетом фильтрации по дате, типу и статусу оплаты.
get_client Возвращает подробную информацию о авторизованном клиенте, включая данные из WHMCS и внутренние данные системы (теги, верификация). Поддерживает расширенный режим получения данных через параметр full.
get_clientgroups Возвращает список доступных групп клиентов из WHMCS для указанной локации.
get_contacts Возвращает список дополнительных контактов, привязанных к клиенту в WHMCS. Если указан email, возвращаются только те контакты, которые имеют соответствующие права доступа.
get_invoice Возвращает детальную информацию о счете из WHMCS, включая данные клиента и статус оплаты.
get_invoices Возвращает список всех инвойсов, связанных с клиентом в выбранной локации WHMCS.
get_related_invoices Возвращает список всех инвойсов, связанных с конкретным сервером (через account_id)
getcredits Возвращает информацию о доступных кредитах на аккаунте пользователя в WHMCS.
getpaymentgw Возвращает список доступных платежных методов (шлюзов) для конкретного инвойса с обработанными ссылками на оплату.
mass_pay Позволяет произвести массовую оплату нескольких инвойсов клиента одним платежом. Требуется минимум 2 инвойса.
request_cancellation Инициирует процесс отмены заказа или подписки. Проверяет наличие активных лицензий, статус оплаты инвойсов и рассчитывает сумму возврата средств (refund) с учетом фактически использованного времени и лимитов трафика.
request_subscription_cancellation Инициирует процесс отмены банковской подписки для сервера. Создает JIRA тикет и вешает тег запроса на сервер.
reset_password Позволяет сбросить пароль пользователя. Если reset_token не предоставлен, отправляется ссылка на почту. Если токен известен, выполняется проверка 2FA и смена пароля.
transactions Возвращает список транзакций пользователя по конкретному инвойсу или ID транзакции
update_client Обновляет профиль клиента в WHMCS, включая персональные данные (имя, email), контактную информацию, настройки 2FA и кастомные поля (custom fields). Поддерживает обновление юридических данных для компаний.
update_contact Обновляет информацию о дополнительном контакте (имя, фамилия, email, телефон) для клиента в WHMCS. Поддерживает проверку уникальности email и верификацию номера телефона.
question_mark
Я могу вам чем-то помочь?
question_mark
ИИ Помощник ×