customers.php¶

В этой статье

Методы API

customers/bulk

customers/deploy_list

customers/deploy_load

customers/deploy_logs

customers/deploy_update

customers/fix_duplicates

customers/get

customers/list

customers/login

customers/orders

customers/remove

customers/reset

customers/reset_brute

customers/servers

customers/update

customers/update_acl

customers/set_order_status

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

Методы API¶

Метод	Действие	Описание
`bulk`	массовая операция над услугами клиента	Выполняет массовое изменение статуса услуг (активация, приостановка, удаление) для списка серверов.
`deploy_list`	получение списка деплоев	Возвращает список событий развертывания (деплоя) по фильтрам.
`deploy_load`	загрузка деплоев клиента	Вызывает функцию customers_deploy_load, которая добавляет теги развертывания (deploy tags) для сервера, связанного с клиентом.
`deploy_logs`	логи деплоев	Возвращает логи операций развертывания.
`deploy_update`	обновление деплоя	Обновляет данные о развертывании (комментарии, периоды и т.д.).
`fix_duplicates`	поиск дубликатов клиентов	Поиск и подготовка к удалению дублирующихся записей клиентов по email в рамках одного биллинга.
`get`	получение данных клиента, включая информацию о биллинге и теги	Возвращает детальную информацию о клиенте (данные из БД + WHMCS), включая расширенную группу биллинга.
`list`	получение списка клиентов	Возвращает список клиентов с примененными фильтрами.
`login`	авторизация клиента	Генерирует временный токен доступа для входа в интерфейс клиента.
`orders`	получение заказов	Возвращает список заказов, связанных с клиентом.
`remove`	удаление клиента	Удаляет запись о клиенте по его ID.
`reset`	сброс данных авторизации клиента	Сбрасывает данные авторизации клиента (сессии, токены и счетчик брутфорса).
`reset_brute`	сброс лимитов	Сбрасывает счетчик ограничений (rate limiter) для клиента.
`servers`	получение серверов клиента	Возвращает список серверов, привязанных к конкретному клиенту в указанной локации.
`set_order_status`	установка статуса заказа	Устанавливает статус заказа в системе WHMCS на основе ID клиента.
`update`	обновление данных клиента	Обновляет основные данные клиента, включая billing (WHMCS), email и другие параметры профиля. При изменении email обновляются настройки 2FA.
`update_acl`	обновление IP ACL	Добавляет или удаляет список разрешенных IP-адресов (ACL) для клиента.

customers/bulk¶

Выполняет массовое изменение статуса услуг (активация, приостановка, удаление) для списка серверов.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `bulk`
token	✅	string	Токен авторизации
params[action_type]	✅	string	Тип массовой операции. Допустимые значения: active, suspend, cancel
params[server_ids][]	✅	array	Параметр `server_ids`

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=bulk" \
--data "token=HOSTKEY_TOKEN" \
--data "params[action_type]=suspend" \
--data "params[server_ids][]=123" \
--data "params[server_ids][]=456"

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

{
"result": "OK",
"processed": 5,
"skipped": [
{
"id": 123,
"error": "Invalid: current status 'Active', required 'Suspended' to make Suspended"
}
],
"status_from": "Active",
"status_to": "Suspended"
}

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

{
"exceptions": [
{
"code": null,
"message": "customers/bulk: invalid customer id"
},
{
"code": null,
"message": "customers/bulk: no server IDs provided"
},
{
"code": null,
"message": "customers/bulk: invalid action_type '...'"
}
]
}

customers/deploy_list¶

Возвращает список событий развертывания (деплоя) по фильтрам.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `deploy_list`
token	✅	string	Токен авторизации
params[billing]	❌	string	Фильтр по биллингу.
params[period_from]	✅	string	Дата начала периода. Должна быть валидной датой.
params[period_to]	✅	string	Дата окончания периода. Должна быть валидной датой.
params[event]	❌	string	Тип события. Допустимые значения: whmcs_am, whmcs_itb, whmcs_ru.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=deploy_list" \
--data "token=HOSTKEY_TOKEN" \
--data "params[period_from]=2024-01-01" \
--data "params[period_to]=2024-12-31"

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

{
"result": "OK",
"module": "customers",
"action": "deploy_list",
"data": [
{
"id": 123,
"server_id": 456,
"companyname": "Company Inc",
"inn": "1234567890",
"email": "user@example.com",
"billing": "whmcs_ru",
"title": "Title",
"recc": "price_value",
"period": "P1M",
"deploy_date": "2024-01-01",
"comment": "Billing cycle change: old (old_price currency) → new (new_price currency)",
"order_id": "",
"contract_num": "CNT-123",
"is_event": true
}
]
}

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

{
"500": "Date field cannot be empty"
}

customers/deploy_load¶

Вызывает функцию customers_deploy_load, которая добавляет теги развертывания (deploy tags) для сервера, связанного с клиентом.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `deploy_load`
token	✅	string	Токен авторизации
id	✅	integer	ID клиента (извлекается из $_POST/$_GET)
params[load]	❌	integer	Флаг запуска процесса добавления тегов (если > 0). Если 0, процесс не выполняется. По умолчанию 1.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=deploy_load" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "params[load]=1"

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

{
"result": "OK",
"module": "customers",
"action": "deploy_load",
"data": null
}

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

{
"400": "Please provide ID (если id пустой)",
"404": "RuntimeException: Deploy log instance not found (если для клиента нет записей в deploy_log)",
"500": "RuntimeException: Deploy log instance not found (если для клиента нет записей в deploy_log)"
}

customers/deploy_logs¶

Возвращает логи операций развертывания.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `deploy_logs`
token	✅	string	Токен авторизации
params[billing]	❌	string	Фильтр по биллингу. Допустимые значения: whmcs_ru, whmcs_itb, whmcs_am
params[period_from]	❌	string	Дата начала периода.
params[period_to]	❌	string	Дата окончания периода.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=deploy_logs" \
--data "token=HOSTKEY_TOKEN" \
--data "params[billing]=whmcs_ru"

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

{
"result": "OK",
"module": "customers",
"action": "deploy_logs",
"data": [
{
"l.*": "all columns from deploy_log table",
"loaded": "boolean",
"c.corporate": "string/null"
}
]
}

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

{
"code": -2,
"message": "action is required / authorization is required"
}

customers/deploy_update¶

Обновляет данные о развертывании (комментарии, периоды и т.д.).

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `deploy_update`
token	✅	string	Токен авторизации
id	✅	integer	ID клиента (из $_args)
params[comment]	❌	string	Комментарий к обновлению.
params[inn]	❌	string	ИНН клиента.
params[companyname]	❌	string	Название компании.
params[email]	❌	string	Электронная почта клиента.
params[order_id]	❌	string	ID заказа.
params[period]	❌	string	Период обновления.
params[deploy_date]	❌	string	Дата развертывания.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=deploy_update" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "params[comment]=Updated info" \
--data "params[inn]=770123456789" \
--data "params[companyname]=My Company" \
--data "params[email]=test@example.com" \
--data "params[order_id]=ORD-123" \
--data "params[period]=2023-01-01 to 2024-01-01" \
--data "params[deploy_date]=2023-05-20"

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

{
"result": "OK",
"module": "customers",
"action": "deploy_update"
}

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

{
"400": {
"message": "Please provide ID"
},
"404": {
"message": "Unable to find tag `[id]`"
}
}

customers/fix_duplicates¶

Поиск и подготовка к удалению дублирующихся записей клиентов по email в рамках одного биллинга.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `fix_duplicates`
token	✅	string	Токен авторизации
limit	❌	integer	Лимит записей. По умолчанию 50.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=fix_duplicates" \
--data "token=HOSTKEY_TOKEN" \
--data "limit=50"

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

{
"result": "Customers found: [count]\nCustomers to remove: [count]\nMultiple billing accounts found, need manual check: [count]\n[emails]\n[sql_queries]"
}

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

{
"-2": "action is required / authorization is required",
"-1": "invalid token, logout",
"Exception": "location required, customers not found, Not available for the environment [env], multiple billing accounts found"
}

customers/get¶

Возвращает детальную информацию о клиенте (данные из БД + WHMCS), включая расширенную группу биллинга.

HTTP-метод: POST|GET

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `get`
token	✅	string	Токен авторизации
id	❌	integer	ID клиента (по умолчанию -1)

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

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

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

{
"result": "OK",
"customer": {
"id": 123,
"email": "user@example.com",
"billing": "WHMCS_LOC",
"billing_group": "Group Name - Group Label",
"account_id": 456,
"tags": []
}
}

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

{
"message": "customers/get: failed to get customer 123: error message"
}

customers/list¶

Возвращает список клиентов с примененными фильтрами.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `list`
token	✅	string	Токен авторизации
params[id]	❌	integer	ID клиента (передается через массив params)
params[billing]	❌	string	Локация/биллинг
params[email]	❌	string	Email клиента для поиска.
params[order]	❌	string	Порядок сортировки (например: id DESC).

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=list" \
--data "token=HOSTKEY_TOKEN" \
--data "params[id]=10" \
--data "params[email]=user@example.com"

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

{
"result": "OK",
"module": "customers",
"action": "list",
"list": [
{
"id": 10,
"email": "user@example.com",
"billing": "WHMCS",
"billing_group": "Standard - WHMCS",
"status": "active",
"tags": []
}
]
}

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

{
"code": 500,
"message": "customers/list: customer not found or never logged it: [error_from_customers_list]"
}

customers/login¶

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

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `login`
token	✅	string	Токен авторизации (администратора)
id	❌	integer	ID клиента для входа
res	❌	string	Результат выполнения запроса или контекст сессии

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

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

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

{
"result": "OK",
"module": "customers",
"action": "login",
"token": "string (hex)"
}

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

{
"errors": [
{
"code": -1,
"message": "customers/login: failed to get a token for customer 123: error message"
}
]
}

customers/orders¶

Возвращает список заказов, связанных с клиентом.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `orders`
token	✅	string	Токен авторизации
params[limit]	❌	integer	Количество записей на страницу. По умолчанию 10.
params[page]	❌	integer	Номер страницы. По умолчанию 1.
params[order]	❌	integer	ID заказа для фильтрации (по умолчанию 0).

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=orders" \
--data "token=HOSTKEY_TOKEN" \
--data "params[limit]=10" \
--data "params[page]=1" \
--data "params[order]=501"

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

{
"result": "OK",
"module": "customers",
"action": "orders",
"data": {
"invoices": [
{
"id": 501,
"amount": 49.99,
"currency": {
"EUR": 49.99,
"RUB": 4800
},
"status": "paid",
"date": "2024-01-15T10:30:00Z"
}
]
}
}

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

{
"code": -2,
"message": "customers: action is required"
}

customers/remove¶

Удаляет запись о клиенте по его ID.

HTTP-метод: POST

Параметры:

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

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

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

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

{
"result": "OK",
"module": "customers",
"message": "Customer record for user@example.com at billing removed",
"action": "remove",
"id": 123
}

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

{
"code": -1,
"message": "customers/remove: customer 123 not found: error_from_customer_get"
}

customers/reset¶

Сбрасывает данные авторизации клиента (сессии, токены и счетчик брутфорса).

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `reset`
token	✅	string	Токен авторизации
id	❌	integer	ID клиента (если не указан, берется из данных токена)

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

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

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

{
"result": "OK",
"action": "reset",
"id": 123
}

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

{
"errors": [
{
"code": -1,
"message": "customers/reset: invalid token, logout"
},
{
"code": -1,
"message": "customers/reset: failed to reset auth for the customer 123: customers_reset: invalid id key 123 provided"
},
{
"code": -1,
"message": "customers/reset: failed to reset auth for the customer 123: customers_reset: invalid customer id 123, not exists "
}
]
}

customers/reset_brute¶

Сбрасывает счетчик ограничений (rate limiter) для клиента.

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `reset_brute`
token	✅	string	Токен авторизации
id	❌	integer	ID клиента для сброса лимитов попыток входа (по умолчанию -1)

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

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

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

{
"result": "OK",
"module": "customers",
"action": "reset_brute",
"id": 123
}

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

{
"errors": [
{
"code": null,
"message": "customers/reset_brute: invalid request"
},
{
"code": null,
"message": "customers/reset_brute: failed to reset rate limiter for the customer 123: customers_reset_brute: invalid id key -1 provided"
},
{
"code": null,
"message": "customers/reset_brute: failed to reset rate limiter for the customer 123: customers_reset_brute: invalid customer id 123, not exists"
}
]
}

customers/servers¶

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

HTTP-метод: POST

Параметры:

action	✅	string	Идентификатор метода: `servers`
token	✅	string	Токен авторизации
params[customerEdit_billing]	✅	string	Параметр customerEdit_billing, используемый в формировании сообщения об ошибке

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=servers" \
--data "token=HOSTKEY_TOKEN" \
--data "params[customerEdit_billing]=VALUE"

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

{
"result": "OK",
"servers": [
{
"id": 50,
"type": "server_type",
"owner": "customer_email",
"status": "active",
"ip": "1.2.3.4",
"location": "NL",
"config": "hw_config",
"full_location": "Rack-Pos-ID",
"monthly": 50.0,
"next_duedate": "2023-10-10",
"preset": "preset_value",
"currency": "EUR",
"billing_status": "paid",
"reccuring": "true",
"billing_cycle": "monthly",
"deploy_date": "2023-01-01"
}
]
}

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

{
"502": "failed to list servers for customer $id; location customerEdit_billing: error message"
}

customers/update¶

Обновляет основные данные клиента, включая billing (WHMCS), email и другие параметры профиля. При изменении email обновляются настройки 2FA.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `update`
token	✅	string	Токен авторизации
id	❌	integer	ID клиента для обновления (по умолчанию -1)
params[billing]	✅	string	Локация/биллинг. Если изменена, проверяется наличие дубликатов в системе.
params[email]	✅	string	Email клиента. При изменении обновляются настройки двухфакторной аутентификации (2FA).
params[currency]	❌	string	Валюта клиента.
billng_update	❌	integer	Флаг синхронизации данных с WHMCS (1 — обновить email в WHMCS). По умолчанию 0.
params[customerEdit_billing]	✅	string	Параметр для формирования ошибки PlatformException при обновлении WHMCS

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=update" \
--data "token=HOSTKEY_TOKEN" \
--data "params[billing]=VALUE" \
--data "params[email]=VALUE" \
--data "params[customerEdit_billing]=VALUE"

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

{
"result": "OK",
"action": "update",
"id": 123
}

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

{
"code": -2,
"message": "$module: action is required"
}

customers/update_acl¶

Добавляет или удаляет список разрешенных IP-адресов (ACL) для клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `update_acl`
token	✅	string	Токен авторизации
id	✅	integer	ID клиента
ips	✅	string	Список IP-адресов через пробел. Если пусто, список ACL будет очищен.

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=update_acl" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ips=192.168.1.1 10.0.0.1"

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

{
"result": "OK"
}

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

{
"code": -1,
"message": "Invalid IP address in the access list"
}

customers/set_order_status¶

Устанавливает статус заказа в системе WHMCS на основе ID клиента.

HTTP-метод: POST

Параметры:

Параметр	Обязательный	Тип	Описание
action	✅	string	Идентификатор метода: `set_order_status`
token	✅	string	Токен авторизации
id	✅	integer	Идентификатор клиента
params[status]	✅	string	Статус заказа для установки.
location	❌	string	Локация (биллинг) клиента.
status	✅	string	Параметр `status`

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

curl -s "https://invapi.hostkey.ru/customers.php" -X POST \
--data "action=set_order_status" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "params[status]=VALUE" \
--data "status=VALUE"

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

{
"result": "OK",
"action": "set_order_status"
}

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

{
"code": -1,
"message": "Error message from WHMCS integration"
}