Настройка

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

Как две стороны аутентифицируют друг друга

Обе точки входа аутентифицируют каждый запрос подписью HMAC-SHA256, вычисленной на основе общего секрета.

Проще говоря: отправитель подписывает тело запроса секретом и добавляет метку времени. Получатель заново вычисляет подпись со своей копией секрета и отклоняет всё, у чего подпись не совпадает или чья метка времени старше 300 секунд. Именно это временное окно не позволяет кому-либо позже воспроизвести перехваченный запрос.

Отсюда следствие: секрет должен быть побайтово идентичен с обеих сторон, иначе абсолютно каждый запрос будет завершаться ошибкой 401. Кроме того, каждая точка входа отклоняет весь трафик, пока её собственный секрет пуст, поэтому наполовину настроенный мост закрыт, а не открыт.

Обе стороны перед использованием отбрасывают начальные и конечные пробелы, поэтому случайный пробел или перевод строки, подхваченный при копировании, ничего не сломает. Всё, что между ними, должно совпадать точно.

Относитесь к общему секрету как к учётным данным

Общий секрет даёт право на запись клиентов и контактов в Perfex, а с лицензией Pro - счетов, платежей, заказов и тикетов с обеих сторон. Немедленно смените его с обеих сторон, если какая-либо из баз данных или её резервная копия когда-либо оказалась скомпрометирована. Секреты хранятся в открытом виде в tbladdonmodules (WHMCS) и tbloptions (Perfex) - это стандартная практика в обеих экосистемах, поэтому у любого, кто имеет доступ к базе данных, есть и секрет.

Сопряжение: быстрый путь (рекомендуется)

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

Шаг 1: сгенерируйте секрет в Perfex

1. В Perfex CRM перейдите в Setup > WHMCS Bridge.
2. Рядом с полем Shared Secret нажмите Generate. Поле заполнится стойким случайным секретом из 64 символов и станет видимым, чтобы вы понимали, что именно сохраняете. Кнопка с изображением глаза снова скрывает значение.
3. Нажмите Save.

Шаг 2: скопируйте код подключения

Страница перезагрузится, и теперь на ней появится поле Connection code, доступное только для чтения. Его значение - одна строка, начинающаяся с PBC1..

Нажмите Copy. Кнопка на мгновение покажет "Copied!", когда код окажется в буфере обмена.

Код подключения - это пароль

Код состоит из префикса PBC1. и закодированного в base64url JSON, содержащего адрес вашей установки Perfex и ваш общий секрет. Это кодирование, а не шифрование. Любой, кто получит код, сможет обращаться к точкам входа вашего моста. Не вставляйте его в публичный тикет, чат-канал, скриншот или обращение в поддержку.

Если код подключения не появляется

Код отображается только при выполнении двух условий: ваша установка Perfex работает по HTTPS, а сохранённый общий секрет содержит не менее 32 символов. Обычная причина - нажатие Generate без последующего Save. Страница подсказывает, какое условие не выполнено:

• "not served over HTTPS" - для сопряжения нужен HTTPS. Используйте ручную настройку или исправьте сертификат.
• "shorter than 32 characters" - нажмите Generate, затем Save, и код появится.

Шаг 3: вставьте его в WHMCS

1. В WHMCS откройте Addons > Perfex CRM Bridge.
2. Найдите зелёный блок Quick setup вверху страницы.
3. Вставьте код в поле.
4. Нажмите Connect.

Что на самом деле делает Connect

За один шаг и именно в этом порядке:

1. Декодирует код и строго его проверяет: префикс PBC1., корректный base64url, правильно сформированный объект JSON, адрес, начинающийся с https:// и проходящий валидацию URL, и секрет длиной не менее 32 символов.
2. Отправляет подписанный ping в вашу установку Perfex, используя декодированные адрес и секрет, и ждёт ответа pong.
3. Только если этот ping успешен, сохраняет Perfex CRM URL и Shared Secret на стороне WHMCS.
4. Только при первом сопряжении ping также передаёт базовый адрес вашей установки WHMCS, поэтому поле WHMCS URL на стороне Perfex заполняется автоматически. Это происходит только если ваш WHMCS работает по HTTPS, и никогда не перезаписывает уже заданное значение.
5. Фиксирует успешную проверку, поэтому строка контрольного списка Connection verified становится зелёной на этой же загрузке страницы.

При успехе вы получите зелёный баннер с названием адреса Perfex, с которым выполнено сопряжение. При неудаче - красный баннер с точным описанием проблемы, и ничего не сохраняется. Код, не прошедший проверку, никогда не сможет перезаписать конфигурацию, которая сейчас работает.

Повторное сопряжение в будущем

После настройки WHMCS блок Quick setup превращается в неприметную форму Re-pair. Вставляйте свежий код в любой момент, когда меняете секрет или переносите Perfex на новый домен. Правило то же: код, не прошедший проверку, ничего не меняет.

Сначала смените секрет, затем выполните повторное сопряжение, именно в таком порядке

Если вы нажмёте Generate и Save на стороне Perfex, все существующие запросы WHMCS немедленно начнут завершаться ошибкой HTTP 401, пока вы не вставите новый код в WHMCS. Выполняйте эти два шага подряд. Старый код, скопированный до смены секрета, будет отклонён, и баннер сообщит, что Perfex ответил кодом 401.

Сопряжение: ручной способ

Код подключения - это удобство, а не магия. Всё, что он делает, можно сделать вручную, и этот путь понадобится вам, если ваша установка Perfex ещё не работает по HTTPS или если ваш регламент запрещает вставлять объединённые учётные данные.

1. Сгенерируйте стойкий случайный секрет длиной не менее 32 символов. Используйте кнопку Generate на странице настроек Perfex или собственный инструмент, например openssl rand -hex 32.
2. В Perfex, на странице Setup > WHMCS Bridge, вставьте его в поле Shared Secret и нажмите Save.
3. В WHMCS откройте Addons > Perfex CRM Bridge, прокрутите до Settings > Connection и:
   • укажите в Perfex CRM URL базовый адрес вашей установки Perfex, например https://crm.example.com, по HTTPS и без завершающего пути;
   • вставьте тот же самый секрет в поле Shared Secret.
4. Нажмите Save Settings.
5. Нажмите Test Connection вверху страницы. Вам нужен зелёный баннер "Connection OK".
6. Для двусторонней синхронизации Pro также задайте WHMCS URL на странице настроек Perfex. При сопряжении это было бы сделано за вас.

Настройки WHMCS, раздел за разделом

Все настройки находятся на собственной странице модуля

Откройте Addons > Perfex CRM Bridge и прокрутите до раздела Settings. Не ищите их на экране Configure в WHMCS в разделе System Settings > Addon Modules: на том экране остаётся только Access Control, который отрисовывается ядром WHMCS и не может быть перенесён.

Нажмите Save Settings, чтобы применить изменения. Форма работает по принципу "всё или ничего": некорректное значение, например адрес не по HTTPS, отклоняет всю отправку целиком и ничего не меняет.

Два поля с секретами никогда не показывают сохранённое значение

Поля Shared Secret и Pro License Key всегда отображаются пустыми, поэтому сохранённые учётные данные никогда не попадают в исходный код страницы у каждого администратора, который может открыть модуль. Оставьте поле пустым, чтобы сохранить текущее значение. Введите что-то, чтобы заменить его. Чтобы полностью удалить ключ Pro, отметьте Remove the stored key.

Connection

Параметр	Что делает	Разумное значение по умолчанию
Perfex CRM URL	Базовый адрес вашей установки Perfex, например https://crm.example.com. Обязательно по HTTPS: мост отказывается отправлять данные по обычному HTTP.	Задаётся автоматически при сопряжении
Shared Secret	Секрет для HMAC. Должен совпадать с секретом, заданным в Perfex в разделе Setup > WHMCS Bridge. Оставьте пустым, чтобы сохранить текущее значение.	Задаётся автоматически при сопряжении

Sync behaviour

Параметр	Что делает	Разумное значение по умолчанию
Enable Sync	Главный переключатель. Снимите отметку, чтобы приостановить всю исходящую доставку. Во время паузы события продолжают ставиться в очередь, поэтому ничего не теряется; они будут доставлены на первом же такте после повторного включения.	Включено после настройки
Order Sync Target (Pro)	Во что превращается заказ WHMCS в Perfex. lead создаёт по одному лиду Perfex на заказ. note вместо этого добавляет заметку у клиента Perfex. off вообще не синхронизирует заказы.	lead
Two-Way Conflict Policy (Pro)	Какая сторона побеждает, когда обе системы изменили одного и того же клиента или контакт с момента последней синхронизации. См. ниже.	newest_wins

Варианты политики разрешения конфликтов, по одной строке на каждый:

• newest_wins (по умолчанию) - сравнивает время входящего события Perfex со временем последней синхронизации, побеждает более свежее изменение.
• whmcs_wins - сохраняет данные WHMCS и отбрасывает конфликтующее изменение из Perfex.
• perfex_wins - применяет изменение из Perfex поверх данных WHMCS.

Политика конфликтов срабатывает только при настоящем конфликте

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

Замечание о newest_wins и часах на серверах

"Более свежее" определяется сравнением метки времени отправляющего сервера со временем последней синхронизации на принимающем, поэтому точность часов обоих хостов имеет значение. Держите оба сервера на NTP. Если расхождение часов между хостом WHMCS и хостом Perfex вам неподконтрольно, выбирайте whmcs_wins или perfex_wins - они детерминированы.

Tickets

Параметр	Что делает	Разумное значение по умолчанию
Ticket Reply Admin (Pro)	Имя пользователя администратора WHMCS, от которого добавляется ответ сотрудника Perfex, синхронизированный в тикет WHMCS. Оставьте пустым, чтобы вместо этого указывать имя сотрудника Perfex, а ответ публиковать как неадминистративный.	Пусто

Лицензия Pro

Параметр	Что делает	Разумное значение по умолчанию
Pro License Key	Оставьте пустым для бесплатного тарифа. Вставьте сюда ваш ключ Pro, чтобы открыть возможности Pro. Ключи начинаются с sk_. Сохранение изменившегося ключа сразу же запускает его проверку по сети.	Пусто (Free)
Remove the stored key	Флажок, который появляется, только когда ключ сохранён. Отметка и сохранение возвращают установку на бесплатный тариф и освобождают слот активации этого сайта, чтобы лицензию можно было использовать в другом месте.	Не отмечено
Check licence now (кнопка вверху страницы)	Принудительно запускает немедленную повторную проверку уже сохранённого ключа, игнорируя ограничение "раз в сутки".	-
Upgrade to Pro / Buy a Pro licence (ссылки)	Открывают оформление покупки. На установке без Pro они появляются рядом с полем ключа, в строке контрольного списка с лицензией и в информационных блоках о Pro.	-

Подробности - в разделе Лицензирование и активация Pro.

Настройки Pro безопасно задавать и на бесплатном тарифе

Order Sync Target, Two-Way Conflict Policy и Ticket Reply Admin прекрасно сохраняются на бесплатной установке. Они просто не действуют, пока не активна действующая лицензия, и страница сообщает об этом под каждым полем. При желании настройте их заранее.

Настройки Perfex CRM, поле за полем

Откройте Setup > WHMCS Bridge в админке Perfex, затем нажмите Save.

Connection

Поле	Что делает	Значение по умолчанию / запасной вариант
Shared Secret	Должен совпадать с полем Shared Secret в WHMCS. Используйте Generate для стойкого значения, затем Save. Кнопка с глазом показывает или скрывает значение. Пока поле пусто, точка входа отклоняет весь трафик.	Пусто, точка входа закрыта
Connection code	Только для чтения. Появляется, когда сохранённый секрет содержит 32 символа или больше, а Perfex работает по HTTPS. Скопируйте его в блок Quick setup в WHMCS.	Формируется автоматически
WHMCS URL	Базовый адрес установки WHMCS, на которой работает аддон. Нужен только для трафика из Perfex в WHMCS, а это возможность Pro. Должен начинаться с https://, иначе не сохраняется.	Заполняется автоматически при первом сопряжении, после этого никогда не перезаписывается

Синхронизация тикетов (Pro)

Поле	Что делает	Значение по умолчанию / запасной вариант
Department mapping (WHMCS to Perfex)	Сопоставляет каждый отдел тикетов WHMCS с отделом Perfex. Отображается как один выпадающий список на каждый отдел WHMCS, если справочник удалось получить, либо как текстовое поле для ручного ввода в противном случае.	Пусто, ничего не сопоставлено
Default department for unmapped WHMCS tickets	Отдел Perfex, используемый для любого тикета WHMCS, чей отдел отсутствует в сопоставлении.	"Lowest department id (automatic)"
Staff author for synced WHMCS staff replies	Сотрудник Perfex, указываемый автором ответов сотрудников WHMCS, зеркалируемых в Perfex.	"First active admin (automatic)"
Create a Perfex task per synced ticket	Если отмечено, каждый синхронизированный тикет получает связанную задачу Perfex, чтобы ваши сотрудники могли учитывать по ней время в нативных таймшитах Perfex.	Выключено

Как отображается сопоставление отделов

Обычный сценарий - выпадающие списки. При загрузке страницы настроек она получает справочник отделов поддержки WHMCS по подписанному каналу моста и отображает по одной строке на каждый отдел WHMCS с выпадающим списком ваших отделов Perfex. Выберите цель для каждой строки либо оставьте значение - not mapped - и нажмите Save.

Для этого запроса нужны работающее подключение и лицензия Pro на стороне WHMCS, потому что справочник отделов закрыт тем же лицензионным ограничением, что и синхронизация тикетов. Когда запрос выполнить не удаётся, страница автоматически переключается на текстовое поле для ручного ввода и объясняет причину:

Что вы видите	Что это значит
Выпадающие списки, по одному на каждый отдел WHMCS	Всё работает
Текстовое поле, "Couldn't fetch WHMCS departments (needs Pro + working connection)"	Мост ещё не настроен, WHMCS недоступен с сервера Perfex либо установка WHMCS работает на бесплатном тарифе
Текстовое поле, "Connection OK, but WHMCS has no support departments yet"	Запрос выполнен успешно. Создайте отделы в WHMCS в разделе Support > Support Departments, затем перезагрузите эту страницу

Время на получение справочника ограничено несколькими секундами, поэтому недоступный WHMCS слегка замедляет страницу настроек, но никогда её не подвешивает.

Формат ручного ввода - одно сопоставление на строку, идентификатор отдела WHMCS слева и идентификатор отдела Perfex справа:

1=2
2=5
3=5

Когда отображаются выпадающие списки, ссылка Advanced: edit the mapping manually открывает то же самое текстовое поле. Пока этот ручной редактор открыт, сохраняется именно его содержимое, перекрывая выбор в выпадающих списках.

Порядок определения отдела для входящего тикета:

1. Точное совпадение в сопоставлении.
2. Иначе - заданный Default department.
3. Иначе - наименьший идентификатор отдела Perfex, выбранный автоматически.

Опечатка в строке сопоставления мягко деградирует до запасного варианта. Она не мешает сохранению и не ломает синхронизацию.

Время, учтённое в задаче на тикет, остаётся в Perfex

Дополнительная задача Perfex нужна для того, чтобы ваши сотрудники могли использовать нативные таймшиты Perfex по тикету. Эти записи времени не синхронизируются обратно в WHMCS, и задача не закрывается автоматически при закрытии тикета.

Панели на той же странице

В правой колонке страницы Setup > WHMCS Bridge расположены три панели только для чтения:

• WHMCS plan - какой тариф последний раз сообщила сторона WHMCS (Pro, Free или Unknown), когда лицензия проверялась в последний раз, и кнопка Upgrade to Pro, когда есть что купить.
• Outbound queue - изменения на стороне Perfex, ожидающие отправки в WHMCS, с числом ожидающих и "мёртвых" записей, количеством повторов, временем следующей попытки и последней ошибкой по каждой строке.
• Recent inbound events - что WHMCS отправил в эту установку Perfex, со статусом и сообщением.

Это ваша диагностика на стороне Perfex. См. Как это работает и повседневная эксплуатация.

Контрольный список настройки, построчно

Страница модуля в WHMCS открывается контрольным списком настройки из шести строк. Каждая строка отмечена зелёной галочкой, жёлтым предупреждением, красным крестиком или серым тире, плюс однострочная подсказка. Зелёный по всем строкам, с серым в строке лицензии, если вы на бесплатном тарифе, означает, что мост исправен.

Строка	Зелёный означает	Всё остальное означает
Module tables present	Таблицы outbox, map и log существуют.	🔴 Красный: таблица отсутствует. Деактивируйте и снова активируйте модуль в разделе System Settings > Addon Modules, чтобы создать её заново.
Connection configured	Заданы и адрес Perfex, и общий секрет.	🔴 Красный: ещё не заданы. Вставьте код подключения в блок Quick setup или заполните оба поля в разделе Settings > Connection.
Connection verified	Подписанный ping получил ответ pong, и строка показывает, как давно это было.	🔴 Красный: последняя проверка не прошла, и строка показывает ошибку. Устраните её, затем нажмите Test Connection. ⚪ Серый: проверка никогда не выполнялась либо последняя была более 24 часов назад. Нажмите Test Connection, чтобы обновить.
Sync enabled	Исходящая доставка включена.	🔴 Красный: синхронизация приостановлена. События продолжают ставиться в очередь, но не доставляются. Отметьте Enable Sync в разделе Settings > Sync behaviour и сохраните.
Cron delivering	Системный cron WHMCS недавно выполнял реальную работу моста, и строка показывает, насколько недавно.	🟠 Жёлтый: активности cron не было некоторое время. Проверьте, что системный cron WHMCS запущен. 🔴 Красный: активность cron не фиксировалась никогда. На совершенно новой установке это нормально до первой доставки; если состояние сохраняется, ваш cron не работает.
License / plan	Тариф Pro активен.	⚪ Серый: лицензионного ключа нет, это бесплатный тариф и полностью поддерживаемый способ работы с модулем. 🔴 Красный: ключ задан, но не проходит проверку. Проверьте ключ, затем нажмите Check licence now.

Строку "Cron delivering" намеренно сложно подделать

Зелёной её делает только настоящий такт системного cron WHMCS. Run Sync Now доставляет ваши события из очереди и подтверждает, что доставка работает, но эту строку не затрагивает. В этом и смысл: строка отвечает на вопрос "продолжит ли это работать, когда никто не смотрит?", а нажатие кнопки на такой вопрос ответить не может.

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

И Connect (сопряжение), и Test Connection обновляют строку Connection verified.

Что дальше

• Проверьте всю цепочку от начала до конца: Установка, шаг 5.
• Откройте двустороннюю синхронизацию, счета и тикеты: Лицензирование и активация Pro.
• Разберитесь, что синхронизируется и где находятся журналы: Как это работает и повседневная эксплуатация.