仕組みと日常運用
ブリッジのペアリングが完了して同期が有効になると、あとは自動的に動作します。このページでは、実際に何が行われているのかを説明します。何かおかしいと感じたときに、当てずっぽうではなく、どこを見ればよいかがわかるようになります。
同期エンジンをわかりやすく解説
1. 変更がイベントを発生させる
WHMCS内の関連するすべての変更は、WHMCSのフックを発火させます。クライアントの追加や編集、コンタクトの作成、請求書の確定、支払いの着金、注文の発生、サービスのプロビジョニングや一時停止、チケットの起票や返信などが該当します。
フックはHTTP通信を行いません。小さなイベントをアウトボックステーブル（mod_perfexbridge_outbox）へ書き込み、即座に処理を返します。
WHMCSのフックがPerfexを直接呼び出していた場合、Perfexサーバーの応答が遅かったり到達できなかったりすると、WHMCSの管理ページや顧客のチェックアウトがブロックされてしまいます。ローカルのテーブルへの書き込みは1ミリ秒で完了し、他者のネットワーク事情で失敗することはありません。それ以降の処理はすべてバックグラウンドで行われます。
2. cronがキューを処理する
WHMCSのシステムcronが実行されるたびに、ディスパッチャーはアウトボックスから処理対象のイベントをバッチで取り出し、それぞれをHTTPSでPerfexインストール環境へPOSTします。
各リクエストは、JSONボディに加えて2つのヘッダーを持ちます。タイムスタンプと、そのタイムスタンプおよびリクエストボディそのものに対して共有シークレットで計算したHMAC-SHA256署名です。Perfexは自身が保持するシークレットで署名を再計算し、一致しないもの、またはタイムスタンプが300秒を超えて古いものを拒否します。
WHMCSのモジュールページのRun Sync Nowを使えば、いつでも即座にキューの処理を実行できます。
3. 失敗は再試行され、その後デッドレターになる
送信に失敗したイベントは失われませんし、短い間隔で再試行され続けることもありません。指数バックオフでスケジュールし直されます。最初の失敗からおよそ60秒後、次は2分後、4分、8分と延びていき、試行間隔の上限は6時間です。
15回の試行 後、期間にしておよそ40時間が経過すると、その行はdeadとしてマークされます。dead状態の行が自動的に再試行されることはなく、自動削除されることもありません。これがデッドレターの保管場所です。WHMCSのモジュールページ上部のDead eventsカウンターが件数を示し、ログの行がその理由を示します。
デッドレターになったということは、同じイベントが同じ理由でほぼ2日間失敗し続けたということです。原因はほぼ必ず次の4つのいずれかです。Perfexに通貨が登録されていない、シークレットが一致していない、FreeプランがProのイベントをブロックしている、Perfexがオフラインである、のいずれかです。原因を解消してから、その処理を再度キューに入れてください。トラブルシューティングをご覧ください。
4. 一時停止しても何も失われない
Enable Syncのチェックを外すと、一時停止するのは配信だけです。フックはアウトボックスへイベントを書き込み続けるため、停止中も失われるものはありません。再度有効にすると、次の実行タイミングで滞留分が処理されます。Run Sync Nowを使えば即座に処理できます。
5. エコー抑止が無限ループを防ぐ
双方向同期には明白な危険が伴います。WHMCSがPerfex由来の変更を適用すると、その書き込みがWHMCS自身のフックを発火させ、変更がそのまま戻ってしまうという問題です。何も対策しなければ、1件の編集が永遠に往復し続けます。
ブリッジは、両側で適用される多層的なガードによってこれを防いでいます。
- リクエスト内の発生元フラグ。 ブリッジが受信した変更を適用している間に設定され、ブリッジ自身による書き込みが新しいユーザー編集として扱われないようにします。
- エンティティおよび返信IDのマップ参照。 ブリッジが作成したばかりのチケット返信を正しく認識し、新規として再送しないようにします。
- チェッ クサムの比較。 データが最後に同期された状態と既に一致している場合、そのイベントを何もしない処理へと変えます。
各側が独自の発生元フラグを持ち、フラグが何らかの理由で機能しなかった場合の最後の砦としてチェックサムが働きます。これらのガードは意図的にフェイルオープンで設計されています。判断がつかない場合は、更新が黙って失われるよりも、無害な送信が1回余分に行われるほうを選びます。
6. ハウスキーピング
両側とも、24時間に1回を上限とする自己制御型の日次クリーンアップを実行します。
- 配信済みのアウトボックスの行は、7日を過ぎたものが削除されます。
- ログの行は、90日を過ぎたものが削除されます。
- pendingとdeadの行は削除されません。 pendingは未配信の処理であり、deadはデッドレターの保管場所だからです。
何がどの方向へ同期されるか
WHMCSからPerfex CRMへ
| データ | Free | Pro | Perfexに作成されるもの |
|---|---|---|---|
| 👥 クライアント | ✅ | ✅ | Perfexの顧客と、クライアントの氏名とメールアドレスを持つ主担当コンタクト |
| 👤 コンタクト | ✅ | ✅ | 同じPerfex顧客配下の追加コンタクト |
| 🗑️ クライアントの削除 | ✅ | ✅ | Perfexの顧客は削除されず、無効化されます |
| 📄 請求書 | ➖ | ✅ | 明細、税行、一致する合計金額、ステータス、管理メモ内のWHMCS請求書番号を持つPerfexの請求書 |
| 💳 支払いとトランザクション | ➖ | ✅ | ミラーされた請求書に対する支払い記録。ゲートウェイとトランザクションIDを含みます。重複は拒否されます |
| 💸 返金 | ➖ | ✅ | Perfex側のミラーがキャンセルされ、注記が追加されます |
| 🛒 注文 | ➖ | ✅ | Order Sync Targetの設定に応じて、注文ごとのPerfexリード、顧客へのメモ、または同期なし |
| 📦 サービス | ➖ | ✅ | 顧客のWHMCSタブの行。製品名、ドメイン、ステータス、請求サイクル、金 額、次回請求日 |
| 🌐 ドメイン | ➖ | ✅ | 同じタブの行。レジストラ、ステータス、有効期限、次回請求日 |
| 🎫 チケットと返信 | ➖ | ✅ | 顧客配下のPerfexチケット。マッピングされた部門に、返信とステータスとともに作成されます |
Freeプランでは、クライアントのステータスとメモはペイロードに含まれて送信されますが、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請求書としてミラーされます。
- 2件のWHMCSクライアントの統合には対応していません。 統合後は、吸収された側のクライアントのマップ行を貼り替えるか削除してください。
- 同期されたチケットへのPerfexスタッフの返信により、顧客宛のメールが2通送信されることがあります。 Perfexからの1通とWHMCSからの1通です。顧客がWHMCSのクライアントポータルを利用している場合は、PerfexのSetup > Email Templates > Ticketsで
ticket-replyのメールテンプレートを無効にしてください。
ログの場所
ここが最も時間の節約につながるセ クションです。多くの方が習慣的に間違った場所を探してしまいます。
WHMCS側: モジュール自身のページ
Addons > Perfex CRM Bridgeへ移動し、Recent activityまでスクロールします。
ブリッジは Utilities > Logs 配下のWHMCSのActivity Logには書き込みません。ブリッジ独自のテーブルが、モジュールページのRecent activityパネルとして描画されます。WHMCS側で確認する場所はここだけです。
このテーブルには直近50件のイベントが、次の列とともに表示されます。
| 列 | 意味 |
|---|---|
| Time | その行が書き込まれた日時 |
| Dir | WHMCSからPerfexへはout、PerfexからWHMCSへはin |
| Event | 例: client.upsert 、invoice.upsert、cron.drain |
| Entity | client、contact、invoice、ticketなど |
| WHMCS ID | そのレコードのWHMCS上のID |
| Status | 緑のok、または赤のerror |
| Message | 処理結果、またはエラーの本文 |
そのすぐ上のヘッダー行には、Queue pendingとDead eventsの件数が表示されます。この2つの数値が健全性のサマリーです。pendingはcronの1〜2サイクル以内にゼロまで減るはずで、deadはゼロのままであるべきです。
Perfex側: 設定ページ上の2つのパネル
Setup > WHMCS Bridgeへ移動します。
Recent inbound eventsには、WHMCSがこのPerfex環境へ送信した内容が、イベント種別、WHMCSのID、対応付けられたPerfexのID、ステータスバッジ、メッセージとともに一覧表示されます。拒否されたリクエストがauth.rejectedの行として現れるのもここです。これは署名またはタイムスタンプの問題を意味し、ほぼ必ずシークレットの不一致が原因です。拒否された行は1分あたり10件を上限として記録されるため、大量に発生してもディスクを埋め尽くすことはありません。
Outbound queueには、WHMCSへ送信待ちのPerfex側の変更が、次の情報とともに一覧表示されます。
- パネルの見出しにあるpendingとdeadの件数。
- キューに入った変更ごとに1行で、イベント、エンティティ、ステータス、試行回数、次回試行時刻、直近のエラーを表示。
- 原因が判明している場合は、生のエラーの代わりにわかりやすい説明を表示。ライセンスのないWHMCSからの403は、JSONのダンプではなく「Two-way sync requires Pro on the WHMCS side」という文言とアップグレードのリンクとして表示されます。
表示されるのは最新の20行のみです。配信済みの行は7日後に自動的に消え、pendingとdeadの行は保持されます。
どのログがどの疑問に答えるか
| 疑問 | 確認する場所 |
|---|---|
| 📤 WHMCSでの変更はWHMCSから送信されたか | WHMCS: Recent activityのout方向 |
| 📥 Perfexはそれを受け入れたか | Perfex: Recent inbound events |
| 🔑 共有シークレットが間違っていないか | Perfex: Recent inbound eventsのauth.rejectedの行 |
| 🔁 Perfexでの編集はWHMCSに届いたか | Perfex: Outbound queue、続いてWHMCS: Recent activityのin方向 |
| ⏰ cronは動作しているか | WHMCS: Cron deliveringのチェックリスト行 |
| 🔇 双方向同期が動かないのはなぜか | Perfex: WHMCS planパネル。Freeと表示されていれば、それが答えです |
バックフィルウィザード（Pro）
ライブ同期が扱うのは、あくまで新規のアクティビティだけです。すでに運用中のWHMCS環境にブリッジを導入した場合、既存のクライアントや請求書は、バックフィルを実行するまでPerfexに存在しません。
バックフィルウィザードは、WHMCSのモジュールページの設定フォームの下にあります。既存のレコードを、ライブ同期が使うのと同じアウトボックスへキューイングするため、署名、再試行、バックオフ、デッドレターの仕組みをそのまま引き継ぎます。
対象範囲
1つ以上にチェックを入れてください。
| 対象範囲 | キューに入るもの |
|---|---|
| Clients + contacts | 範囲内のすべてのクライアント。コンタクトはクライアントに付随して自動的に処理されます |
| Invoices | 範囲内のすべての請求書 |
| Services + domains | 範囲内のすべてのサービスとドメイン。PerfexのWHMCSタブに反映されます |
過去のチケットは同期されません。ブリッジの稼働後に発生した新しいチケットのアクティビティのみが連携されます。これは設定の問題ではなく、仕様として明記された制限です。
モード
| モード | 挙動 |
|---|---|
| All history | 選択した対象範囲のすべてのレコード |
| Date range | YYYY-MM-DD形式の開始日と終了日の範囲内に作成されたレコードのみ。開始日が終了日より後になっているなど範囲が不正な場合は、明確なメッセージとともに拒否され、何もキューに入りません |
| Only new (not yet synced) | すでにマッピング済みのレコードをスキップします。繰り返し実行する際はこのモードをご利用ください |
500エンティティの上限と再開の方法
1回の実行でキューに入るのは最大500エンティティです。これにより、大規模環境でのバックフィルがキューを溢れさせたり、cronを停滞させたりすることを防ぎます。
上限に達すると、ウィザードがその旨を通知します。手順は次のとおりです。
- Queue Backfillをクリックします。情報バナーに、対象として計画された件数、キューに入った件数、エラーになった件数、そして実行が途中で打ち切られたかどうかが表示されます。
- ページ上部のQueue pendingカウンターが減っていく様子を確認します。cronに任せても、Run Sync Nowを使っても構いません。
- **Only new (not yet synced)**モードでウィザードを再実行します。
- 新たに対象となるものがなくなるまで繰り返します。
重複が発生する心配はありません。マッピング済みのレコードはスキップされ、データが既にPerfex側と一致しているイベントは、何もしない処理として応答されます。
時間を節約する2つの順序のルール
親となるクライアントがまだPerfexに存在しない子レコードは「not mapped, will retry」と応答され、親が登録されるまでキューに残ります。通常はキュー自体の順序で解決されます。ただし、クライアントを一度も同期していない環境でサービスや請求書だけをバックフィルした場合、それらのイベントはおよそ40時間再試行された後、デッドレターになります。
同じ実行でClients + contactsにもチェックを入れるか、先にクライアントをバックフィルしてください。
Perfexが認識していない通貨の請求書は拒否されて再試行され、およそ40時間後にデッドレターになります。請求書をバックフィルする前に、WHMCSのクライアントが使用するすべての通貨を、正確なISOコードでPerfexのSetup > Finance > Currenciesに追加してください。
過去の支払い済み請求書について
WHMCSですでに支払い済みだった請求書をバックフィルすると、Perfex側では擬似的な支払い記録によって消し込まれるため、OverdueではなくPaidとして表示されます。バックフィルを再実行しても、支払いが重複して作成されることはありません。
日常の運用
セットアップが完了すれば、行うべきことはほとんどありません。週に一度、WHMCSのモジュールページを短時間確認すれば十分です。
| 確認する項目 | 正常な状態 |
|---|---|
| セットアップチェックリスト | すべて緑。Freeで運用している場合はライセンス行のみグレー |
| Queue pending | 少なく、cronの実行ごとに減っている |
| Dead events | 0 |
| Recent activity | ほとんどがokの行 |
| PerfexのOutbound queue | Proの双方向同期環境では、pendingが0、deadが0 |
このいずれかに問題がある場合は、トラブルシューティングに原因と対処方法が記載されています。