Установка

На этой странице устанавливаются обе половины Perfex CRM Integration for WHMCS. Выполняйте шаги по порядку. Весь процесс проходит в двух вкладках браузера плюс файловый менеджер вашей хостинг-панели. SSH и командная строка не требуются.

У вас должен быть распакованный upload.zip (themesic.com/marketplace/whmcs-perfex.zip), из которого получаются два файла:

Файл	Устанавливается в
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Быстрая установка (краткая версия)

Для опытного администратора хостинга вся работа сводится к пяти действиям. Выполните их в этом порядке.

1. 🧩 Сначала Perfex. В Perfex CRM перейдите в Setup > Modules > Upload Module, загрузите module.zip, затем нажмите Activate. Установка стороны Perfex первой означает, что принимающая точка входа существует ещё до того, как WHMCS что-либо отправит.
2. ⚙️ Аддон для WHMCS. Загрузите и распакуйте addon.zip в modules/addons/, чтобы в итоге получить modules/addons/perfexbridge/perfexbridge.php, затем активируйте Perfex CRM Bridge в разделе System Settings > Addon Modules.
3. 🔓 Отметьте Access Control. На экране Configure аддона отметьте Full Administrator (плюс любую другую роль, которой он нужен) и нажмите Save Changes. Без этого модуль невидим - он вообще не появляется в меню Addons.
4. 🔗 Свяжите обе стороны. Откройте Addons > Perfex CRM Bridge, вставьте Connection code, скопированный из Perfex, в блок Quick setup и нажмите Connect. Подробности в разделе Настройка.
5. ✅ Проверьте. Создайте тестового клиента в WHMCS, нажмите Run Sync Now и убедитесь, что он появился в Perfex в разделе Customers.

Каждый клик, каждая строка контрольного списка и полная сквозная проверка описаны в Подробном руководстве ниже.

Подробное руководство

Порядок имеет значение

Сначала установите компаньон для Perfex. Он создаёт принимающую точку входа. Если сначала установить аддон для WHMCS и запустить синхронизацию, каждое событие будет завершаться ошибкой, пока не появится сторона Perfex, и вы потратите время на чтение журналов ошибок о проблеме, которую сами же ещё не создали.

Шаг 1: установка компаньона для Perfex CRM

Компаньон для Perfex бесплатен, не требует лицензионного ключа и устанавливается полностью из админки Perfex.

1. Войдите в Perfex CRM как Administrator.
2. Перейдите в Setup > Modules.
3. Нажмите кнопку Upload Module.
4. Выберите module.zip в диалоге выбора файла и загрузите его.
5. Perfex покажет модуль в списке как WHMCS Bridge. Нажмите Install, если появится запрос, затем нажмите Activate.

Если загрузка отклонена из-за размера

Кнопка Upload Module передаёт архив через PHP, поэтому серверные ограничения upload_max_filesize и post_max_size должны быть больше размера файла. Если загрузка не проходит, либо увеличьте эти ограничения в конфигурации PHP, либо воспользуйтесь ручным способом ниже.

Ручной способ: распакуйте module.zip на своём компьютере и загрузите полученную папку whmcs_bridge в каталог modules/ вашей установки Perfex по FTP или через файловый менеджер хостинг-панели. В результате должен получиться путь modules/whmcs_bridge/whmcs_bridge.php. Затем вернитесь в Setup > Modules и нажмите Activate.

Проверка того, что сторона Perfex установлена правильно

• В меню Setup в Perfex появляется новый пункт WHMCS Bridge. На этой странице в следующей главе вы сгенерируете общий секрет.

Шаг 2: установка аддона для WHMCS

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

1. Откройте Файловый менеджер вашей хостинг-панели и перейдите в каталог modules/addons/ вашей установки WHMCS.
2. Загрузите addon.zip в modules/addons/.
3. Примените к загруженному файлу действие Extract в файловом менеджере, распаковав его в тот же каталог modules/addons/.
4. Убедитесь, что в результате получился путь modules/addons/perfexbridge/perfexbridge.php. Если получилось modules/addons/perfexbridge/perfexbridge/perfexbridge.php, распаковка создала лишний уровень вложенности. Переместите внутреннюю папку на уровень выше и удалите пустую обёртку.
5. После успешной распаковки удалите загруженный addon.zip с сервера.

Альтернатива через FTP

Сначала распакуйте addon.zip на своём компьютере, затем загрузите полученную папку perfexbridge в modules/addons/ по FTP. Итоговое состояние будет тем же.

Теперь активируйте модуль:

6. В WHMCS перейдите в System Settings > Addon Modules.
7. Найдите в списке Perfex CRM Bridge и нажмите Activate.

Шаг 3: отметьте роли в Access Control, иначе модуль останется невидимым

Это самая частая жалоба вида "модуль не установился"

После активации WHMCS показывает панель конфигурации модуля с разделом Access Control, где перечислены роли администраторов. Необходимо отметить как минимум Full Administrator, а также любые другие роли, которым нужен доступ к модулю, и нажать Save Changes.

Пока не отмечена ни одна роль, модуль вообще не появляется в меню Addons слева. Модуль установлен, его таблицы созданы, а страница настроек работает безупречно, но ссылки на него нигде в админке нет. В девяти случаях из десяти "модуль не установился" означает, что эта галочка так и не была поставлена.

Конкретно:

1. Оставаясь в System Settings > Addon Modules, нажмите Configure рядом с Perfex CRM Bridge. Обычно WHMCS открывает эту панель автоматически сразу после активации.
2. В разделе Access Control отметьте Full Administrator. Отметьте также любую другую роль администратора, которая должна открывать и настраивать мост.
3. Нажмите Save Changes.
4. Обновите админку. Perfex CRM Bridge теперь появится в меню Addons.

Access Control - единственное, что есть на экране Configure

Все реальные настройки модуля находятся на его собственной странице по адресу Addons > Perfex CRM Bridge, а не на экране Configure в WHMCS. На экране Configure остаётся только Access Control, потому что этот раздел отрисовывается ядром WHMCS и его нельзя перенести. Если вы открыли Configure в поисках адреса Perfex или лицензионного ключа, вы не на том экране. См. Настройка.

Шаг 4: откройте страницу модуля

Перейдите в Addons > Perfex CRM Bridge.

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

Строка контрольного списка	Ожидаемое состояние сейчас
Module tables present	🟢 Зелёная галочка
Connection configured	🔴 Красный крестик, сопряжение ещё не выполнено
Connection verified	⚪ Серое тире, проверка никогда не выполнялась
Sync enabled	🔴 Красный крестик, пока вы не включите Enable Sync
Cron delivering	🔴 Красный крестик, активность cron ещё не зафиксирована
License / plan	⚪ Серое тире, бесплатный тариф

Это правильное состояние для только что установленного и ненастроенного моста. Каждая строка разбирается в разделе Настройка.

Далее свяжите обе стороны: Настройка.

Шаг 5: проверьте первую синхронизацию от начала до конца

Сделайте это один раз, сразу после сопряжения, прежде чем доверять мосту реальные данные. Это занимает две минуты и подтверждает работоспособность всей цепочки.

1. Выполните сопряжение, описанное в разделе Настройка. Строки контрольного списка Connection configured и Connection verified обе должны стать зелёными.
2. На той же странице в разделе Settings > Sync behaviour убедитесь, что отмечен параметр Enable Sync, затем нажмите Save Settings. Строка Sync enabled станет зелёной.
3. В WHMCS создайте тестового клиента. Подойдут любые имя и email, например компания с названием Bridge Test Ltd.
4. Вернитесь в Addons > Perfex CRM Bridge. Счётчик Queue pending вверху страницы должен показывать как минимум 1.
5. Нажмите Run Sync Now. Это принудительно запускает немедленную попытку доставки, не дожидаясь cron. Страница сообщит, сколько событий отправлено, сколько завершилось ошибкой и сколько перешло в состояние dead-letter.
6. В Perfex CRM откройте Customers. Тестовый клиент теперь присутствует там как клиент, а имя и email клиента WHMCS указаны в качестве основного контакта.
7. Убедитесь, что оба журнала это зафиксировали:
   • Сторона WHMCS: таблица Recent activity ниже на странице модуля показывает строку client.upsert со статусом ok.
   • Сторона Perfex: Setup > WHMCS Bridge, панель Recent inbound events, показывает соответствующую строку client.upsert с зелёным значком ok.
8. Удалите тестового клиента из обеих систем, если он вам не нужен.

"Run Sync Now" не доказывает, что ваш cron работает

Run Sync Now подтверждает доставку. Он не делает строку Cron delivering зелёной, потому что эта строка намеренно отслеживает реальную активность системного cron WHMCS. Если через час эта строка всё ещё красная или жёлтая, ваш системный cron WHMCS не запускается и автоматическая синхронизация работать не будет. Исправьте cron до запуска в продуктив. См. Устранение неполадок.

Обновление до новой версии

Оба модуля имеют одинаковую версию, и их всегда следует обновлять вместе.

Сторона Perfex. Загрузите новый module.zip через Setup > Modules > Upload Module, перезаписав существующий модуль, затем откройте любую страницу админки. Компаньон обнаружит устаревшую версию базы данных и применит собственные миграции на месте. Если предпочитаете, вместо этого деактивируйте и снова активируйте модуль. Оба пути безопасны: каждая инструкция миграции защищена проверкой, поэтому повторный запуск не изменит то, что уже корректно.

Сторона WHMCS. Загрузите и распакуйте новый addon.zip поверх modules/addons/perfexbridge/. WHMCS запустит процедуру обновления модуля, когда увидит новый номер версии. Если возникают сомнения, деактивируйте и снова активируйте аддон в разделе System Settings > Addon Modules.

Ваши настройки переживают обновление

Настройки, общий секрет, лицензионный ключ, карта сущностей и журналы хранятся в таблицах базы данных, которые обновление никогда не удаляет. Деактивация аддона WHMCS также не удаляет его данные.

Удаление

1. WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate, затем удалите с диска modules/addons/perfexbridge/.
2. Perfex: Setup > Modules, деактивируйте WHMCS Bridge, затем удалите модуль.
3. Если вы хотите избавиться и от данных, удалите таблицы базы данных модуля в каждой системе (сначала сделайте резервную копию).
4. Если была активна лицензия Pro, удалите ключ до деинсталляции, чтобы освободить слот активации и иметь возможность использовать лицензию в другом месте. См. Удаление ключа и возврат к бесплатному тарифу.