Установка и настройка WHMCS для работы с биллингом HOSTKEY¶

В этой статье

Необходимое ПО

Подключение модуля

Активация модуля в WHMCS

Загрузка и удаление информации от HOSTKEY с помощью вызова консольных команд

Настройка курса валют

Настройка конкретных продуктов для перепродажи

Редактирование конкретного продукта

Активация оплаты заказанных продуктов

Примеры и подсказки

Типовые ошибки и решения

Необходимое ПО¶

модуль реселлера для WHMCS: скачать;
WHMCS версия 8.8 и выше.

Подключение модуля¶

Скачайте и распакуйте архив модуля в корень WHMCS

Распакуйте содержимое архива в корень вашей биллинговой системы.

Корень WHMCS — это директория, где находятся файлы configuration.php, папки vendor/, modules/, includes/.

Через SSH:
```
cd /path/to/your/whmcs
```
```
unzip /path/to/HostkeyResellerMod.zip
```
Через FTP: загрузите содержимое архива в корень WHMCS, согласившись на объединение папок.
Проверьте структуру после распаковки

Должны появиться:
- modules/addons/hostkeyresellermod/
- modules/servers/hostkeyresellermod/
- modules/gateways/callback/hostkeyresellermod.php
- includes/hooks/hostkeyresellermod.php
Ключевые файлы:
- modules/addons/hostkeyresellermod/hostkeyresellermod.php
- modules/addons/hostkeyresellermod/cron.php
- modules/addons/hostkeyresellermod/clean.php
- modules/addons/hostkeyresellermod/import.ini (опционально)
Обновите сессию админ-панели

Выйдите и снова войдите в админку WHMCS. При необходимости очистите кеш браузера.

Частые проблемы при копировании¶

Файлы в неправильной папке: модуль не появится в списке, если оказался в подпапке, а не в корне WHMCS.
Права/владелец: некорректные права мешают активации/отображению.
Кеш браузера/сессия: перелогин решает проблему "модуль не виден".

Активация модуля в WHMCS¶

Откройте список аддон-модулей
- Путь: System Settings → Apps & Integrations → Addon Modules.
- Найдите "HOSTKEY VPS/Dedicated".
Активируйте модуль и перейдите в настройки
- Нажмите ~~Activate~~.
- Затем Configure (или Settings), чтобы открыть форму параметров.
Заполните настройки модуля и сохраните

Поля:
- API Url — адрес API биллинга HOSTKEY:
- Международный: https://invapi.hostkey.com/ (по умолчанию).
- RU-биллинг: https://invapi.hostkey.ru/.
- API key — ключ доступа к API HOSTKEY. Получаем по данной инструкции. Храните в секрете.
- Preset name prefix — префикс имен (по умолчанию HKP-), чтобы визуально отличать товары HOSTKEY в списках WHMCS.
- Default product group — группа продуктов WHMCS для создаваемых товаров (по умолчанию Hostkey servers).
- Logging of requests to Hostkey API — при необходимости включите для отладки.
Нажмите ~~Save Changes~~.
Настройте доступ (Access Control)

Отметьте группы администраторов, которым нужен доступ к модулю (рекомендуем включить "Administrators").

Внимание

Если не отметить ни одной группы в разделе Access Control, модуль не будет отображаться в меню Addons, в том числе и для администратора.

Если все сделано правильно (в том числе установлены права), то в меню Addons появится раздел HOSTKEY VPS/Dedicated.
Откройте модуль и настройте импорт продуктов

Перейдите в раздел Addons → HOSTKEY VPS/Dedicated и выберите продукты для реселлинга:
- Import VPS products — для VPS/VDS;
- Import Bare metal products — для выделенных серверов;
- Import GPU products — для GPU-серверов.
Для каждой отмеченной категории задайте наценку и формат:
- В процентах: введите значение и оставьте "%" (пример: "10 %").
- В фиксированной валюте: введите значение и выберите валюту WHMCS (пример: "5 USD").
Выберите режим округления в Round price to: - Not round — без округления. - 0.1, 0.2, etc — до десятых. - 0.25, 0.5, 0.75 — до четвертей. - 0.5, 1.0 — до половин. - 1.0 — до целых.

Затем нажмите на кнопку ~~ImportProduct/AdjustPrice~~.

Примечание

При первом запуске рекомендуем воспользоваться другим способом, поскольку при загрузке большого количества информации страница может завершиться с кодом 504.
Успешная загрузка и что делать дальше

При верном подключении и активации модуля появится сообщение об успешной загрузке продуктов HOSTKEY и предложение перейти к настройке конкретных продуктов в меню System Settings → Product/Services.

Перейдите в Product/Services:
- Проверьте созданные группы и товары.
- По необходимости откройте товар, на вкладке Pricing выставьте цены/периоды; на вкладке Details снимите Hidden, чтобы товар отображался на витрине.
Примечание

При большом объеме информации страница может завершиться с кодом 504 Gateway Timeout. Для первоначальной загрузки списка продуктов рекомендуем воспользоваться загрузкой из консоли.

Загрузка и удаление информации от HOSTKEY с помощью вызова консольных команд¶

Вызов cron.php¶

Служит для загрузки информации от Hostkey. Вызов нужно выполнить из корня сайта:

php modules/addons/hostkeyresellermod/cron.php

Вызов clean.php¶

Удаляет информацию, полученную ранее от HOSTKEY. Вызов нужно выполнить из корня сайта:

php modules/addons/hostkeyresellermod/clean.php

Примечание

При вызове удаляются все группы и пресеты, полученные от HOSTKEY, а также их цены.

Важно: приоритет import.ini над настройками админ панели¶

Если в modules/addons/hostkeyresellermod/ существует файл import.ini, импорт будет ориентироваться на параметры из этого файла и перезапишет/проигнорирует настройки, заданные через админ-панель на странице Addons → HOSTKEY VPS/Dedicated.

Рекомендуем использовать import.ini, если импорт через веб-интерфейс работает нестабильно (зависания, 504) или когда вы запускаете импорт по крону/из консоли.

Если вы хотите настраивать импорт через админку, удалите или переименуйте import.ini:

rm modules/addons/hostkeyresellermod/import.ini

Параметры в import.ini¶

При работе вызов использует файл modules/addons/hostkeyresellermod/import.ini (если он есть).

Параметры в import.ini:

template = 5 — замените 5 на ID нужного email-шаблона из WHMCS (можно посмотреть в разделе Email Templates)
round = 0 — округление цен (0 = не округлять, 10 = до 0.1, 4 = до 0.25, 2 = до 0.5, 1 = до 1.0)
vps = 10 % — VPS наценка
bm = 50 USD — Bare metal наценка
gpu = 100 RUB — GPU наценка

Пример import.ini:

[general]
round = 0
template = 5
[markup]
vps = 10 %
bm = 50 USD
gpu = 100 RUB

Файл имеет две секции:

В секции general существует параметр round, отвечающий за округление. Возможные значения параметра:
0 — без округления;
10 — округление до десятых;
4 — округление до четвертей;
2 — округление до половин;
1 — округление до целого.
Секция markup содержит наценку в процентах для каждой группы.

Если файла import.ini нет или используется вариант по «умолчанию», то наценка и округление не производится.

Автоматическое обновление пресетов (cron)¶

Рекомендуем настроить расписание на 1 раз в сутки, в непиковое время.

Пример crontab (каждый день в 03:30; замените пути на свои):

30 3 * * * /usr/bin/php /path/to/whmcs/modules/addons/hostkeyresellermod/cron.php >/dev/null 2>&1

Подсказки по расписанию: см. кратко о cron, помощник — crontab.guru.

Настройка курса валют¶

Для правильного экспорта цен продуктов вам необходимо настроить курсы валют по отношению к EUR или USD и между ними. Это можно сделать в разделе Payments >> Currencies.

Настройка конкретных продуктов для перепродажи¶

Перейдя в меню System Settings >> Product/Services вы увидите таблицу всех доступных вам для перепродажи продуктов

Нажав на значки в крайних правых колонках вы можете изменить параметры продукта или удалить его из списка. Большая часть настроек определяется настройками WHMCS и мы остановимся только на критичных для перепродажи.

Редактирование конкретного продукта¶

Нажав на значок Edit вы попадаете в раздел изменения параметров Edit Product.

Вкладка Detail¶

На этой вкладке вы можете поменять Product Name продукта, который будет отображаться на вашей витрине.

Также выбрав чекбокс Hidden вы можете скрыть продукт из формы заказа не удаляя его.

Вкладка Price¶

На этой вкладке вы можете установить свою цену продукта в доступных вам валютах.

Вам доступна установка трех видов типа платежей (Payment Type):

Free - продукт распространяется бесплатно;
One Time - единовременный платеж за месяц использования;
Recurring - возобновляемый платеж за период.

Цена устанавливается вами для каждого периода и валюты отдельно, позволяя вам гибко регулировать политику ценообразования:

One Time/Monthly - единоразовый платеж или рекуррентный помесячно.
Quarterly - платеж раз в квартал (3 месяца)
Semi-Annually - платеж раз в полгода (6 месяцев)
Annually - платеж за год (12 месяцев)

Вам доступны две отдельные цены:

Setup Fee - цена за установку продукта;
Price - цена продажи продукта.

Внимание

Ваша цена должна быть больше показываемой в полях Price, так как иначе вы будете продавать продукт "в минус".

Изменив параметры и цену нажимаем кнопку ~~Save Changes~~ и сохраняем настройки для данного продукта.

После подтверждения успешного сохранения настроек, нажимаем и кнопку в правом верхнем углу ~~Back to Product list~~ для возврата к таблице продуктов.

После настройки продукты появляются на клиентской витрине.

Активация оплаты заказанных продуктов¶

Все заказанные продукты будут оплачиваться с баланса вашего аккаунта HOSTKEY. Для этого он должен иметь и у на нем должен быть включен режим автоматической оплаты с баланса.

Примеры и подсказки¶

Пример наценки и округления: цена 123.56 при наценке 10% и округлении до 0.5 → 136.0;
Валюты: проверьте Payments → Currencies — должны быть настроены курсы к EUR/USD и между используемыми валютами.

Типовые ошибки и решения¶

Invalid API key / 403: проверьте корректность API key, URL (.com vs .ru), отсутствие лишних пробелов;
Модуль не виден в Addons: отметьте группы в Access Control, обновите сессию, проверьте права файлов/владельца;
504 Gateway Timeout при импорте: используйте консольный импорт, увеличьте max_execution_time;
Цены кажутся "минусовыми": выставьте свою цену в Pricing выше закупочной; проверьте наценку и округление;
Ошибка 503: для выяснения попробуйте обратиться к журналу ошибок сервера error.log или php_error.log.