Продавайте хостинг Zinn® через WHMCS

Модуль Zinn Digital® превращает стандартные кнопки WHMCS в реальные действия на нашей платформе. Заказ подготавливает хостинг для вашего клиента. Автоматизация просроченных счетов WHMCS приостанавливает его действие. Отметка счета как оплаченного возобновляет его. Отмена планирует удаление. А ваш клиент получает в своем личном кабинете кнопку Log in to hosting panel, которая сразу выполняет вход в систему.

Он бесплатный, распространяется под лицензией GPL-2.0-or-later и не имеет привилегированного доступа к нашей платформе: каждый выполняемый им вызов — это документированная конечная точка, к которой вы могли бы обратиться сами со своим собственным API-ключом.

Перед началом работы

Вам понадобятся две вещи, и со второй часто возникают сложности.

1. Реселлерский аккаунт Zinn® с активной программой. Зарегистрируйтесь на

zinndigital.com и включите реселлинг.

2. Реселлерский тариф с доступным лимитом сайтов. Заказываемые вашими клиентами сайты расходуют лимит вашего

тарифа, поэтому вам нужен тариф со свободным местом.

⚠️ Функция «Test Connection» не может подсказать, будет ли заказ успешным. Она считывает данные вашей программы и ничего не подготавливает, поэтому сообщает об исправном аккаунте со статусом active, который пока ничего не может продавать. Если ваш первый заказ завершается ошибкой «This organization has no hosting plan, so it cannot host a site yet», дело именно в этом — приобретите или расширьте ваш реселлерский тариф и оформите заказ заново. С модулем все в порядке.

1. Создайте API-ключ

В панели управления Zinn® откройте раздел API keys и создайте ключ ровно с этими одиннадцатью разрешениями:

⛔ Не предоставляйте разрешение reseller.manage. Ключ, добавленный в биллинг-панель, должен иметь возможность приостанавливать услуги клиента за неуплату и авторизовывать его. Он не должен иметь возможности читать и перезаписывать данные ваших собственных платежных шлюзов. Разрешение reseller.provision существует как раз для того, чтобы вам не приходилось выдавать более широкие права. ⛔ Разрешение org.create обязательно. Без него модуль может читать данные ваших аккаунтов, но не может открыть новый, поэтому Test Connection выполняется успешно, а при первом заказе возвращается ошибка 403. ⛔⛔ Предоставьте все права из таблицы и обратите внимание, что Test Connection не покажет их отсутствие. Функция считывает данные вашей реселлерской программы и ничего не подготавливает, поэтому проверка будет успешной даже для ключа, у которого отсутствует любое из этих разрешений. Вместо этого спустя месяцы вы получите от клиента ошибку 403 именно на той операции, за которую отвечало отсутствующее разрешение.

2. Установите модуль

1. Скачайте модуль и распакуйте архив.
2. Загрузите каталог zinn в установленный у вас WHMCS, чтобы файл модуля располагался по пути

modules/servers/zinn/zinn.php.

⛔ Каталог обязательно должен называться zinn. WHMCS формирует имена функций модуля подготовки на основе имени его каталога, поэтому его переименование в zinn-whmcs или zinndigital приведет к тому, что модуль будет отображаться в списке WHMCS, позволит себя выбрать, а затем ни разу не будет вызван — без вывода каких-либо ошибок. Архив уже распаковывается с правильным именем; просто не переименовывайте его.

3. Добавьте сервер

В WHMCS перейдите: Configuration → System Settings → Servers → Add New Server.

• Name: любое, например Zinn Digital®
• Hostname: api.zinndigital.com
• Type: Zinn Digital®
• Password: ваш API-ключ из шага 1

⛔ Ключ указывается в поле Password, которое WHMCS сохраняет в зашифрованном виде. Не указывайте его в настраиваемых параметрах продукта — они сохраняются в базе данных в открытом виде и доступны каждому администратору, тогда как эти учетные данные позволяют создавать и удалять хостинг ваших клиентов.

Нажмите Test Connection. При этом выполняется реальный запрос и выводятся данные от нашей платформы, а не просто проверяется заполнение полей.

4. Создайте продукт

Перейдите в раздел Configuration → System Settings → Products/Services, затем в блоке Module Settings выберите сервер, который вы только что добавили. Поля для заполнения:

⛔⛔ Поле «Plan code» обязательно, и заказ без него намеренно отклоняется. До 2026-09-01 это поле являлось декоративным и нигде не считывалось, поэтому модуль заказывал хостинг, к которому не был привязан никакой тариф, — и все последствия этого оставались незамеченными. Ваша оптовая ведомость формируется на основе активных подписок ваших клиентов, поэтому в ней отсутствовала строка с этой услугой, и вам ничего не выставлялось к оплате на протяжении всего времени ее работы; ваш клиент не получал лимитов, поэтому к его сайту не применялись квоты на диск или количество файлов; а действию Change Package нечего было изменять, из-за чего проданный апгрейд не мог быть выполнен. При этом сайт продолжал успешно создаваться и работать все это время.

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

Задайте параметр Auto Setup по вашему усмотрению — модуль идемпотентен по идентификатору услуги WHMCS, поэтому повторная попытка подготовки вернет тот же сайт, а не выставит вам счет за второй.

Что выполняет каждое действие в WHMCS

Смена тарифа: кто и кому выставляет счета

Zinn® никогда не выставляет счета вашему клиенту — ни при заказе, ни при смене тарифа. вы выставляете счет клиенту через WHMCS; мы выставляем счет вам в вашей оптовой ведомости. Таким образом, действие Change Package меняет доступные вашему клиенту ресурсы и строку в вашей следующей ведомости, никак не затрагивая банковские карты: WHMCS уже принял оплату у вашего клиента и самостоятельно выполнил перерасчет стоимости.

Вторая услуга клиента. На том же тарифе она представляет собой еще один сайт в рамках выделенного лимита сайтов этого тарифа, и никаких дополнительных ресурсов не выделяется. На другом тарифе запрос отклоняется: замена активного тарифа привела бы к тому, что за одну из двух услуг перестали бы выставляться счета. Либо продавайте обе услуги на одном и том же тарифе, либо создайте для клиента отдельную учетную запись в WHMCS.

Действие Change Password доступно только для WordPress. В хостинге Zinn® нет единого «пароля услуги» — ваш клиент попадает в панель управления с помощью кнопки входа, — а на сайте с окружением php или static нет учетной записи приложения, пароль которой можно было бы сменить. WHMCS полностью скрывает это поле, вместо того чтобы показывать элемент, который не может функционировать.

Три варианта ответа, которые нельзя сводить к двум

• Unsuspend может ответить отказом. Это означает, что сайт был заблокирован нашей службой безопасности,

а не вами, и ни одна биллинг-панель не может его разблокировать. Об этом прямо говорится в сообщении; покажите его своему администратору вместо повторных попыток.

• Terminate лишь планирует удаление, а не выполняет его мгновенно. Дата возвращается в поле

pending_deletion_at и отображается в личном кабинете. Сказать клиенту, что его данные уже удалены, когда это не так, хуже, чем ничего ему не говорить.

• Объем диска и трафика могут иметь статус неизвестных, и статус «неизвестно» — это не ноль. Если нам не удалось получить

показатели, модуль оставляет значение нетронутым вместо записи 0 — иначе WHMCS показал бы клиенту ложно успокаивающий пустой индикатор использования для сайта, данные по которому у нас отсутствуют.

Устранение неполадок

Test Connection завершается успешно, а первый заказ завершается ошибкой прав доступа. В API-ключе отсутствует разрешение org.create. Модуль должен открыть аккаунт клиента, прежде чем сможет создать для него сайт.

Заказ завершается с сообщением, что у организации нет тарифного плана. В вашем реселлерском тарифе закончился лимит сайтов или он еще не приобретен. См. раздел Перед началом работы выше.

Заказ завершается с упоминанием окружения (stack). Поле Stack в настройках продукта не заполнено либо содержит значение, которое мы не развертываем. Укажите wordpress, если только вы не продаете другое окружение.

Операции отмены завершаются ошибкой. Убедитесь, что вы используете модуль версии 1.0.0 или новее. Более ранние сборки не отправляли подтверждение удаления, поэтому каждая операция отмены отклонялась, а услуга продолжала работать и тарифицироваться.

Отказ с указанием конкретного поля. Наши ошибки валидации содержат имя поля и причину в скобках после сообщения, например: (php_version: 7.2 is not offered on this product line). Это именно та часть, которая требует исправления — предложение перед ней намеренно имеет общий характер.

Проверка целостности загруженного файла

Все архивы передаются по протоколу TLS с нашего собственного домена и никогда не перенаправляются на сторонние узлы. Контрольная сумма SHA-256 указана рядом со ссылкой на скачивание на странице загрузок. Сверьте ее после скачивания:

• macOS или Linux: shasum -a 256 zinn-whmcs-1.0.0.zip
• Windows: certutil -hashfile zinn-whmcs-1.0.0.zip SHA256

Используете другую систему вместо WHMCS?

Для других решений доступны модуль для HostBill и однофайловый PHP-клиент — оба бесплатные и размещены на той же странице загрузок. Все конечные точки, используемые модулями, описаны в документации по API.