Как это работает и повседневная эксплуатация
После того как мост сопряжён и синхронизация включена, он работает сам по себе. Эта страница объясняет, что именно он делает, чтобы при появлении чего-то странного вы знали, куда смотреть, а не гадали.
Движок синхронизации простыми словами
1. Изменение порождает событие
Каждое значимое изменение в WHMCS вызывает хук WHMCS: добавлен или изменён клиент, создан контакт, выставлен счёт, поступил платёж, размещён заказ, предоставлена или приостановлена услуга, открыт тикет или добавлен ответ.
Хук не выполняет HTTP-запрос. Он записывает небольшое событие в таблицу outbox (mod_perfexbridge_outbox) и мгновенно возвраща ет управление.
Если бы хук WHMCS обращался к Perfex напрямую, медленный или недоступный сервер Perfex блокировал бы админ-страницу WHMCS или оформление заказа клиентом. Запись в локальную таблицу занимает миллисекунду и никогда не может завершиться неудачей из-за чужой сети. Всё остальное происходит в фоне.
2. Cron разбирает очередь
На каждом такте системного cron WHMCS диспетчер забирает из outbox пакет событий, которым пришло время, и отправляет каждое из них методом POST в вашу установку Perfex по HTTPS.
Каждый запрос несёт два заголовка помимо тела JSON: метку времени и подпись HMAC-SHA256, вычисленную по этой метке времени и точному телу запроса с использованием вашего общего секрета. Perfex заново вычисляет подпись со своей копией секрета и отклоняет всё, что не совпадает или чья метка времени старше 300 секунд.
Принудительно запустить разбор очереди можно в любой момент кнопкой Run Sync Now на странице модуля в WHMCS.
3. Сбои повторяются, затем уходят в dead-letter
Неудачная отправка не теряется и не повторяется в плотном цикле. Она переносится с экспоненциальной задержкой: примерно через 60 секунд после первой неудачи, затем через 2 минуты, 4, 8 и так далее, с ограничением в 6 часов между попытками.
После 15 попыток, охватывающих примерно 40 часов, строка помечается как dead. Такие строки никогда не повторяются автоматически и никогда не удаляются при очистке. Это ваш ящик недоставленных сообщений: счётчик Dead events вверху страницы модуля в WHMCS по казывает, сколько их, а строка журнала объясняет причину.
Переход в dead-letter означает, что одно и то же событие почти двое суток завершалось неудачей по одной и той же причине. Почти всегда причина одна из четырёх: в Perfex отсутствует валюта, не совпадает секрет, бесплатный тариф блокирует событие Pro, или Perfex был недоступен. Устраните причину и поставьте работу в очередь заново. См. Устранение неполадок.
4. Пауза ничего не теряет
Снятие отметки с Enable Sync приостанавливает только доставку. Хуки продолжают записывать события в outbox, поэтому во время паузы ничего не теряется. Включите синхронизацию снова, и накопившееся будет доставлено на следующем такте либо немедленно по кнопке Run Sync Now.
5. Подавление эха предотвращает бесконечные циклы
Двусторонняя синхронизация создаёт очевидный риск: WHMCS применяет изменение, пришедшее из Perfex, эта запись вызывает собственные хуки WHMCS, и изменение тут же уходит обратно. Без защиты одна правка курсировала бы туда-сюда вечно.
Мост предотвращает это многоуровневыми защитами, применяемыми с обеих сторон:
- Флаг источника в рамках запроса, устанавливаемый на время, пока мост применяет входящее изменение, чтобы его собственные записи не считались новыми правками пользователя.
- Поиск в карте сущностей и идентификаторов ответов, чтобы ответ на тикет, только что созданный мостом, распознавался, а не отправлялся заново как новый.
- Сравнение контрольных сумм, которое превращает событие в пустую операцию, когда данные уже совпадают с последним синхронизированным состоянием.
У каждой стороны есть свой флаг источника, а контрольная сумма работает как подстраховка на случай, если флаг будет обойдён. Защиты намеренно срабатывают в сторону разрешения: если защита не может принять решение, лучше одна лишняя безвредная отправка, чем молча потерянное обновление.
6. Обслуживание
Обе стороны выполняют самоограниченную ежедневную очистку, не чаще одного раза в 24 часа:
- доставленные строки outbox старше 7 дней удаляются;
- строки журнала старше 90 дней удаляются;
- строки в состоянии pending и dead не удаляются никогда, потому что pending - это недоставленная работа, а dead - ваш ящик недоставленных сообщений.
Что синхронизируется и в каком направлении
Из WHMCS в Perfex CRM
| Данные | Free | Pro | Что появляется в Perfex |
|---|---|---|---|
| 👥 Клиенты | ✅ | ✅ | Клиент Perfex плюс основной контакт с именем и email клиента |
| 👤 Контакты | ✅ | ✅ | Дополнительные контакты у того же клиента Perfex |
| 🗑️ Удаление клиента | ✅ | ✅ | Клиент Perfex деактивируется, а не уничтожается |
| 📄 Счета | ➖ | ✅ | Счёт Perfex с позициями, налоговой строкой, совпадающими итогами, статусом и номером счёта WHMCS в служебной заметке |
| 💳 Платежи и транзакции | ➖ | ✅ | Запись о платеже по зеркальному счёту с указанием шлюза и идентификатора транзакции. Дубликаты отклоняются |
| 💸 Возвраты | ➖ | ✅ | Зеркало в Perfex отменяется и снабжается пометкой |
| 🛒 Заказы | ➖ | ✅ | Лид Perfex на каждый заказ, либо заметка у клиента, либо ничего, согласно параметру Order Sync Target |
| 📦 Услуги | ➖ | ✅ | Строки на вкладке WHMCS у клиента: название продукта, домен, статус, цикл оплаты, сумма и дата следующего платежа |
| 🌐 Домены | ➖ | ✅ | Строки на той же вкладке: регистратор, статус, дата окончания и дата следующего платежа |
| 🎫 Тикеты и ответы | ➖ | ✅ | Тикет Perfex у клиента, в сопоставленном отделе, с ответами и статусом |
На бесплатном тарифе статус и заметки клиента передаются в полезной нагрузке, но не записываются в Perfex. Только удаление клиента влияет на запись в Perfex, деактивируя её.
Из Perfex CRM в WHMCS (только Pro)
| Изменение, сделанное в Perfex | Что происходит в WHMCS |
|---|---|
| Изменены данные компании клиента | Запись клиента в WHMCS обновляется с учётом политики разрешения конфликтов |
| Изменён основной контакт | Обновляются идентификационные поля клиента в WHMCS, потому что основной контакт и есть идентичность клиента |
| Изменён неосновной контакт | Обновляется соответствующий контакт в WHMCS |
| Сотрудник отвечает в зеркалированном тикете | Ответ появляется в тикете WHMCS от имени вашего Ticket Reply Admin, если он задан, иначе от имени сотрудника Perfex |
| Изменён статус тикета | Статус тикета в WHMCS следует за изменением |
Удаление клиента или записи в Perfex не удаляет ничего в WHMCS. Биллинговые записи сохраняются независимо от того, что происходит в CRM. Это сделано намеренно и не настраивается.
Известные особенности, о которых стоит знать заранее
Это задокументированные решения, а не ошибки:
- Тикеты, созданные напрямую в Perfex, остаются в Perfex. Они никогда не создаются в WHMCS, потому что тикету WHMCS нужны учётная запись клиента и отдел поддержки, которых у тикета со стороны CRM может не быть.
- Изменение статуса тикета через полную форму настроек тикета в Perfex не передаётся. Выпадающий список статуса в отдельном тикете, ответы, массовое изменение статусов и автозакрытие синхронизируются корректно.
- Время, учтённое в задаче Perfex по тикету, не передаётся обратно в WHMCS. Задача существует для отчётности в нативных таймшитах Perfex.
- Периодичность повторяющихся счетов не моделируется. Счета WHMCS зеркалируются как обычные разовые счета Perfex.
- Объединение двух клиентов WHMCS не поддерживается. После объединения переназначьте или удалите строки карты для поглощённого клиента.
- Ответ сотрудника Perfex в синхронизированном тикете может привести к двум письмам клиенту, одному от Perfex и одному от WHMCS. Если ваши клиенты работают в клиентском портале WHMCS, отключите шаблон письма
ticket-replyв Perfex в разделе Setup > Email Templates > Tickets.
Где находятся журналы
Этот раздел экономит больше всего времени. Люди по привычке смотрят не туда.
Сторона WHMCS: собственная страница модуля
Перейдите в Addons > Perfex CRM Bridge и прокрутите до раздела Recent activity.
Мост не пишет в журнал активности WHMCS в разделе Utilities > Logs. Его собственная таблица отображается как панель Recent activity на странице модуля, и на стороне WHMCS смотреть нужно только туда.
Таблица показывает последние 50 событий со следующими столбцами:
| Столбец | Значение |
|---|---|
| Time | Когда была записана строка |
| Dir | out для направления WHMCS в Perfex, in для Perfex в WHMCS |
| Event | Например, client.upsert, invoice.upsert, cron.drain |
| Entity | client, contact, invoice, ticket и так далее |
| WHMCS ID | Идентификатор записи в WHMCS |
| Status | Зелёный ok или красный error |
| Message | Результат либо точный текст ошибки |
Прямо над таблицей в строке заголовка показываются счётчики Queue pending и Dead events. Эти два числа - ваша сводка о состоянии: pending должен опускаться до нуля за один-два цикла cron, а dead должен оставаться нулевым.
Сторона Perfex: две панели на странице настро ек
Перейдите в Setup > WHMCS Bridge.
Recent inbound events перечисляет то, что WHMCS отправил в эту установку Perfex, с типом события, идентификатором WHMCS, идентификатором Perfex, с которым он сопоставлен, значком статуса и сообщением. Именно здесь отклонённый запрос отображается строкой auth.rejected, что означает проблему с подписью или меткой времени, почти всегда - несовпадение секрета. Количество отклонённых строк ограничено 10 в минуту, чтобы поток ошибок не заполнил ваш диск.
Outbound queue перечисляет изменения на стороне Perfex, ожидающие отправки в WHMCS, включая:
- счётчики pending и dead в заголовке панели;
- по одной строке на каждое поставленное в очередь изменение с указанием события, сущности, статуса, числа попыток, времени следующей попытки и последней ошибки;
- понятное человеку объяснение вместо необработанной ошибки там, где причина известна. Ответ 403 от WHMCS без лицензии отображается как "Two-way sync requires Pro on the WHMCS side" со ссылкой на обновление тарифа, а не как выгрузка JSON.
Показываются только последние 20 строк. Доставленные строки удаляются сами через 7 дней; строки pending и dead сохраняются.
Какой журнал отвечает на какой вопрос
| Вопрос | Смотреть здесь |
|---|---|
| 📤 Ушло ли моё изменение из WHMCS? | WHMCS: Recent activity, направление out |
| 📥 Принял ли его Perfex? | Perfex: Recent inbound events |
| 🔑 Неверен ли мой общий секрет? | Perfex: строки auth.rejected в Recent inbound events |
| 🔁 Дошло ли моё изменение из Perfex до WHMCS? | Perfex: Outbound queue, затем WHMCS: Recent activity, направление in |
| ⏰ Работает ли cron? | WHMCS: строка контрольного списка Cron delivering |
| 🔇 Почему двусторонняя синхронизация молчит? | Perfex: пане ль WHMCS plan. Если там Free, это и есть ваш ответ |
Мастер переноса данных (Pro)
Живая синхронизация всегда работает только с новой активностью. Если вы устанавливаете мост на давно работающую установку WHMCS, ваши существующие клиенты и счета не появятся в Perfex, пока вы не перенесёте их.
Мастер переноса данных расположен на странице модуля в WHMCS, ниже формы настроек. Он ставит ваши существующие записи в ту же очередь outbox, которую использует живая синхронизация, поэтому они наследуют те же подписи, повторные попытки, задержки и переход в dead-letter.
Области переноса
Отметьте одну или несколько:
| Область | Что ставится в очередь |
|---|---|
| Clients + contacts | Все клиенты в заданном диапазоне. Контакты передаются вместе со своим клиентом автоматически |
| Invoices | Все счета в заданном диапазоне |
| Services + domains | Все услуги и домены в заданном диапазоне, заполняющие вкладку WHMCS в Perfex |
Исторические тикеты не синхронизируются. После запуска моста передаётся только новая активность по тикетам. Это задокументированное ограничение, а не проблема настройки.
Режимы
| Режим | Поведение |
|---|---|
| All history | Все записи в выбранных областях |
| Date range | Только записи, созданные в интервале "с" и "по" в формате YYYY-MM-DD. Н екорректный диапазон, например когда "с" позже, чем "по", отклоняется с понятным сообщением, и ничего не ставится в очередь |
| Only new (not yet synced) | Пропускает уже сопоставленные записи. Этот режим следует использовать при повторных запусках |
Ограничение в 500 сущностей и как продолжить
За один запуск в очередь ставится не более 500 сущностей, поэтому перенос данных на крупной установке не может переполнить очередь или застопорить ваш cron.
При достижении ограничения мастер сообщает об этом. Порядок действий:
- Нажмите Queue Backfill. Информационный баннер сообщит, сколько записей было запланировано, сколько поставлено в очередь, сколько завершилось ошибкой и был ли запуск усечён.
- Наблюдайте, как счётчик Queue pending вверху страницы уменьшается - по cron ли бо по кнопке Run Sync Now.
- Запустите мастер снова в режиме Only new (not yet synced).
- Повторяйте, пока очередной запуск не перестанет находить новые записи.
Риска дублирования нет. Уже сопоставленные записи пропускаются, а событие, данные которого уже совпадают со стороной Perfex, обрабатывается как пустая операция.
Два правила порядка, которые сэкономят вам время
Дочерняя запись, чей родительский клиент ещё не появился в Perfex, получает ответ "not mapped, will retry" и остаётся в очереди, пока не появится родитель. Обычно собственный порядок очереди сам всё улаживает. Но если вы перенесёте только услуги или счета на установке, клиенты которой никогда не синхронизировались, эти события будут повторяться около 40 часов, а затем уйдут в dead-letter.
Либо отметьте Clients + contacts в том же запуске, либо перенесите клиентов первыми.
Счёт в валюте, которая неизвестна Perfex, отклоняется и повторяется, а примерно через 40 часов уходит в dead-letter. Перед переносом счетов добавьте в Perfex все валюты, которые используют ваши клиенты WHMCS, в разделе Setup > Finance > Currencies, указывая точный код ISO.
Исторические оплаченные счета
Перенесённые счета, уже оплаченные в WHMCS, закрываются в Perfex синтетической записью о платеже, поэтому отображаются как Paid, а не как Overdue. Повторный запуск переноса не создаёт дублирующихся платежей.
Повседневная эксплуатация
После настройки делать почти ничего не нужно. Достаточно короткого еженедельного взгляда на страницу модуля в WHMCS:
| На что смотреть | Норма |
|---|---|
| Контрольный список настройки | Всё зелёное, с серым в строке лицензии, если вы на бесплатном тарифе |
| Queue pending | Небольшое значение, уменьшающееся между тактами cron |
| Dead events | 0 |
| Recent activity | Преимущественно строки ok |
| Outbound queue в Perfex | 0 в pending, 0 в dead, на установках с двусторонней синхронизацией Pro |
Если что-то из этого списка не соответствует норме, в разделе Устранение неполадок описаны причина и решение.