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

Документация 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 Инициирует повторную отправку кода двухфакторной аутентификации (2FA) на привязанный канал связи пользователя.
billing_list Возвращает список активных сервисов и данных о биллинге пользователя
email_check Проверяет существование клиента по его адресу электронной почты и возвращает связанные с ним теги.
flip_tag Переключает состояние (активен/неактивен) указанного тега для пользователя или сущности
get_log Возвращает лог событий авторизации за указанный период или по токену.
get_log_details Возвращает детальную информацию о событии в журнале авторизации по предоставленному токену
github_init Инициализирует процесс авторизации через GitHub для получения токена доступа
github_signin Выполняет вход в систему с использованием учетной записи GitHub, генерирует токен доступа и устанавливает сессию пользователя.
google_signin Выполняет вход в систему с использованием учетной записи Google для получения токена доступа
info Возвращает информацию о текущем состоянии аутентификации и данных пользователя
login Выполняет вход в систему, создавая новую сессию пользователя и возвращая данные авторизованного клиента.
logout Завершает текущую сессию пользователя и аннулирует токен доступа
session_reset Сбрасывает активную сессию пользователя, аннулируя текущие токены доступа.
set_tag Массовая вставка или обновление тегов для указанных компонентов. Поддерживает валидацию и логирование истории.
tg_verify Проверяет валидность данных авторизации через Telegram для подтверждения личности пользователя
vk_init Инициализирует процесс авторизации или настройки параметров для интеграции с VK
vk_signin Выполняет авторизацию пользователя с использованием данных социальной сети ВКонтакте.
whmcslogin Выполняет вход в систему. Поддерживает стандартную авторизацию (email/password) и SSO-методы (Google, GitHub, VK). При успешном входе возвращает токен сессии, данные клиента и права доступа.

eq.php

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

Метод Описание
abort_reinstall Прерывает процесс переустановки операционной системы, удаляет связанные теги (reinstall_start, autodeploy_start, autodeploy_timeout), сбрасывает сетевой интерфейс (если это не OpenStack) и обновляет логи развертывания.
add_ipmi_admin Создает учетную запись администратора IPMI для сервера. Если у клиента есть тег admin_ipmi, можно задать свои логин и пароль.
add_ipmi_user Создает нового пользователя для управления через интерфейс IPMI на сервере
announceip Выполняет процедуру объявления (announcement) IP-адреса в сети оборудования
backup_get_schedule Возвращает информацию о расписании резервного копирования для указанного сервера или группы серверов
backup_list Возвращает список доступных резервных копий для оборудования
backup_save_schedule Сохраняет настройки расписания для резервного копирования оборудования в очередь задач
boot_dev Запрос на загрузку сервера с указанного носителя (PXE или диск)
check_backup_lock Проверяет наличие активной блокировки на выполнение операции резервного копирования для конкретного сервера.
check_pin Проверяет PIN-код для операций.
clear_pxe Очищает PXE-конфигурацию для конкретного хоста. Метод асинхронный, возвращает callback для отслеживания выполнения задачи.
console Инициирует сессию удаленного доступа к консоли сервера через AMQP очередь
create_backup Запускает процесс создания резервной копии для указанного сервера через очередь задач
create_pxe Инициирует процесс переустановки операционной системы на сервере с использованием технологии PXE. Поддерживает выбор OS, настройку параметров диска, SSH-ключей и выполнение скриптов после установки.
delete_backup Инициирует процесс удаления резервной копии оборудования через очередь задач
deploy Запускает процесс развертывания конкретного сервера по его ID или выбирает доступный сервер из указанного пресета в определенной локации.
get_ipmi Возвращает список доступных IPMI интерфейсов для указанного сервера, включая модель и данные о доступе (IP, логин, пароль), если настроен проброс портов.
get_traffic Возвращает данные о потреблении сетевого трафика для указанного ресурса или сервера
get_upgrade_key Возвращает ключ для выполнения операции обновления системы
getserversforannounce Возвращает список серверов, доступных для размещения анонсов на основе заданных параметров фильтрации
groups Возвращает список групп пресетов для конкретного сервера по его ID
hard_off Отправляет запрос на принудительное (жесткое) выключение сервера. Операция выполняется асинхронно через очередь.
history Возвращает историю событий сервера.
list Возвращает список доступного оборудования с учетом фильтрации по параметрам
off Отправляет запрос на корректное выключение сервера по его ID
on Отправляет запрос на включение (start) сервера по его ID. Если сервер находится в режиме ожидания, снимается блокировка администратора.
order_instance Запускает процесс развертывания нового сервера по пресету, заказа стокового сервера или инициирует переустановку существующего сервера с выбором ОС и дополнительного ПО.
ovirt_novnc Запрашивает доступ к консоли oVirt через протокол noVNC для указанного сервера.
reboot Инициирует процесс перезагрузки указанного сервера. Если сервер находится в локации RU, отправляется соответствующее уведомление клиенту.
reinstall Инициирует процесс переустановки операционной системы на сервере. Создает ключ операции и ставит задачу в очередь.
remove_ipmi_user Удаляет лишних пользователей IPMI с сервера. Операция выполняется асинхронно через очередь.
request_backup_link Инициирует процесс создания резервной копии и возвращает ссылку для скачивания или идентификатор задачи.
restore_backup Запускает процесс восстановления сервера из выбранного резервного экземпляра через очередь задач.
search Возвращает список серверов, отфильтрованных по заданным параметрам (группа, локация, статус, IP и др.) с дополнительной информацией о пребиллинге и тегах.
sensors Возвращает текущие показания сенсоров для указанного сервера. Метод является асинхронным и возвращает callback для отслеживания завершения запроса.
set_pin Устанавливает PIN-код для операций.
show Возвращает полные технические данные о сервере: конфигурацию оборудования, операционную систему, сетевые интерфейсы, IP-адреса и информацию IPMI.
status Возвращает текущий статус сервера по его ID. Операция является асинхронной.
status_check Проверяет текущий статус оборудования по его идентификатору.
suspend Выполняет запрос на приостановку (suspend) или снятие блокировки (unsuspend) VPS/сервера. Если действие — suspend, сервер блокируется; если unsuspend — разблокируется.
traffic_add Добавляет объем трафика для услуги или сервера в систему биллинга
unified_server_search Единый поиск серверов по запросу.
unit_reset Отправляет запрос на выполнение IPMI reset (перезагрузку) выбранного сервера через контроллер управления.
unsuspend Запрашивает разблокировку (unsuspend) VPS или физического сервера. Если операция проходит успешно, возвращает callback для отслеживания процесса.
update_servers Синхронизирует список активных и ожидающих оплаты серверов клиента, собирает ключи развертывания (deploy keys) и данные о состоянии узлов.

eq_callback.php

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

Метод Описание
check Проверяет наличие активной задачи в очереди AMQP по ключу и возвращает текущий статус, контекст выполнения и отладочную информацию.
reinstall Обрабатывает завершение процесса переустановки сервера, обновляет статус в биллинге (WHMCS), отправляет уведомления клиенту и финализирует теги.

ip.php

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

Метод Описание
get_client_ip Возвращает IP-адрес клиента, совершившего запрос к API
get_ip Возвращает полную информацию о конкретном IP-адресе: сетевые данные, маску подсети и другие параметры.
get_ptr Возвращает текущую PTR-запись для указанного IP-адреса, если он закреплен за сервером в данной локации
get_traffic Возвращает данные о сетевом трафике (in/out) для указанного IP-адреса за выбранный период. Поддерживает получение сводной информации или детальных тиков.
list_free_ip Возвращает список неиспользуемых IPv4 адресов для указанной локации на основе тегов Route Reflector. Для клиентов доступны только те подсети, которые привязаны к их email или subaccount.
set_main Устанавливает указанный IPv4 адрес в качестве основного (main) адреса для сервера. При необходимости обновляет данные в биллинговой системе WHMCS.
update_ptr Обновляет PTR-запись для IP-адреса, закрепленного за сервером. Проверяет наличие связи между IP и ID сервера перед выполнением операции.

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 через Microtic для указанного сервера с поддержкой ACL и TTL.
remove_static_nat Удаляет статический NAT passthrough для указанного сервера или белого IP.

net.php

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

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

os.php

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

Метод Описание
list Возвращает список доступных операционных систем, отфильтрованных по параметрам оборудования (CPU, RAM, HDD), типу виртуализации (VM, BM, GPU, VDS) и лицензионным ограничениям сервера или пресета.

pdns.php

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

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

presets.php

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

Метод Описание
groups Возвращает список доступных групп пресетов
info Возвращает детальную информацию о пресете по его идентификатору или имени
list Возвращает список всех доступных пресетов с учетом прав доступа пользователя и локации.
search Поиск подходящих серверов на основе параметров пресета (имя, область поиска и локация)
show Возвращает детальную информацию о пресете по его ID, включая связанные теги и параметры конфигурации

rhr.php

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

Метод Описание
add Создает новый запрос Remote Hands (RHR). Поддерживает типы KVM, UNBLOCK и SERVICE. При наличии клиента автоматически создает тикет в системе поддержки.
chat Отправляет сообщение в существующий запрос Remote Hands, обновляет историю переписки и при необходимости создает тикет поддержки.
discard Утилизирует (отменяет) запрос Remote Hands по его ID. Если предоставлен текст ответа, он сохраняется в историю логов клиента.
list Возвращает список доступных задач Remote Hands с возможностью фильтрации по датам, статусам и локациям. Для клиентов дополнительно возвращается история изменений.

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, связанный с клиентом через WHMCS
get_buckets Метод закомментирован в коде, но предназначен для получения информации о бакетах S3 пользователя, включая использование трафика и снапшоты.
get_buckets_rmq Возвращает информацию об аккаунте S3: список бакетов, объем использованного хранилища, квоту, историю использования (metering), данные биллинга и учетные данные доступа.
get_files Возвращает список доступных файлов в S3 хранилище
get_users Возвращает список пользователей, связанных с S3 хранилищем, с возможностью фильтрации по параметрам
history Возвращает историю событий или логов, связанных с S3 хранилищем
list_plans Возвращает список доступных S3 тарифных планов с параметрами конфигурации и ценами
show_key Возвращает информацию о ключе доступа S3 на основе имени бакета и региона

software.php

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

Метод Описание
list Возвращает список доступного программного обеспечения с указанием тегов и параметров совместимости

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 Применяет доступный баланс клиента (кредит) для оплаты выбранного счета (invoice). Если счет оплачен полностью, может быть инициировано очищение оверюза трафика.
create_addfunds Создает инвойс для пополнения баланса клиента (Add Funds) в системе WHMCS. Поддерживает автоматическое включение подписки при определенных условиях.
delete_cancellation_request Удаляет запрос на отмену для конкретного сервера, если он существует. Позволяет восстановить отмененный инвойс или сгенерировать новый.
delete_contact Удаляет контакт клиента из WHMCS и удаляет связанные записи о пользователе в организации.
download_invoice Возвращает PDF-файл счета (инвойса) в формате base64 для указанного ID пользователя и локации биллинга.
generate_due_invoice Генерирует следующий счет на оплату для сервера в WHMCS, если не нарушены условия (отсутствие неоплаченных счетов или наличие специфических тегов апгрейда).
get_billing_data Возвращает подробную информацию о биллинговых данных сервера, включая данные клиента, статус EU-withdrawal и лицензионные расходы в валюте ЕС.
get_cancellation_requests Возвращает список активных запросов на отмену услуг (из WHMCS и Prebill) с фильтрацией по датам, типу отмены и статусу биллинга.
get_client Возвращает подробную информацию о авторизованном клиенте из WHMCS, включая данные профиля, группу, внутренние теги и кастомные поля.
get_clientgroups Возвращает список доступных групп клиентов из WHMCS для указанной локации.
get_contacts Возвращает список дополнительных контактов для клиента WHMCS с проверкой прав доступа к ним.
get_invoice Возвращает детальную информацию об инвойсе из WHMCS, включая данные клиента и валюту.
get_invoices Возвращает список счетов (инвойсов) для конкретного клиента из WHMCS. Если запрос сделан от лица клиента, возвращаются только его счета.
get_related_invoices Возвращает список инвойсов, связанных с конкретным сервером или аккаунтом пользователя
getcredits Возвращает историю транзакций и текущий баланс кредитов пользователя в WHMCS
getpaymentgw Возвращает список доступных платежных шлюзов для конкретного инвойса с обработанными ссылками и формами оплаты.
mass_pay Создает массовый платеж по списку указанных ID инвойсов в WHMCS.
request_cancellation Инициирует процесс автоматической или ручной отмены услуги (сервера) в WHMCS с расчетом возврата средств, учетом трафика и проверкой условий контракта.
request_subscription_cancellation Инициирует процесс отмены банковской подписки через создание тикета в JIRA и уведомление биллинга. Проверяет статус подписки в WHMCS и наличие открытых тикетов.
reset_password Инициирует процесс сброса пароля. Если передан reset_token, проверяет его валидность и отправляет 2FA код или обновляет пароль. Если токен отсутствует, отправляет ссылку на сброс на email клиента.
transactions Возвращает список транзакций пользователя на основе предоставленного ID транзакции или инвойса
update_client Обновляет персональные данные, контактную информацию, настройки 2FA и конфигурационные поля (custom fields) клиента в WHMCS.
update_contact Обновляет информацию о контакте (имя, фамилия, email, телефон) в WHMCS. Включает проверку прав доступа и валидацию форматов.
question_mark
Я могу вам чем-то помочь?
question_mark
ИИ Помощник ×