インストール
このページでは、Perfex CRM Integration for WHMCSの2つのコンポーネントをインストールします。記載の順序どおりに進めてください。作業はブラウザーのタブ2つと、ホスティングパネルのファイルマネージャーだけで完了します。SSHもコマンドラインも不要です。
upload.zipを展開して、次の2つのファイルが手元にある状態にしてください。
| ファイル | インストール先 |
|---|---|
🧩 perfex-module/module.zip | Perfex CRM |
⚙️ whmcs-addon/addon.zip | WHMCS |
クイックインストール（短縮版）
ホスティングの運用に慣れている方であれば、作業全体はわずか5つの操作です。次の順序で行ってください。
- 🧩 まずPerfex。 Perfex CRMでSetup > Modules > Upload Moduleを開き、
module.zipをアップロードしてActivateします。Perfex側を先にインストールしておけば、WHMCSが何かを送信する前に受信用エンドポイントが用意されます。 - ⚙️ WHMCSアドオン。
addon.zipをmodules/addons/にアップロードして展開し、最終的にmodules/addons/perfexbridge/perfexbridge.phpとなる状態にします。続いてSystem Settings > Addon ModulesでPerfex CRM Bridgeを有効化します。 - 🔓 Access Controlにチェックを入れる。 アドオンのConfigure画面でFull Administrator（および、このモジュールを使用する他のロール）にチェックを入れ、Save Changesをクリックします。これを行わないとモジュールは表示されず、Addonsメニューにまったく現れません。
- 🔗 両側をペアリングする。 Addons > Perfex CRM Bridgeを開き、PerfexからコピーしたConnection codeをQuick setupボックスに貼り付けて、Connectをクリックします。詳細は設定にあります。
- ✅ 検証する。 WHMCSでテスト用クライアントを作成し、Run Sync Nowをクリックして、PerfexのCustomersに表示されることを確認します。
すべてのクリック操作、チェックリストの各行、そして端から端までの完全な検証手順は、以下の詳細な手順に記載されています。
詳細な手順
先にPerfex側のコンパニオンをインストールしてください。こちらが受信用エンドポイントを作成します。WHMCSアドオンを先にインストールして同期を開始すると、Perfex側が存在するまですべてのイベントが失敗し、まだ発生する必要のなかった問題のエラーログを読む時間を費やすことになります。
ステップ1: Perfex CRM側のコンパニオンをインストールする
Perfex側のコンパニオンは無償で、ライセンスキーを持たず、すべてPerfexの管理画面から導入できます。
- AdministratorとしてPerfex CRMにログインします。
- Setup > Modulesに移動します。
- Upload Moduleボタンをクリックします。
- ファイル選択ダイアログで
module.zipを選び、アップロードします。 - PerfexはこのモジュールをWHMCS Bridgeとして一覧に表示します。プロンプトが出たらInstallをクリックし、続いてActivateをクリックします。
Upload ModuleボタンはPHP経由でzipを送信するため、サーバーのupload_max_filesizeとpost_max_sizeの両方がファイ ルサイズより大きい必要があります。アップロードに失敗する場合は、PHP設定でこれらの上限を引き上げるか、以下の手動インストールをご利用ください。
手動での代替手順: お使いのコンピューター上でmodule.zipを展開し、生成されたwhmcs_bridgeフォルダーをFTPまたはホスティングパネルのファイルマネージャーでPerfexインストール環境のmodules/ディレクトリへアップロードします。最終的にmodules/whmcs_bridge/whmcs_bridge.phpとなる必要があります。その後Setup > Modulesに戻り、Activateをクリックします。
Perfex側が正しくインストールされたことの確認
- PerfexのSetupメニューにWHMCS Bridgeという新しい項目が表示されます。次の章で共有シークレットを生成するのは、このページです。
ステップ2: WHMCSアドオンをインストールする
WHMCSには管理画面内のモジ ュールインストーラーがありません。ファイルをご自身でディスク上に配置し、その後で管理画面から有効化します。ホスティングパネルのファイルマネージャーだけで作業は完結します。
- ホスティングパネルのファイルマネージャーを開き、WHMCSインストール環境の
modules/addons/ディレクトリへ移動します。 addon.zipをmodules/addons/へアップロードします。- ファイルマネージャーのExtract機能でアップロードしたファイルを展開します。展開先は同じ
modules/addons/ディレクトリです。 - 結果が
modules/addons/perfexbridge/perfexbridge.phpになっていることを確認します。modules/addons/perfexbridge/perfexbridge/perfexbridge.phpのようになっている場合は、展開時に階層が1つ深くなっています。内側のフォルダーを1階層上へ移動し、空になったフォルダーを削除してください。 - 展開が成功したら、アップロードした
addon.zipをサーバーから削除します。
先にお使いのコンピューター上でaddon.zipを展開し、生成されたperfexbridgeフォルダーをFTPでmodules/addons/へアップロードします。最終的な状態は同じです。
続いて有効化します。
- WHMCSでSystem Settings > Addon Modulesに移動します。
- 一覧からPerfex CRM Bridgeを見つけ、Activateをクリックします。
ステップ3: Access Controlにチェックを入れる（入れないとモジュールは表示されません）
有効化後、WHMCSはモジュールの設定パネルを表示します。その中に、管理者ロールの一覧を含むAccess Controlセクションがあります。少なくともFull Administratorと、このモジュールを使用する他のロールにチェックを入れ、Save Changesをクリックする必要があります。
いずれのロールにもチェックが入っていない間、モジュールは左側のAddonsメニューにまったく表示されません。モジュール自体はインストール済みで、テーブルも存在し、設定ページも問題なく動作していますが、管理画面のどこにもリンクがない状態です。「モジュールがインストールされない」という報告の10件中9件は、このチェックボックスが未設定であることが原因です。
具体的な手順は次のとおりです。
- System Settings > Addon Modulesを開いたまま、Perfex CRM Bridgeの横にあるConfigureをクリックします。通常、WHMCSは有効化の直後にこのパネルを自動的に開きます。
- Access ControlでFull Administratorにチェックを入れます。ブリッジを開いて設定できるようにしたい他の管理者ロールにもチェックを入れてください。
- Save Changesをクリックします。
- 管理画面を再読み込みします。AddonsメニューにPerfex CRM Bridgeが表示されます。
このモジュールの実際の設定はすべて、モジュール自身のページ（Addons > Perfex CRM Bridge）にあり、WHMCSのConfigure画面にはありません。Configure画面に残されているのはAccess Controlのみです。これはWHMCSのコアが描画する部分であり、移動できないためです。Perfex URLやライセンスキーを探してConfigureを開いているのであれば、画面を間違えています。設定をご覧ください。
ステップ4: モジュールページを開く
Addons > Perfex CRM Bridgeに移動します。
ページはセットアップチェックリストから始まります。インストール直後の状態は次のようになります。
| チェックリストの行 | この時点で想定される状態 |
|---|---|
| Module tables present | 🟢 緑のチェック |
| Connection configured | 🔴 赤のバツ。まだペアリングされていません |
| Connection verified | ⚪ グレーのダッシュ。未確認です |
| Sync enabled | 🔴 Enable Syncにチェックを入れるまで赤のバツ |
| Cron delivering | 🔴 赤のバツ。cron の動作がまだ記録されていません |
| License / plan | ⚪ グレーのダッシュ。Freeプランです |
インストール直後で未設定のブリッジとしては、これが正しい状態です。各行の説明は設定にあります。
次は両側をペアリングします。設定へ進んでください。
ステップ5: 最初の同期を端から端まで検証する
ペアリング直後に一度だけ、実データをブリッジに任せる前にこの作業を行ってください。所要時間は2分ほどで、パイプライン全体が正しく動作することを確認できます。
- 設定に記載されたペアリングを完了します。チェックリストのConnection configuredとConnection verifiedの両方が緑になっている必要があります。
- 同じページのSettings > Sync behaviourでEnable Syncにチェックが入っていることを確認し、Save Settingsをクリックします。Sync enabledの行が緑になります。
- WHMCSでテスト用クライアントを作成します。名前とメールアドレスは何でも構いません。たとえば会社名を
Bridge Test Ltdと します。 - Addons > Perfex CRM Bridgeに戻ります。ページ上部のQueue pendingカウンターが1以上になっているはずです。
- Run Sync Nowをクリックします。cronを待たずに、その場で配信を試みます。ページには送信件数、失敗件数、デッドレター件数が表示されます。
- Perfex CRMでCustomersを開きます。テスト用クライアントが顧客として作成され、WHMCSクライアントの名前とメールアドレスが主担当コンタクトとして登録されています。
- 両側のログに記録されていることを確認します。
- WHMCS側: モジュールページの下部にあるRecent activityテーブルに、ステータス
okのclient.upsert行が表示されます。 - Perfex側: Setup > WHMCS BridgeのRecent inbound eventsパネルに、緑の
okバッジが付いた対応するclient.upsert行が表示されます。
- WHMCS側: モジュールページの下部にあるRecent activityテーブルに、ステータス
- 残しておく必要がなければ、テスト用クライアントを両システムから削除します。
Run Sync Nowが証明するのは配信が機能することだけです。Cron deliveringのチェックリスト行は緑になりません。この行は、実際のWHMCSシステムcronの動作を意図的に追跡しているためです。1時間経ってもこの行が赤または黄のままであれば、WHMCSのシステムcronが動作しておらず、自動的には何も同期されません。本番運用に入る前にcronを修正してください。トラブルシューティングをご覧ください。
新しいバージョンへの更新
両方のモジュールは同じバージョンを持ち、常に一緒に更新してください。
Perfex側。 Setup > Modules > Upload Moduleから新しいmodule.zipをアップロードして既存のモジュールを上書きし、その後いずれかの管理ページを読み込みます。コンパニオンはデータベースのバージョンが古いことを検知し、その場で独自のマイグレーションを適用します。お好みで、モジュールを無効化してから再度有効化しても構いません。どちらの方法も安全です。すべてのマイグレーション文にはガードが入っており、再実行しても既に正しい状態のものは変更されません。
WHMCS側。 新しいaddon.zipをmodules/addons/perfexbridge/に上書きアップロードして展開します。WHMCSは新しいバージョン番号を検知すると、モジュールのアッ プグレード処理を実行します。うまくいかない場合は、System Settings > Addon Modulesでアドオンを無効化してから再度有効化してください。
設定、共有シークレット、ライセンスキー、エンティティマップ、ログはすべてデータベースのテーブルに保存されており、アップグレードで削除されることはありません。WHMCSアドオンを無効化してもデータは削除されません。
アンインストール
- WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivateを実行し、その後ディスクから
modules/addons/perfexbridge/を削除します。 - Perfex: Setup > ModulesでWHMCS Bridgeを無効化し、モジュールを削除します。
- データも完全に削除したい場合は、各システムでモジュールのデータベーステーブルをドロップします（事前にバックアップを取得してください）。
- Proライセンスが有効だった場合は、アンインストールする前にキーを削除してください。有効化スロットが解放され、ライセンスを別の環境で再利用できます。ライセンスとProの有効化をご覧ください。