設定
このページの内容は、両方のモジュールがインストールおよび有効化済みで、WHMCSのAddons > Perfex CRM BridgeとPerfex CRMのSetup > WHMCS Bridgeにアクセスできることを前提としています。どちらかが見当たらない場合はインストールに戻ってください。WHMCS側でよくある原因は、Access Controlのチェック漏れです。
両側の認証の仕組み
両方のエンドポイントは、共有シークレットから導出したHMAC-SHA256署名によって、すべてのリクエストを認証します。
平易に説明すると、送信側はシークレットでリクエストボディに署名し、タイムスタンプを付与します。受信側は自身が保持するシークレットで署名を再計算し、署名が一致しないもの、またはタイムスタンプが300秒を超えて古いものを拒否します。このタイムスタンプのウィンドウが、後から取得済みのリクエストを再送されることを防ぎます。
その結果として、シークレットは両側でバイト単位まで完全に一致している必要があります。一致しなければ、すべてのリクエストが401で失敗します。また、各エンドポイントは自身のシークレットが空の間はすべての通信を拒否するため、設定が中途半端なブリッジは開いた状態ではなく閉じた状態になります。
両側とも使用前に先頭と末尾の空白を除去するため、コピー＆ペーストの際に紛れ込んだスペースや改行が原因で動作しなくなることはありません。それ以外の部分は完全に一致している必要があります。
共有シークレットは、Perfexの顧客とコンタクトへの書き込み権限を与えます。Proライセンスがある場合は、さらに両側の請求書、支払い、注文、チケットへの書き込み権限も与えます。いずれかのデータベース、またはそのバックアップが流出した可能性がある場合は、直ちに両側でローテーションしてください。シークレットはtbladdonmodules（WHMCS）とtbloptions（Perfex）に平文で保存されます。これは双方のエコシステムにおける標準的な扱いであり、したがってデータベースにアクセスできる人はシークレットを取得できます。
ペアリング: 推奨される簡単な方法
設定を手作業で行き来してコピーする必要はありません。Perfexは、Perfex URLと共有シークレットの両方を含む1つのConnection codeを生成し、WHMCSはそれを1回貼り付けるだけで取り込みます。
ステップ1: Perfexでシークレットを生成する
- Perfex CRMでSetup > WHMCS Bridgeに移動します。
- Shared Secretの横にあるGenerateをクリックします。フィールドに強度の高い64文字のランダムなシークレットが入力され、保存前に内容を確認できるよう表示状態になります。目のアイコンのボタンで表示と非表示を切り替えられます。
- Saveをクリックします。
ステップ2: Connection codeをコピーする
ページが再読み込みされ、読み取り専用のConnection codeフィールドが表示されます。その値はPBC1.で始まる1本の文字列です。
Copyをクリックします。コードがクリップボードに入ると、ボタンに「Copied!」と一瞬表示されます。
このコードはPBC1.に続けて、Perfex URLと共有シークレットを含むJSONをbase64urlでエンコードしたものです。これは暗号化ではなくエンコードです。コードを入手した人は誰でもブリッジのエンドポイントと通信できます。公開のチケット、チャットチャンネル、スクリーンショット、サポート依頼などに貼り付けないでください。
コードが描画されるのは、次の2つの条件を満たした場合だけです。Perfexインストール環境がHTTPSで提供されていること、そして保存済みの共有シークレットが32文字以上であることです。GenerateをクリックしただけでSaveをクリックしていない、というのがよくある原因です。どちらの条件を満たしていないかはページに表示されます。
- 「not served over HTTPS」 - ペアリングにはHTTPSが必要です。手動セットアップをご利用いただくか、証明書を修正してください。
- 「shorter than 32 characters」 - GenerateをクリックしてからSaveをクリックすると、コードが表示されます。
ステップ3: WHMCSへ貼り付け る
- WHMCSでAddons > Perfex CRM Bridgeを開きます。
- ページ上部にある緑色のQuick setupボックスを見つけます。
- フィールドにコードを貼り付けます。
- Connectをクリックします。
Connectが実際に行っていること
1ステップの中で、次の順序で処理されます。
- コードをデコードし、厳密に検証します。
PBC1.プレフィックス、厳格なbase64url、正しい形式のJSONオブジェクト、https://で始まりURLとして妥当なURL、そして32文字以上のシークレットが対象です。 - デコードしたURLとシークレットを使って、Perfexインストール環境へ署名付きのpingを送信し、
pongを待ちます。 - そのpingが成功した場合に限り、WHMCS側にPerfex CRM URLとShared Secretを保存します。
- 初回のペアリングのときのみ、pingにWHMCSのベースURLも含めて送信するため、Perfex側のWHMCS URLフィールドが自動的に入力されます。これはWHMCSがHTTPSで提供されている場合にのみ行われ、既に設定済みの値を上書きするこ とはありません。
- 確認が成功したことを記録するため、同じページ読み込みの中でConnection verifiedのチェックリスト行が緑になります。
成功すると、ペアリング先のPerfex URLを示す緑色のバナーが表示されます。失敗した場合は、何が問題だったのかを正確に説明する赤色のバナーが表示され、何も保存されません。検証に失敗したコードが、現在動作している設定を上書きすることは決してありません。
後から再ペアリングする
WHMCSの設定が完了すると、Quick setupボックスは目立たないRe-pairフォームに変わります。シークレットをローテーションしたときや、Perfexを新しいドメインへ移転したときは、いつでも新しいコードを貼り付けてください。ルールは同じで、検証に失敗したコードは何も変更しません。
Perfex側でGenerateとSaveをクリックすると、新しいコードをWHMCSへ貼り付けるまで、既存のWHMCSからのリクエストは直ちにHTTP 401で失敗し始めます。この2つの手順は続けて実行してください。ローテーション前にコピーした古いコードは拒否され、バナーにはPerfexが401を返したことが表示されます。
ペアリング: 手動での代替手順
Connection codeは利便性のための仕組みであり、特別なことをしているわけではありません。同じ内容はすべて手作業でも設定できます。Perfexインストール環境がまだHTTPSになっていない場合や、認証情報をまとめた文字列の貼り付けが運用ルールで禁止されている場合は、こちらの方法をご利用ください。
- 32文字以上の強度の高いランダムなシークレットを生成します。Perfexの設定ページのGenerateボタン、またはお手持ちのツール（例:
openssl rand -hex 32）をご利用ください。 - Perfex側で、Setup > WHMCS BridgeのShared Secretにそれを貼り付け、Saveをクリックします。
- WHMCS側で、Addons > Perfex CRM Bridgeを開き、Settings > Connectionまでスクロールして次を設定します。
- Perfex CRM URLにPerfexのベースURLを設定します（例:
https://crm.example.com）。HTTPSで、末尾にパスを含めないでください。 - 同じシークレットをShared Secretに貼り付けます。
- Perfex CRM URLにPerfexのベースURLを設定します（例:
- Save Settingsをクリックします。
- ページ上部のTest Connectionをクリックします。緑色の「Connection OK」バナーが表示されれば成功です。
- Proの双方向同期を利用する場合は、Perfexの設定ページでWHMCS URLも設定します。ペアリングを利用していれば自動的に入力される項目です。
WHMCSの設定（セクション別）
Addons > Perfex CRM Bridgeを開き、Settingsまでスクロールしてください。System Settings > Addon Modules 配下のWHMCSのConfigure画面は確認しないでください。あの画面に残されているのはAccess Controlだけで、これはWHMCSのコアが描画しており移動できません。
Save Settingsをクリックすると適用されます。このフォームはオールオアナッシングです。たとえばHTTPSでないURLのように不正な入力が1つでもあると、送信全体が拒否され、何も変更されません。
Shared SecretとPro License Keyは常に空の状態で描画されます。保存済みの認証情報が、モジュールを開ける管理者全員のページソースに残ることがないようにするためです。現在の値を維持したい場合は、その欄を空のままにしてください。値を置き換えたい場合は入力します。Proキーを完全に削除するには、Remove the stored keyにチェックを入れてください。
Connection
| 設定項目 | 内容 | 推奨される初期値 |
|---|---|---|
| Perfex CRM URL | Perfexインストール環境のベースURLです（例: 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のリードを1件作成します。noteは代わりにPerfexの顧客にメモを追加します。offは注文をまったく同期しません。 | lead |
| Two-Way Conflict Policy (Pro) | 前回の同期以降に両方のシステムで同じクライアントまたはコンタクトが変更された場合に、どちらを優先するかを決めます。詳細は以下をご覧ください。 | newest_wins |
競合ポリシーの選択肢（各1行での説明）:
newest_wins（既定） - 受信したPerfexイベントの時刻と最終同期時刻を比較し、より新しい編集を優先します。whmcs_wins- WHMCSのデータを維持し、競合するPerfex側の編集を破棄します。perfex_wins- Perfex側の編集をWHMCSのデータに上書き適用します。
このポリシーが適用されるのは、前回の同期成功以降に両側が同じレコードを変更した場合のみです。一方だけで編集し、もう一方に変更がない通常のケースでは、常にその編集が適用されます。どちらのシステムが全般的に「優先される」かを選んでいるのではなく、引き分けの解消方法だけを選んでいます。
newest_winsとサーバーの時刻について「より新しい」の判定は、送信側サーバーのタイムスタンプと受信側サーバーの最終同期時刻を比較して行うため、2台のホストの時刻が重要になります。両方のサーバーをNTPで同期させてください。WHMCSホストとPerfexホストの時刻のずれを管理できない場合は、決定論的に動作するwhmcs_winsまたはperfex_winsをお選びください。
Tickets
| 設定項目 | 内容 | 推奨される初期値 |
|---|---|---|
| Ticket Reply Admin (Pro) | Perfexのスタッフによる返信をWHMCSのチケットへ同期する際に使用するWHMCS管理者のユーザー名です。空のままにすると、代わりにPerfexのスタッフ名で返信が記録され、管理者以外の返信として投稿されます。 | 空 |
Pro licence
| 設定項目 | 内容 | 推奨される初期値 |
|---|---|---|
| Pro License Key | Freeプランの場合は空のままにします。Pro機能を有効にするには、ここにProキーを貼り付けます。キーはsk_で始まります。変更されたキーを保存すると、その場で即座にライブ検証が実行されます。 | 空（Free） |
| Remove the stored key | キーが保存されている場合にのみ表示されるチェックボックスです。チェッ クを入れて保存すると、環境がFreeに戻り、さらにこのサイトの有効化スロットが解放されるため、ライセンスを別の環境で利用できるようになります。 | チェックなし |
| Check licence now（ページ上部のボタン） | 1日1回の実行制限を無視して、保存済みのキーを直ちに再確認します。 | - |
| Upgrade to Pro / Buy a Pro licence（リンク） | チェックアウトを開きます。Pro以外の環境では、キー入力欄の横、ライセンスのチェックリスト行、Proの案内ボックスに表示されます。 | - |
詳細はライセンスとProの有効化をご覧ください。
Order Sync Target、Two-Way Conflict Policy、Ticket Reply Adminは、いずれもFree環境で問題なく保存できます。有効なライセンスがアクティブになるまで効果が出ないだけで、その旨が各フィールドの下に表示されます。あらかじめ設定しておいても構いません。
Perfex CRMの設定（フィールド別）
Perfexの管理画面でSetup > WHMCS Bridgeを開き、設定後にSaveをクリックします。
Connection
| フィールド | 内容 | 既定値 / フォールバック |
|---|---|---|
| Shared Secret | WHMCS側のShared Secretと一致している必要があります。強度の高い値を得るにはGenerateを使い、その後Saveをクリックします。目のアイコンのボタンで表示と非表示を切り替えられます。この値が空の間、エンドポイントはすべての通信を拒否します。 | 空。エンドポイントは閉じた状態 |
| Connection code | 読み取り専用です。保存済みのシークレットが32文字以上で、PerfexがHTTPSで提供されている場合に表示されます。WHMCSのQuick setupボックスへコピーしてください。 | 自動的に描画されます |
| WHMCS URL | アドオンが動作しているWHMCSインストール環境のベースURLです。PerfexからWHMCSへの通信にのみ必要で、これはPro機能です。https://で始まらない場合は保存されません。 | 初回ペアリング時に自動入力。設定後に上書きされること はありません |
Ticket sync（Pro）
| フィールド | 内容 | 既定値 / フォールバック |
|---|---|---|
| Department mapping (WHMCS to Perfex) | WHMCSの各チケット部門をPerfexの部門に対応付けます。部門一覧を取得できる場合はWHMCSの部門ごとに1つのドロップダウンとして、取得できない場合は手動入力のテキストエリアとして描画されます。 | 空。いずれも未マッピング |
| Default department for unmapped WHMCS tickets | マッピングに存在しない部門のWHMCSチケットに使用するPerfexの部門です。 | 「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の部門ごとに1行ずつ、Perfexの部門を選ぶドロップダウンとともに描画します。各行で対応先を選ぶか、- not mapped -のままにして、Saveをクリックします。
この取得処理には、正常な接続とProライセンスが有効なWHMCSの両方が必要です。部門一覧は、チケット同期と同じライセンスの制限下にあるためです。実行できない場合、ページは自動的に手動入力のテキストエリアへフォールバックし、その理由を表示します。
| 表示される内容 | 意味 |
|---|---|
| WHMCSの部門ごとに1つのドロップダウン | すべて正常に動作しています |
| テキストエリアと「Couldn't fetch WHMCS departments (needs Pro + working connection)」 | ブリッジが未設定である、PerfexサーバーからWHMCSに到達できない、またはWHMCS環境がFreeプランです |
| テキストエリアと「Connection OK, but WHMCS has no support departments yet」 | 取得は成功しています。WHMCSのSupport > Support Departmentsで部門を作成してから、このページを再読み込みしてください |
取得処理には数秒の上限が設けられているため、WHMCSに到達できない場合でも設定ページの表示が少し遅くなるだけで、固まることはありません。
手動入力の書式は1行につき1つのマッピングで、左にWHMCSの部門ID、右にPerfexの部門IDを記述します。
1=2
2=5
3=5
ドロップダウンが表示されている状態でも、Advanced: edit the mapping manuallyのリンクから同じテキストエリアを開けます。この手動エディターが開いている間は、そのテキストの内容が保存され、ドロップダウンの選択内容よりも優先されます。
受信したチケットの部門を決める解決順序は次のとおりです。
- マッピング内の完全一致。
- 一致がなければ、設定済みのDefault department。
- それもなければ、自動的に選ばれるPerfexの最小の部門ID。
マッピングの行に入力ミスがあっても、フォールバックへ穏やかに移行します。保存が失敗することも、同期が止まることもありません。
このオプションのPerfexタスクは、スタッフがチケットに 対してPerfexのネイティブなタイムシートを利用できるようにするためのものです。記録された工数はWHMCSへは同期されず、チケットがクローズされてもタスクは自動的にクローズされません。
同じページ上のパネル
Setup > WHMCS Bridgeの右側の列には、読み取り専用のパネルが3つあります。
- WHMCS plan - WHMCS側が最後に報告したプラン（Pro、Free、Unknown）、ライセンスの最終確認時刻、購入可能な場合はUpgrade to Proボタンが表示されます。
- Outbound queue - WHMCSへ送信待ちのPerfex側の変更です。保留件数とデッド件数、再試行回数、次回試行時刻、行ごとの直近のエラーが表示されます。
- Recent inbound events - WHMCSがこのPerfex環境へ送信した内容が、ステータスとメッセージとともに表示されます。
これらがPerfex側の診断情報です。仕組みと日常運用をご覧ください。
セットアップチェックリストの各行について
WHMCSのモジュールページは、6行のセットアップチェックリストから始まります。各行には緑のチェック、黄色の警告、赤のバツ、グレーのダッシュのいずれかと、1行のヒントが表示されます。Freeプランの場合にライセンス行がグレーであることを除き、すべて緑であればブリッジは正常です。
| 行 | 緑の意味 | それ以外の意味 |
|---|---|---|
| Module tables present | アウトボックス、マップ、ログの各テーブルがすべて存在します。 | 🔴 赤: テーブルが不足しています。System Settings > Addon Modules でモジュールを無効化してから再度有効化すると、再作成されます。 |
| Connection configured | Perfex URLと共有シークレットの両方が設定されています。 | 🔴 赤: まだ未設定です。Quick setupにConnection codeを貼り付けるか、Settings > Connection で両方のフィールドを入力してください。 |
| Connection verified | 署名付きのpingに対してpongが返り、どれくらい前の確認かが表示されます。 | 🔴 赤: 直近の確認が失敗しており、行にエラーが表示されます。修正してからTest Connectionをクリックしてください。⚪ グレー: 未確認、または直近の確認から24時間以上経過しています。Test Connectionをクリックして更新してください。 |
| Sync enabled | 送信配信が有効です。 | 🔴 赤: 同期が一時停止しています。イベントはキューに入り続けますが配信されません。Settings > Sync behaviour でEnable Syncにチェックを 入れて保存してください。 |
| Cron delivering | WHMCSのシステムcronが最近、実際にブリッジの処理を実行しました。どれくらい前かが表示されます。 | 🟠 黄: しばらくcronの動作がありません。WHMCSのシステムcronが稼働しているか確認してください。🔴 赤: cronの動作が一度も記録されていません。新規インストール直後であれば最初の配信までは正常な状態です。それが続く場合は、cronが稼働していません。 |
| License / plan | Proが有効です。 | ⚪ グレー: ライセンスキーがありません。これはFreeプランであり、このモジュールの正式にサポートされた運用形態です。🔴 赤: キーは設定されていますが検証に通りません。キーを確認してからCheck licence nowをクリックしてください。 |
この行を緑にできるのは、本物のWHMCSシステムcronの実行だけです。Run Sync Nowはキューに入ったイベントを配信し、配信が機能することを証明しますが、この行には影響しません。それが狙いです。この行は「誰も見ていないときにも動き 続けるか」という問いに答えるものであり、ボタンを押すことではその問いに答えられないからです。
この行が追跡しているのは実際のブリッジの処理です。キューの処理、ログの整理、突き合わせの実行などが該当します。したがって、長く待機状態にある完全に健全な環境が、単に処理すべきことがなかったという理由で黄色のまま、修正すべき点もない状態になることがあります。
Connect（ペアリング）とTest Connectionは、どちらもConnection verifiedの行を更新します。
次に読むページ
- パイプラインを端から端まで検証する: インストールのステップ5。
- 双方向同期、請求書、チケットを有効にする: ライセンスとProの有効化。
- 何がどこへ同期され、ログがどこにあるかを理解する: 仕組みと日常運用。