Документация API (интерфейс прикладного программирования) панели управления Invapi¶
В этой документации описан общий дизайн и принципы работы API, а также конкретные конечные точки. Также приведены примеры запросов к ним.
Информация
Панель управления invapi.hostkey.ru построена на основе этого API.
Запросы API¶
Запросы должны выполняться по протоколу HTTPS, чтобы гарантировать шифрование транзакций.
Для запросов необходимо использовать метод POST, если не указано иное.
Формат примеров API¶
Примеры в этой документации описаны с помощью сurl, HTTP-клиента командной строки. На компьютерах Linux и macOS обычно по умолчанию установлен curl, и он доступен для загрузки на всех популярных платформах, включая Windows.
Каждый пример разделен на несколько строк символом \, который совместим с bash. Типичный пример выглядит так:
Пример запроса POST:
Параметр -X задает метод запроса. Для согласованности метод будет указан во всех примерах, даже если он явно не требуется для методов GET.
Примеры, для которых требуется объект JSON в теле запроса, передают требуемые данные через параметр --data.
Ответ на запросы происходит в формате JSON и в документации отформатирован для удобочитаемости.
Примечание
Чтобы использовать приведенные примеры, не подставляя каждый раз в них свой токен, вы можете добавить токен один раз в переменные окружения в вашей консоли. Например, на Linux это можно сделать с помощью команды:
После этого токен будет автоматически подставляться в ваши запросы.
Примечание
Обратите внимание, что все значения в этой документации являются примерами. Не полагайтесь на идентификаторы операционных систем, тарифов и т.д., используемые в примерах. Используйте ваши значения серверов/сетей/доменов для получения значений или перед созданием ресурсов.
api_keys.php¶
Модуль управления API-ключами: создание, редактирование, удаление, просмотр истории и получение списков ключей для клиентов и серверов.
| Ресурс | Действие | Описание |
|---|---|---|
add | add | Создает новый API ключ для клиента или конкретного сервера. Требуется наличие активных серверов у клиента. |
delete | delete | Удаляет указанный API ключ из системы. |
edit | edit | Изменяет параметры существующего API ключа (название, IP, статус, срок действия). |
history | history | Возвращает историю действий с API ключами (создание, изменение, удаление). |
list | list | Возвращает список всех API ключей текущего клиента. |
list_for_server | list_for_server | Возвращает список API ключей, привязанных к конкретному серверу. |
view | view | Возвращает детальную информацию об одном API ключе. |
auth.php¶
Модуль аутентификации и авторизации: управление сессиями, вход через WHMCS, API-ключи, SSO (Google, GitHub, VK), двухфакторная аутентификация и проверка токенов.
| Ресурс | Действие | Описание |
|---|---|---|
info | info | Возвращает информацию о текущем токене, включая роль, права доступа, список серверов, статус верификации и настройки биллинга. |
login | login | Авторизация пользователя по API-ключу. Возвращает токен сессии, список доступных серверов и права доступа. |
logout | logout | Очищает указанный токен доступа, завершая сессию пользователя. |
whmcslogin | whmcslogin | Авторизация через учетные данные WHMCS (email/password) или SSO. Поддерживает выбор биллинга и двухфакторную аутентификацию. |
eq.php¶
Модуль управления оборудованием (eq.php) для операций с серверами: заказ, деплой, перезагрузка, управление питанием, IPMI, бэкапы и мониторинг.
| Ресурс | Действие | Описание |
|---|---|---|
add_ipmi_user | add_ipmi_user | Добавляет пользователя IPMI для указанного сервера. Генерирует случайный логин и пароль, если не переданы администратором. |
boot_dev | boot_dev | Загружает сервер с указанного носителя (PXE или диск). |
clear_pxe | clear_pxe | Очищает PXE конфигурацию для указанного сервера, позволяя перезагрузить процесс развертывания. |
create_pxe | create_pxe | Запрашивает переустановку сервера через PXE. |
list | list | Возвращает список доступного оборудования по различным критериям поиска. |
novnc | novnc | Инициализирует подключение к NoVNC консоли для указанного сервера. Возвращает ключ для отслеживания статуса операции. |
off | off | Запрашивает выключение сервера. |
on | on | Отправляет команду на включение сервера по указанному ID. Требует валидацию токена и проверки прав доступа. |
order_instance | order_instance | Заказывает новый сервер или переустанавливает существующий. |
reboot | reboot | Запрашивает перезагрузку сервера. |
recreate_novnc | recreate_novnc | Пересоздает NoVNC консоль для механизма callback. |
reinstall | reinstall | Запрашивает переустановку сервера (reinstall) через метод order_instance. |
remove_ipmi_user | remove_ipmi_user | Удаляет дополнительных пользователей IPMI. |
sensors | sensors | Запрашивает текущие показания датчиков (температура, напряжение, обороты) для указанного сервера. |
show | show | Возвращает данные о сервере и оборудовании. |
status | status | Получает статус сервера по ID. |
stop_novnc | stop_novnc | Прерывает сессию NoVNC консоли для указанного сервера. |
unit_reset | unit_reset | Запрашивает сброс IPMI сервера. |
update_servers | update_servers | Обновляет список активных серверов для текущего токена, проверяя статусы в биллинге и добавляя новые серверы в сессию. |
eq_callback.php¶
Модуль обработки асинхронных колбэков от worker-задач для управления оборудованием, серверами и виртуальными машинами. Обрабатывает статусы выполнения задач (deploy, reinstall, backup, network operati
| Ресурс | Действие | Описание |
|---|---|---|
check | check | Проверяет текущий статус асинхронной задачи по ключу (key) и возвращает результат выполнения, контекст и отладочную информацию. |
ip.php¶
Модуль управления IP-адресами и сетевой инфраструктурой: получение информации об IP, управление PTR-записями, отслеживание трафика, работа с подсетями и VLAN.
| Ресурс | Действие | Описание |
|---|---|---|
get_client_ip | get_client_ip | Возвращает IP-адрес текущего клиента |
get_ip | get_ip | Возвращает полную информацию о конкретном IP-адресе (сеть, маска и т.д.) |
get_ptr | get_ptr | Проверяет и возвращает PTR-запись для указанного IP |
get_traffic | get_traffic | Возвращает статистику входящего и исходящего трафика для IP за указанный период |
list_free_ip | list_free_ip | Возвращает список свободных IP-адресов для указанной локации или подсети |
set_main | set_main | Устанавливает указанный IP как основной для интерфейса сервера |
update_ptr | update_ptr | Обновляет PTR-запись (обратное DNS) для указанного IP |
jenkins.php¶
Модуль интеграции с Jenkins для управления задачами: получение списка доступных задач и их выполнение для серверов.
| Ресурс | Действие | Описание |
|---|---|---|
get_tasks | get_tasks | Возвращает список доступных задач Jenkins, доступных для текущего пользователя или клиента. |
jira.php¶
Модуль интеграции с Jira для создания тикетов поддержки по управлению серверами (питание, перезагрузка, KVM) и запросам на помощь продажам.
| Ресурс | Действие | Описание |
|---|---|---|
request_PXEboot | request_PXEboot | Создает тикет в Jira для ручной загрузки сервера с PXE, если отсутствует удаленное управление. |
request_assistance | request_assistance | Создает тикет в Jira для отдела продаж с деталями отмены или изменения услуги. |
request_check | request_check | Создает тикет в Jira для проверки и загрузки сервера в ОС при отсутствии удаленного управления. |
request_kvm | request_kvm | Создает тикет в Jira для подключения IP KVM к серверу. |
request_poff | request_poff | Создает тикет в Jira для ручного выключения питания сервера. |
request_pon | request_pon | Создает тикет в Jira для ручного включения питания сервера. |
request_reboot | request_reboot | Создает тикет в Jira для ручной перезагрузки сервера. |
nat.php¶
Модуль управления статическим NAT: добавление и удаление правил проброса IP-адресов через MikroTik.
| Ресурс | Действие | Описание |
|---|---|---|
add_static_nat | add_static_nat | Добавляет статический NAT passthrough для указанного сервера. Принимает ID сервера и ACL для IPMI. |
remove_static_nat | remove_static_nat | Удаляет статический NAT passthrough для указанного сервера или белого IP. |
net.php¶
Модуль управления сетевой инфраструктурой: добавление и удаление IP-адресов, блокировка трафика, управление состоянием сетевых портов, получение статистики и отображение графиков Cacti.
| Ресурс | Действие | Описание |
|---|---|---|
add_ipv4 | add_ipv4 | Добавляет указанное количество IPv4 адресов к серверу на конкретный порт и VLAN. Поддерживает выбор конкретных IP или автоматический подбор свободных. |
block_ip | block_ip | Блокирует указанный IP-адрес на сервере через BIRD или blackhole. Требует причину блокировки. |
get_status | get_status | Возвращает текущий статус сетевого интерфейса сервера (up/down, скорость, дуплекс, MAC). |
port_off | port_off | Отключает сетевой интерфейс сервера. Может добавлять тег блокировки с причиной. |
port_on | port_on | Включает сетевой интерфейс сервера. Удаляет тег блокировки, если он не был установлен администратором. |
remove_ipv4 | remove_ipv4 | Удаляет указанный IPv4 адрес или все адреса с сервера. Очищает PTR записи в DNS. |
show_cacti | show_cacti | Возвращает данные или ссылку на график трафика для указанного порта сервера из системы мониторинга Cacti. |
show_ipv4_free | show_ipv4_free | Возвращает список доступных свободных IPv4 адресов для указанного сервера, порта и VLAN. |
unblock_ip | unblock_ip | Разблокирует ранее заблокированный IP-адрес на сервере. Требует прав администратора или совпадения с причиной блокировки. |
os.php¶
Модуль управления операционными системами: предоставляет методы для добавления, удаления, обновления и получения списка ОС с фильтрацией по совместимости оборудования и лицензиям.
| Ресурс | Действие | Описание |
|---|---|---|
list | list | Возвращает список доступных операционных систем с фильтрацией по типу оборудования (VM, BM, GPU), лицензиям и локации. Поддерживает фильтрацию для конкретного сервера или пресета. |
pdns.php¶
Модуль управления DNS-записями и зонами: добавление, удаление и просмотр доменов, поддоменов и зон, а также получение информации о callback-URL.
| Ресурс | Действие | Описание |
|---|---|---|
add_dns | add_dns | Добавляет новую DNS-запись в указанную зону. |
add_domain | add_domain | Добавляет новый домен в систему DNS для указанного клиента. |
delete_dns | delete_dns | Удаляет указанную DNS-запись. |
delete_domain | delete_domain | Удаляет домен и все связанные с ним записи. |
get_cb_url | get_cb_url | Возвращает URL для callback-уведомлений. |
list_domains | list_domains | Возвращает список доменов клиента. |
list_zones | list_zones | Возвращает список DNS-зон. |
view_zone | view_zone | Возвращает детали указанной DNS-зоны. |
presets.php¶
Модуль управления пресетами серверов: получение списков, группировка, поиск подходящих серверов и детализация конфигураций с ценами в разных валютах.
| Ресурс | Действие | Описание |
|---|---|---|
groups | groups | Возвращает список групп пресетов |
info | info | Возвращает список пресетов для реселлеров с ценами в указанных валютах |
list | list | Возвращает список доступных пресетов с фильтрацией по локации и правам доступа |
search | search | Ищет подходящие серверы для конкретного пресета по имени |
show | show | Возвращает детальную информацию о пресете по ID или имени |
s3.php¶
Модуль управления S3-хранилищем: создание и удаление аккаунтов и бакетов, управление файлами, получение статистики использования и тарифных планов.
| Ресурс | Действие | Описание |
|---|---|---|
create_account | create_account | Создает новый бесплатный S3 аккаунт для клиента, включая создание бакета и учетных данных. |
create_bucket | create_bucket | Создает новый бакет в существующем S3 аккаунте. |
delete_account | delete_account | Полностью удаляет S3 аккаунт и все связанные с ним данные. |
delete_bucket | delete_bucket | Удаляет указанный бакет из S3 аккаунта. |
delete_file | delete_file | Удаляет указанный файл из бакета. |
get_available_locations | get_available_locations | Возвращает список доступных географических локаций для размещения S3 хранилищ. |
get_buckets_rmq | get_buckets_rmq | Возвращает список бакетов с информацией об использовании хранилища и трафика через RMQ. |
get_files | get_files | Возвращает список файлов и папок в указанном бакете с поддержкой пагинации и поиска. |
get_users | get_users | Возвращает список S3 аккаунтов пользователя или всех пользователей (для администратора) с информацией о трафике. |
list_plans | list_plans | Возвращает список доступных тарифных планов S3 с ценами в разных валютах. |
show_key | show_key | Возвращает расшифрованный ключ доступа (access_key или secret_key) для S3 аккаунта. |
software.php¶
Модуль управления программным обеспечением: предоставляет методы для получения списка доступного ПО с фильтрацией по характеристикам сервера или пресета, а также подбор совместимых пресетов и операцио
| Ресурс | Действие | Описание |
|---|---|---|
list | list | Возвращает список программного обеспечения, подходящего для конкретного сервера (id) или пресета (instance_id), с учетом лицензий, характеристик оборудования и промо-акций. |
stocks.php¶
Модуль управления серверами на складе: предоставление списков доступных серверов с фильтрацией по локациям и группам, а также детализированная информация о конкретном сервере.
| Ресурс | Действие | Описание |
|---|---|---|
list | list | Возвращает список доступных серверов на складе с возможностью фильтрации по локации и группе. |
show | show | Возвращает детальную информацию о конкретном сервере по его идентификатору. |
tags.php¶
Модуль управления метками (tags) для серверов и компонентов: добавление, удаление, очистка и поиск меток с поддержкой внутренних и публичных данных.
| Ресурс | Действие | Описание |
|---|---|---|
add | add | Добавляет пользовательскую метку к серверу или компоненту. Поддерживает добавление к списку ID через id_list. |
list | list | Возвращает список всех меток для указанного сервера или компонента. |
remove | remove | Удаляет метку по имени с указанного сервера или компонента. Поддерживает удаление по списку ID. |
traffic_plans.php¶
Модуль управления тарифными планами трафика: создание, удаление, обновление и получение списка доступных планов с фильтрацией по серверу или локации и конвертацией цен.
| Ресурс | Действие | Описание |
|---|---|---|
list | list | Возвращает список подходящих тарифных планов трафика для указанного сервера (id) или локации (location). Поддерживает фильтрацию по типу оборудования и конвертацию цен в EUR/USD/RUB. |
vm.php¶
Модуль управления виртуальными машинами (VM): создание и управление снапшотами, получение статистики, восстановление состояний.
| Ресурс | Действие | Описание |
|---|---|---|
create_snapshot | create_snapshot | Инициирует создание снапшота для указанной виртуальной машины. |
get_snapshot | get_snapshot | Запрашивает список существующих снапшотов для виртуальной машины. |
load_stats | load_stats | Запрашивает текущую статистику использования ресурсов виртуальной машины. |
remove_snapshot | remove_snapshot | Инициирует удаление указанного снапшота. |
restore_snapshot | restore_snapshot | Инициирует восстановление состояния виртуальной машины из снапшота. |
whmcs.php¶
Модуль интеграции с WHMCS для управления клиентами, счетами, кредитом, отменами заказов и биллинговыми данными серверов.
| Ресурс | Действие | Описание |
|---|---|---|
add_contact | add_contact | Добавляет новый контакт к существующему клиенту в биллинге. |
apply_credit | apply_credit | Применяет кредит с баланса клиента к оплате указанного счета. |
create_addfunds | create_addfunds | Создает счет для пополнения баланса (Add Funds). |
delete_cancellation_request | delete_cancellation_request | Удаляет активный запрос на отмену сервера и восстанавливает счет. |
delete_contact | delete_contact | Удаляет контакт из аккаунта клиента. |
download_invoice | download_invoice | Генерирует и возвращает PDF файл счета. |
generate_due_invoice | generate_due_invoice | Генерирует следующий счет для оплаты сервера. |
get_billing_data | get_billing_data | Получает синхронизированные данные биллинга для сервера. |
get_cancellation_requests | get_cancellation_requests | Возвращает список активных запросов на отмену серверов. |
get_client | get_client | Возвращает информацию об авторизованном клиенте или по ID. |
get_clientgroups | get_clientgroups | Возвращает список групп клиентов в биллинге. |
get_contacts | get_contacts | Возвращает список дополнительных контактов клиента. |
get_invoice | get_invoice | Возвращает данные конкретного счета. |
get_invoices | get_invoices | Возвращает список счетов клиента. |
get_related_invoices | get_related_invoices | Возвращает счета, связанные с сервером или аккаунтом. |
getcredits | getcredits | Возвращает историю кредитов клиента. |
getpaymentgw | getpaymentgw | Возвращает доступные методы оплаты для счета. |
mass_pay | mass_pay | Оплачивает несколько счетов одним платежом. |
request_cancellation | request_cancellation | Инициирует процесс отмены сервера с расчетом возврата средств. |
reset_password | reset_password | Инициирует сброс пароля или устанавливает новый с 2FA. |
transactions | transactions | Возвращает историю транзакций клиента. |
update_client | update_client | Обновляет данные профиля клиента в биллинге. |
update_contact | update_contact | Обновляет данные контакта клиента. |