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

Проходите эту страницу по порядку. Первые три раздела покрывают подавляющее большинство обращений в поддержку.

Прежде всего откройте Addons > Perfex CRM Bridge в WHMCS и прочитайте контрольный список настройки. Он специально сделан так, чтобы указывать прямо на проблему, и каждая строка разбирается в разделе Настройка.

Краткий справочник

Симптом	Наиболее вероятная причина	Решение
Модуль отсутствует в меню Addons в WHMCS	В Access Control не отмечена ни одна роль администратора	Отметьте роли в Access Control
Все отправки сразу завершаются ошибкой	Адрес Perfex начинается с http://	Используйте HTTPS
Строки auth.rejected в журнале входящих событий Perfex	Общий секрет не совпадает	Выполните повторное сопряжение
"Two-way sync requires Pro" в очереди исходящих Perfex	Сторона WHMCS работает на бесплатном тарифе	Активируйте Pro
События ставятся в очередь, но не доставляются	Синхронизация приостановлена либо cron WHMCS не работает	Проверьте cron
Один счёт никогда не доходит и повторяется бесконечно	Валюта счёта отсутствует в Perfex	Добавьте валюту
Лицензия не активируется	Отсутствует ключ либо нет связи со службой лицензирования	Смотрите на цвет баннера
На странице Perfex нет поля Connection code	Perfex работает не по HTTPS либо сохранённый секрет слишком короткий	Нажмите Generate и Save
Сопоставление отделов показывает текстовое поле, а не выпадающие списки	Бесплатный тариф либо WHMCS недоступен из Perfex	Запасные варианты сопоставления
Строки застряли в состоянии dead	15 неудачных попыток по одной и той же причине	Повторите обработку "мёртвых" строк

Модуль отсутствует в меню Addons

Симптом. Вы активировали Perfex CRM Bridge в разделе System Settings > Addon Modules, WHMCS сообщил об успешной активации, но модуля нигде нет в меню Addons слева.

Причина. Ни одной роли администратора не выдан доступ. WHMCS полностью скрывает аддон от любой роли, которая не отмечена, поэтому модуль установлен и полностью работоспособен, но ссылки на него нигде в админке нет. Это самая частая жалоба вида "модуль не установился".

Решение.

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

Больше на этом экране Configure ничего нет

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

Все отправки сразу завершаются ошибкой, или адрес отклоняется

Симптом. События ставятся в очередь и мгновенно завершаются ошибкой. Журнал Recent activity заполняется ошибками соединения. Либо поле Perfex CRM URL вообще отказывается сохраняться.

Причина. HTTPS требуется по замыслу. HTTP-транспорт жёстко привязан к протоколу https и проверяет TLS-сертификат. Адрес вида http:// приводит к сбою абсолютно каждой отправки, а поле WHMCS URL на стороне Perfex точно так же отказывается сохраняться, если значение не начинается с https://.

Решение.

1. Задайте в Perfex CRM URL адрес вида https:// на стороне WHMCS.
2. Задайте в WHMCS URL адрес вида https:// на стороне Perfex.
3. Убедитесь, что оба сертификата действительно проходят проверку с противоположного сервера, а не только в вашем браузере. Самоподписанный сертификат работает только в том случае, если вызывающий сервер ему доверяет.
4. Нажмите Test Connection на странице модуля в WHMCS.

Отключить проверку HTTPS невозможно

Это сделано намеренно. По этому каналу передаются ваш общий секрет и данные ваших клиентов. Если сертификат не проходит проверку, исправьте сертификат.

Строки auth.rejected в журнале Perfex

Симптом. WHMCS сообщает об ошибках HTTP 401. В Perfex, в разделе Setup > WHMCS Bridge > Recent inbound events, отображаются красные строки auth.rejected.

Причина. Общий секрет не совпадает на двух сторонах либо метка времени запроса выходит за пределы окна в 300 секунд. На практике почти всегда дело в секрете: кто-то сгенерировал его заново на одной стороне и не выполнил повторное сопряжение на другой.

Быстрое решение.

1. В Perfex, в разделе Setup > WHMCS Bridge, скопируйте текущее значение Connection code.
2. В WHMCS, в разделе Addons > Perfex CRM Bridge, вставьте его в блок Re-pair и нажмите Connect.
3. Нажмите Test Connection. Вам нужен зелёный баннер "Connection OK".
4. Нажмите Run Sync Now. Поставленные в очередь события, которые завершались ошибкой, теперь будут доставлены.

Решение вручную. Заново вставьте абсолютно один и тот же секрет в оба поля Shared Secret и сохраните с обеих сторон. Начальные и конечные пробелы отбрасываются автоматически, но всё, что между ними, должно совпадать посимвольно.

Если дело не в секрете. Проверьте часы на обоих серверах. Расхождение более 300 секунд между ними приводит к тому, что каждый запрос отклоняется как повтор. Настройте оба хоста на NTP.

Количество отклонённых строк ограничено

Perfex записывает не более 10 строк auth.rejected в минуту, поэтому неправильно настроенный отправитель не сможет заполнить ваш диск. Если вы видите ровно 10 строк за минуту, считайте, что их было больше.

"Two-way sync requires Pro" в очереди исходящих Perfex

Симптом. Вы изменяете клиента в Perfex. Панель Outbound queue в разделе Setup > WHMCS Bridge показывает строку с сообщением "Two-way sync requires Pro on the WHMCS side." и ссылку Upgrade to Pro. Число попыток растёт, и в итоге строка переходит в состояние dead.

Причина. Двусторонняя синхронизация - возможность Pro, а лицензия хранится на стороне WHMCS. Ваша установка WHMCS работает на бесплатном тарифе, поэтому её входящая точка отвечает кодом 403 на любое изменение, инициированное в Perfex. Компаньон для Perfex ведёт себя правильно, ставя изменения в очередь и повторяя попытки.

Решение. Активируйте лицензию Pro на стороне WHMCS. См. Лицензирование и активация Pro. Как только Pro станет активным, WHMCS немедленно передаст новое состояние тарифа в Perfex, предложение об обновлении исчезнет, а ожидающие строки будут доставлены при следующем запуске cron в Perfex.

Строки, которые уже перешли в состояние dead, пока вы были на бесплатном тарифе, сами повторяться не будут. См. Строки застряли в состоянии dead.

Сначала посмотрите на панель тарифа

Панель WHMCS plan расположена прямо над очередью исходящих на странице настроек Perfex именно по этой причине. Если там указано Free, ответ у вас есть, и читать строки очереди не придётся.

Ничего не синхронизируется вообще

Симптом. События появляются в очереди, счётчик Queue pending растёт, и ничего не доходит до Perfex. Никаких ошибок, просто тишина.

Причин две, и контрольный список позволяет их различить.

Причина А: синхронизация приостановлена

Строка контрольного списка Sync enabled красная.

Решение. На странице модуля в WHMCS, в разделе Settings > Sync behaviour, отметьте Enable Sync и нажмите Save Settings. Во время паузы ничего не потерялось; события продолжали ставиться в очередь и теперь будут доставлены.

Причина Б: системный cron WHMCS не работает

Строка контрольного списка Cron delivering красная или жёлтая.

Решение.

1. Убедитесь, что сам мост работает, нажав Run Sync Now. Если очередь разбирается, доставка в порядке и проблема действительно в cron.
2. Проверьте состояние собственного cron WHMCS в разделе Utilities > System > System Health Status. WHMCS показывает, когда системный cron запускался в последний раз.
3. Если cron давно не запускался, исправьте это на уровне сервера. Команда cron для WHMCS находится в менеджере заданий вашей хостинг-панели или в crontab вашего сервера. Точную команду для вашей версии приводит собственная документация WHMCS.
4. Как только cron заработает снова, строка Cron delivering станет зелёной при следующей загрузке страницы после того, как мост выполнит реальную работу.

Run Sync Now не может сделать строку cron зелёной

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

Жёлтая строка cron - не всегда проблема

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

Счёт застрял и не доходит до Perfex

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

Причина. Валюта счёта не настроена в Perfex. Perfex справедливо отклоняет счёт, потому что не может записать итог в валюте, которая ему неизвестна.

Решение.

1. В Perfex перейдите в Setup > Finance > Currencies.
2. Добавьте валюту, используя точный код ISO, который применяет WHMCS, например EUR или USD.
3. Больше ничего не делайте. Событие в очереди повторится по собственному расписанию и на следующей попытке пройдёт успешно.

У вас есть примерно 40 часов

Расписание повторов допускает 15 попыток на протяжении примерно 40 часов. Добавьте валюту в этот интервал, иначе строка уйдёт в dead-letter и её придётся повторять вручную. Если вы собираетесь переносить исторические счета, сначала добавьте все валюты, которые используют ваши клиенты.

Смежный случай: "Not mapped (will retry)"

Дочерняя запись поступила раньше родительской: контакт, чей клиент ещё не появился в Perfex, счёт, чей клиент ещё не сопоставлен, или ответ на тикет, чей тикет ещё не синхронизирован.

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

Лицензия не активируется

Симптом. Вы вставили ключ, а установка по-прежнему показывает бесплатный тариф.

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

Баннер	Значение	Решение
🔴 Красный	Сервер лицензирования явно отклонил ключ, и сообщение объясняет почему.	Скопируйте ключ из письма о покупке заново и целиком. Ключи состоят из 32 символов и могут содержать знаки препинания, поэтому ничего не обрезайте и не переформатируйте. Если в сообщении упоминаются установки или квота, освободите слот активации, удалив ключ с той установки, где он больше не нужен.
🟠 Жёлтый	Ваш сервер не смог связаться со службой лицензирования. Это не отказ.	Ключ сохранён, и попытки продолжаются. Разрешите исходящие HTTPS-соединения к api.freemius.com во всех межсетевых экранах и прокси на сервере WHMCS. Затем нажмите Check licence now.
⚪ Баннера нет вообще	Вы сохранили тот же ключ, который уже был сохранён, поэтому повторная проверка не выполнялась.	Нажмите Check licence now.
В заголовке написано "awaiting first verification"	Ключ сохранён, но ни разу не был подтверждён.	Нажмите Check licence now.

Дополнительные проверки:

• Убедитесь, что ключ находится в поле Pro License Key в разделе Settings > Pro licence на собственной странице модуля, а не где-то на экране Configure в WHMCS.
• Нажимайте Check licence now с паузой в несколько секунд. Быстрое повторное нажатие отвечает "проверено только что", не отправляя запрос.
• Если Pro активен в WHMCS, но Perfex по-прежнему показывает Free, нажмите Check licence now или Test Connection в WHMCS. Обе кнопки немедленно передают состояние тарифа в Perfex. Затем перезагрузите страницу настроек Perfex.

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

В Perfex не появляется Connection code

Симптом. Вы находитесь в разделе Setup > WHMCS Bridge, сохранили секрет, но поля Connection code нет, есть только серое примечание.

Причины и решения. Само примечание подсказывает, какой случай ваш.

Примечание	Причина	Решение
"not served over HTTPS"	Для сопряжения нужна установка Perfex, работающая по HTTPS.	Исправьте сертификат либо используйте ручную настройку.
"shorter than 32 characters"	Сохранённый секрет слишком короткий. Обычная причина - нажатие Generate без последующего Save.	Нажмите Generate, затем Save. Код появится после перезагрузки.

Сопряжение завершается сообщением о несовпадении общего секрета

Симптом. Вы вставили код подключения в WHMCS и получили красный баннер с упоминанием HTTP 401.

Причина. Код содержит секрет, которого у Perfex больше нет. Почти всегда это код, скопированный до последующего Generate и Save, либо Generate, который так и не был сохранён.

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

Сопоставление отделов показывает текстовое поле вместо выпадающих списков

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

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

Подсказка	Причина	Решение
"Couldn't fetch WHMCS departments (needs Pro + working connection)"	Мост не настроен, WHMCS недоступен с сервера Perfex либо WHMCS работает на бесплатном тарифе. Справочник закрыт тем же лицензионным ограничением, что и синхронизация тикетов.	Завершите сопряжение, проверьте, что Perfex может обратиться к вашему адресу WHMCS по HTTPS, и активируйте Pro.
"Connection OK, but WHMCS has no support departments yet"	Запрос выполнен успешно; сопоставлять просто нечего.	Создайте отделы в WHMCS в разделе Support > Support Departments, затем перезагрузите страницу Perfex.

Тем временем всегда работает ручной формат whmcs_deptid=perfex_department_id в текстовом поле, по одному сопоставлению на строку. Синхронизация из-за этого не блокируется: несопоставленный тикет попадает в ваш отдел по умолчанию либо в отдел Perfex с наименьшим идентификатором.

Строки застряли в состоянии dead

Симптом. Счётчик Dead events на странице модуля в WHMCS или счётчик dead на панели Outbound queue в Perfex больше нуля.

Причина. Эти строки 15 раз за примерно 40 часов завершились ошибкой по одной и той же причине. Строки в состоянии dead намеренно никогда не повторяются автоматически и никогда не удаляются при очистке, чтобы вы могли их изучить.

Решение.

1. Выясните причину. Откройте Recent activity в WHMCS либо столбец "Last error" в очереди исходящих в Perfex и прочитайте ошибку по затронутым строкам. Причина почти всегда одна из следующих: отсутствующая валюта в Perfex, несовпадение секрета, бесплатный тариф, блокирующий событие Pro, или недоступность Perfex.

2. Сначала устраните первопричину. Повтор строки без устранения причины просто сожжёт ещё 40 часов.

3. Поставьте работу в очередь заново. Самый безопасный путь не требует доступа к базе данных:

   • Для клиентов, контактов, счетов, услуг и доменов вызовите событие повторно. Измените и сохраните запись в WHMCS либо запустите мастер переноса данных в режиме Only new (not yet synced).
   • Для изменений на стороне Perfex снова отредактируйте запись Perfex, чтобы поставить в очередь новое событие.

4. Если вы предпочитаете повторить исходную строку и у вас есть доступ к базе данных, переведите её обратно в состояние pending. Сначала сделайте резервную копию:

   UPDATE mod_perfexbridge_outbox
      SET status = 'pending', attempts = 0, next_attempt_ts = 0
    WHERE id = 123;

   Замените 123 на идентификатор строки, которую хотите повторить. Аналогичная таблица на стороне Perfex - tblwhmcs_bridge_outbox, с вашим префиксом таблиц Perfex.

Изменение в Perfex не доходит до WHMCS

Пройдите по этому списку:

1. Активен ли Pro на стороне WHMCS? Проверьте панель WHMCS plan на странице настроек Perfex. Двусторонняя синхронизация доступна только в Pro.
2. Задан ли WHMCS URL на стороне Perfex? Setup > WHMCS Bridge > WHMCS URL, по HTTPS, без завершающего пути. При первом сопряжении это поле обычно заполняется автоматически, но уже заданное значение никогда не перезаписывается.
3. Может ли сервер Perfex обратиться к WHMCS по HTTPS? Клиент отправки в Perfex жёстко привязан к HTTPS и проверяет сертификат, ровно как и сторона WHMCS.
4. Работает ли cron в Perfex? Изменения, инициированные в Perfex, доставляются по cron Perfex, а не WHMCS. Проверьте задание cron в Perfex.
5. Сопоставлена ли запись? Сопоставлены только клиенты, синхронизированные из WHMCS. У клиента, созданного напрямую в Perfex, нет соответствия в WHMCS, и он никогда не отправляется. Точно так же тикеты, созданные напрямую в Perfex, остаются в Perfex.
6. Прочитайте панель Outbound queue. Она указывает последнюю ошибку по каждой строке.

Изменение вернулось обратно и перезаписало мою правку

Симптом. Вы изменили запись в одной системе, а она вернулась к значению из другой системы.

Причина. Обе стороны изменили одну и ту же запись с момента последней синхронизации, и победителя определила ваша политика Two-Way Conflict Policy.

Решение. Выберите политику, соответствующую тому, как работает ваша команда, в разделе Settings > Sync behaviour на странице модуля в WHMCS:

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

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

Клиенты получают два письма на один ответ в тикете

Симптом. Сотрудник Perfex отвечает в синхронизированном тикете, и клиент получает два уведомления.

Причина. Perfex отправляет собственное письмо об ответе в тикете, а ответ, синхронизированный в WHMCS, заставляет WHMCS отправить своё уведомление. Это задокументированное поведение, а не цикл синхронизации. Подавление писем работает только в направлении из WHMCS в Perfex.

Решение. Если ваши клиенты работают в клиентском портале WHMCS, отключите в Perfex шаблон письма ticket-reply в разделе Setup > Email Templates > Tickets.

Проблема осталась: что собрать перед обращением в поддержку

Подготовьте следующее, и ответ обычно приходит с первого же письма:

• Версия обоих модулей, сейчас это 1.3.4, и подтверждение того, что обе стороны работают на одной версии.
• Версия WHMCS, версия Perfex CRM и версия PHP на обоих серверах.
• Скриншот контрольного списка настройки со страницы модуля в WHMCS.
• Значения счётчиков Queue pending и Dead events.
• Соответствующие строки из Recent activity в WHMCS и Recent inbound events в Perfex, вместе с полным содержимым столбца с сообщением.
• Что вы делали в момент сбоя и работало ли это когда-либо раньше.

Никогда не отправляйте свой общий секрет или код подключения

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