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

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

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

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

Вам понадобятся две вещи, причем вторая часто вызывает затруднения.

1. Учетная запись реселлера Zinn® с активной программой. Зарегистрируйтесь на сайте zinndigital.com и включите реселлинг.
2. План реселлера с выделением сайтов. Сайты, заказываемые вашими клиентами, расходуют лимит вашего плана, поэтому вам нужен план со свободным местом.

⚠️ Тест подключения не может определить, будет ли заказ успешным. Он считывает вашу программу и ничего не подготавливает, поэтому сообщает о работоспособной учетной записи со статусом active, которая еще ничего не может продать. Если ваш первый заказ завершается ошибкой "У этой организации нет плана хостинга, поэтому она пока не может разместить сайт" (This organization has no hosting plan, so it cannot host a site yet), произошло именно это — приобретите или продлите свой план реселлера и повторите заказ. С модулем все в порядке.

1. Создание ключа API

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

| Разрешение | Для чего оно необходимо | | -------------------- | ----------------------------------------------------------- | | org.create | Создание учетной записи Zinn® вашего клиента при первом заказе. | | org.read | Чтение данных учетных записей ваших клиентов. | | sites.create | Подготовка сайта. | | sites.view | Чтение информации об услуге и ее использовании. | | sites.delete | Удаление. | | reseller.view | Просмотр списка проданного, а также объема диска и полосы пропускания. | | reseller.provision | Приостановка, возобновление, вход в систему от имени клиента, установка его плана и изменение пакета. | | billing.view | Расчет стоимости обновления перед его выполнением. | | sites.manage | Очистка кэша и создание резервной копии с помощью кнопок. | | sites.panel_access | Изменение пароля администратора WordPress. | | hosting.php.manage | Переключение версии PHP при повышении или понижении тарифа. |

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

2. Установка модуля

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

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

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) сервер, который вы только что добавили. Доступные поля:

| Поле | Обязательно | Что оно представляет | | ---------------- | ----------- | -------------------------------------------------------------------------- | | Линейка продуктов (Product line) | да | Линейка Zinn®, которую вы продаете: mainstream (управляемый WordPress), footprint_free, wordpress, linux, cloud, agency, app_hosting, ai_hosting, lms_hosting, managed_database, vector_hosting, zinn_compute, fleet_linux, fleet_enterprise, mail или reseller. | | Стек (Stack) | да | Что создается: wordpress (по умолчанию), woocommerce, php, static, node, one_click, headless_cms, nextcloud или owncloud. | | Приложение (Application) | нет | Только для стеков one_click и headless_cms — какое приложение установить. Указание приложения для любого другого стека отклоняется, поскольку этот стек уже определяет, что именно устанавливается. | | Версия PHP (PHP version) | нет | Например, 8.3. Оставьте пустым для использования версии линейки по умолчанию. Версия, не поддерживаемая линейкой, отклоняется с выводом списка доступных версий. | | Код плана (Plan code) | да | План Zinn®, который продает этот продукт. Команда GET /v1/reseller/prices выводит список доступных вам планов. Заказ без него отклоняется — см. предупреждение ниже. | | Интервал выставления счетов (Billing interval) | нет | monthly (по умолчанию) или annual — интервал, с которым выставляется счет для вашей оптовой линейки по этому клиенту. Сумма, взимаемая с вашего собственного клиента, настраивается в продукте WHMCS и остается неизменной. |

⛔⛔ Код плана является обязательным, и заказ без него намеренно отклоняется. До 2026-09-01 это поле было декоративным, и его никто не читал, поэтому модуль заказывал хостинг, к которому вообще не был привязан никакой план, и все последствия этого оставались незамеченными. Ваш оптовый отчет формируется на основе активных подписок ваших клиентов, поэтому для услуги не было строки в отчете, и вам ничего не выставлено к оплате за все время ее работы; ваш клиент не получал никаких квот, поэтому к его сайту не применялись ограничения на дисковое пространство или файлы; и функции изменения пакета нечего было менять, поэтому оформленное вами повышение тарифа не могло быть выполнено. Сайт при этом прекрасно работал и обслуживался.

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

Установите для параметра Автоматическая установка (Auto Setup) то значение, которое вы предпочитаете — модуль идеособен относительно идентификатора услуги WHMCS, поэтому повторная попытка подготовки возвращает тот же сайт, а не выставляет счет за второй.

Что делает каждое действие WHMCS

| Действие WHMCS | Что происходит на нашей стороне | | --------------------------- | ---------------------------------------------------------------------------------------- | | Создать (Create) | Создает учетную запись Zinn® клиента (или использует существующую) и подготавливает его сайт. | | Приостановить (Suspend) | Переводит сайт в режим блокировки из-за неоплаты. Содержимое сохраняется; ничего не удаляется. | | Возобновлить (Unsuspend) | Снимает вашу блокировку. | | Удалить (Terminate) | Планирует удаление сайта с предоставлением льготного периода. Дата отображается в клиентской зоне. | | Обновление использования (Usage update) | Обновляет данные об использовании диска и полосы пропускания для каждой услуги один раз в день. | | Войти в панель хостинга (Log in to hosting panel) | Открывает одноразовую ссылку для входа прямо в панель вашего клиента. | | Изменить пакет (Change Package) | Повышает или понижает уровень услуги. Переносит пакет, а также версию PHP, если в новом продукте она указана. | | Изменить пароль (Change Password) | Устанавливает пароль администратора WordPress. Это поле не отображается для стеков, у которых нет такой учетной записи. | | Продлить (Renew) | Подтверждает, что услуга все еще существует. Хостинг Zinn® является непрерывным, поэтому удаленный срок действия продлевать не нужно. | | Синхронизация использования / Очистка кэша / Создание резервной копии | Кнопки на странице услуги администратора. Ваш клиент получает функции «Очистка кэша» и «Создание резервной копии» в своей клиентской зоне. | | Вкладка «Услуга» (Service tab) | Статус, план, диск, полоса пропускания, информация о запланированном удалении и кто именно инициировал приостановку. | | Импорт (Import) | Функция ListAccounts считывает каждую страницу, поэтому импорт не может незаметно остановиться на первой же. |

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

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

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

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

Три ответа, которые нельзя объединять в один

• Действие «Возобновлить» может вернуть отказ. Это означает, что сайт был приостановлен нашей командой по борьбе со злоупотреблениями, а не вами, и ни одна биллинговая панель не может снять эту блокировку. Сообщение об этом прямо говорит; покажите его своему администратору, вместо того чтобы повторять попытку.
• Действие «Удалить» планирует удаление, но не выполняет его немедленно. Дата возвращается в виде pending_deletion_at, и она отображается в клиентской зоне. Сообщать клиенту, что его данные уже удалены, когда это не так, хуже, чем не говорить ничего.
• Данные об использовании диска и полосы пропускания могут быть неизвестны, а неизвестное не равно нулю. Если нам не удалось получить показания, модуль оставляет значение без изменений, а не записывает 0 — в противном случае WHMCS показала бы вашему клиенту обнадеживающую пустую полосу использования для сайта, по которому у нас нет данных.

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

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

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

Заказ завершается ошибкой, упоминающей стек. Поле Стек (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.