ip.php¶

Модуль управления IP-адресами: получение информации о клиенте, трафике, PTR-записях и управление основными адресами

Методы API¶

Метод	Действие	Описание
`change_ip`	смена IP-адреса	Выполняет процедуру смены текущего IPv4 адреса сервера на новый. Поддерживает предварительный просмотр доступного IP, проверку ограничений для клиентов и автоматическую блокировку старого IP в списках (RKND).
`get_client_ip`	получение клиентского IP	Возвращает текущий IP-адрес клиента, совершившего запрос.
`get_ip`	получение информации об IP	Возвращает полные данные о сетевом адресе, включая маску подсети и информацию о сети.
`get_ptr`	получение PTR-записи	Возвращает текущую обратную DNS-запись (PTR) для указанного IP-адреса.
`get_traffic`	получение трафика	Возвращает данные о входящем и исходящем трафике для IP за указанный период.
`list_free_ip`	получение свободных IP	Возвращает список неиспользуемых IP-адресов для конкретной локации на основе тегов RR.
`set_main`	установка основного IP	Устанавливает выбранный IP-адрес как основной для сетевого интерфейса сервера.
`update_ptr`	обновление PTR-записи	Устанавливает новую обратную DNS-запись (PTR) для IP-адреса.
`update_ptr`	обновление PTR-записи	Обновляет обратную DNS-запись (PTR) для указанного IP.

ip/change_ip¶

Выполняет процедуру смены текущего IPv4 адреса сервера на новый. Поддерживает предварительный просмотр доступного IP, проверку ограничений для клиентов и автоматическую блокировку старого IP в списках (RKND).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `change_ip`
token	✅	string	Токен авторизации пользователя
ip	✅	string	Текущий IPv4 адрес сервера, который необходимо заменить
id	✅	integer	Идентификатор услуги (сервера)
new_ip	❌	string	Новый IPv4 адрес для назначения. Если не указан, система подберет свободный IP в текущей локации.
block_subnet	❌	boolean	Флаг блокировки всей подсети старого IP-адреса в списках RKND
add_to_blacklist	❌	boolean	Флаг принудительной добавления старого IP в черный список (для администраторов)

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=change_ip" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=1.2.3.4" \
--data "id=123" \
--data "new_ip=5.6.7.8" \
--data "block_subnet=true" \
--data "add_to_blacklist=false"

Пример успешного ответа

{
"result": "OK",
"module": "ip",
"action": "change_ip",
"data": {
"old_ip": "1.2.3.4",
"new_ip": "5.6.7.8",
"reason": "Customer request",
"blocked": true,
"note": "Standard change procedure"
}
}

Примеры ошибок

{
"code": -1,
"message": "change_ip: ip and id are required"
}

ip/get_client_ip¶

Возвращает текущий IP-адрес клиента, совершившего запрос.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_client_ip`
token	✅	string	Токен авторизации.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=get_client_ip" \
--data "token=HOSTKEY_TOKEN"

Пример успешного ответа

{
"result": "OK",
"data": {
"ip": "192.168.1.1"
}
}

Примеры ошибок

{
"code": -1,
"message": "authentication required"
}

ip/get_ptr¶

Возвращает текущую обратную DNS-запись (PTR) для указанного IP-адреса.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_ptr`
token	✅	string	Токен авторизации.
id	✅	integer	Идентификатор сервера для проверки прав доступа и получения списка IP.
ip	✅	string	IP-адрес, для которого необходимо получить PTR-запись.
location	❌	string	Местоположение или зона для получения PTR-записи IP-адреса.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=get_ptr" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE"

Пример успешного ответа

{
"result": "OK",
"message": "example.domain.com"
}

Примеры ошибок

{
"code": -1,
"message": "module/get_ptr: invalid IP"
}

ip/update_ptr¶

Устанавливает новую обратную DNS-запись (PTR) для IP-адреса.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `update_ptr`
token	✅	string	Токен авторизации.
id	✅	integer	Идентификатор сервера для проверки прав доступа и получения списка IP-адресов.
ip	✅	string	IP-адрес, для которого устанавливается PTR-запись.
ptr	✅	string	Новое значение обратной DNS-записи (PTR).
location	✅	string	Местоположение или контекст для записи в лог истории.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=update_ptr" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE" \
--data "ptr=VALUE" \
--data "location=VALUE"

Пример успешного ответа

{
"result": "OK",
"message": ""
}

Примеры ошибок

{
"code": -1,
"message": "PTR set error message"
}

ip/get_traffic¶

Возвращает данные о входящем и исходящем трафике для IP за указанный период.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_traffic`
token	✅	string	Токен авторизации.
ip	✅	string	IP-адрес для получения данных о трафике.
period_start	❌	integer	Начальная временная метка (timestamp) периода.
period_stop	❌	integer	Конечная временная метка (timestamp) периода.
summary	❌	integer	Режим возврата данных: 1 — вернуть только сводку {ip, in, out} в GB, 0 — вернуть все тики с метками времени для графиков.
unbilled	❌	integer	Фильтр по оплаченному трафику: 1 — вернуть только неоплаченные тики, 0 — все тики.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=get_traffic" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=1.2.3.4"

Пример успешного ответа

{
"result": "OK",
"traffic": [
{
"timestamp": "2024-05-20T12:00:00Z",
"in": 0.5,
"out": 1.2
}
]
}

Примеры ошибок

{
"code": -1,
"message": "no significant traffic detected for IP in the period..."
}

ip/list_free_ip¶

Возвращает список неиспользуемых IP-адресов для конкретной локации на основе тегов RR.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `list_free_ip`
token	✅	string	Токен авторизации.
exclude_special	❌	integer	Исключать специальные IP. Допустимые значения: 0, 1.
full	❌	boolean	Флаг для возврата полного набора данных в ответе.
location	❌	string	Идентификатор или название локации для поиска свободных IP-адресов.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=list_free_ip" \
--data "token=HOSTKEY_TOKEN" \
--data "location=London" \
--data "exclude_special=1"

Пример успешного ответа

{
"result": "OK",
"ip": [
"192.168.1.10",
"192.168.1.11"
]
}

Примеры ошибок

{
"code": -1,
"message": "invalid IP subnet"
}

ip/set_main¶

Устанавливает выбранный IP-адрес как основной для сетевого интерфейса сервера.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `set_main`
token	✅	string	Токен авторизации.
id	✅	integer	Идентификатор сервера для назначения основного IP-адреса.
ip	✅	string	IP-адрес, который необходимо установить как основной.
description	❌	string	Текстовое описание для назначения основного IP-адреса.
main	❌	string	Флаг или значение, определяющее статус основного адреса.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=set_main" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "ip=192.168.1.1"

Пример успешного ответа

{
"result": "OK",
"message": "Success message or data"
}

Примеры ошибок

{
"code": -1,
"message": "invalid IP for server id"
}

ip/update_ptr¶

Обновляет обратную DNS-запись (PTR) для указанного IP.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `update_ptr`
token	✅	string	Токен авторизации.
id	✅	integer	Идентификатор сервера для проверки прав доступа и получения списка IP.
ip	✅	string	IP-адрес, для которого необходимо обновить PTR-запись.
ptr	✅	string	Новое значение обратной DNS-записи (PTR).
location	✅	string	Местоположение или контекст для логирования операции.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=update_ptr" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE" \
--data "ptr=VALUE" \
--data "location=VALUE"

Пример успешного ответа

{
"result": "OK",
"message": ""
}

Примеры ошибок

{
"code": -1,
"message": "Error message from pdns_update_ptr"
}

ip/get_ip¶

Возвращает полные данные о сетевом адресе, включая маску подсети и информацию о сети.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get_ip`
ip	✅	string	Сетевой адрес (IPv4), для которого необходимо получить информацию о сети.
full	❌	boolean	Возможность получения полной информации о сетевых настройках IP-адреса.

Пример запроса

curl -s "https://invapi.hostkey.ru/ip.php" -X POST \
--data "action=get_ip" \
--data "ip=192.168.1.1"

Пример успешного ответа

{
"result": -1,
"message": "No data for the loopback address",
"data": {
"network": "192.168.1.0",
"netmask": "255.255.255.0",
"broadcast": "192.168.1.255",
"gateway": "192.168.1.1"
}
}

Примеры ошибок

{
"code": -1,
"message": "malformed IP=127.0.0.1"
}