トラブルシューティング

このページは記載の順序どおりに確認していってください。最初の3つのセクションで、お問い合わせの大半をカバーしています。

まず何よりも先に、WHMCSでAddons > Perfex CRM Bridgeを開き、セットアップチェックリストをご確認ください。問題箇所を直接指し示すよう設計されており、各行の説明は設定にあります。

クイックリファレンス

症状	最も可能性の高い原因	対処
WHMCSのAddonsメニューにモジュールが表示されない	Access Controlでいずれの管理者ロールにもチェックが入っていない	Access Controlにチェックを入れる
すべての送信が即座に失敗する	Perfex URLがhttp://で始まっている	HTTPSを使用する
Perfexの受信ログにauth.rejectedの行が出る	共有シークレットが一致していない	再ペアリングする
Perfexの送信キューに「Two-way sync requires Pro」と表示される	WHMCS側がFreeプランである	Proを有効化する
イベントはキューに入るが配信されない	同期が一時停止しているか、WHMCSのcronが動作していない	cronを確認する
特定の請求書だけが届かず再試行され続ける	その請求書の通貨がPerfexに存在しない	通貨を追加する
ライセンスが有効化できない	キーが未設定か、ライセンスサービスへの接続がない	バナーの色を確認する
PerfexのページにConnection codeが表示されない	PerfexがHTTPSでないか、保存済みのシークレットが短すぎる	GenerateしてSaveする
部門マッピングがドロップダウンではなくテキストエリアで表示される	Freeプランであるか、PerfexからWHMCSに到達できない	マッピングのフォールバック
行がdead状態のまま止まっている	同じ理由で15回の試行がすべて失敗した	dead状態の行を再実行する

モジュールがAddonsメニューに表示されない

症状。 System Settings > Addon Modules でPerfex CRM Bridgeを有効化し、WHMCSも有効化されたと表示しているのに、左側のAddonsメニューのどこにもモジュールが見当たらない。

原因。 いずれの管理者ロールにもアクセス権が付与されていません。WHMCSは、チェックが入っていないロールに対してアドオンモジュールを完全に隠すため、モジュールはインストール済みで完全に機能する状態でありながら、管理画面のどこにもリンクが表示されません。これは「インストールできない」という報告の圧倒的多数を占める原因です。

対処。

1. System Settings > Addon Modulesに移動します。
2. Perfex CRM Bridgeの横にあるConfigureをクリックします。
3. Access ControlでFull Administratorと、このモジュールを使用する他のロールにチェックを入れます。
4. Save Changesをクリックします。
5. 管理画面を再読み込みします。Addonsの下にモジュールが表示されます。

そのConfigure画面には他に何もありません

実際の設定はすべて、モジュール自身のページ（Addons > Perfex CRM Bridge）にあります。Configure画面に残されているのはAccess Controlだけです。WHMCSのコアが描画しており、移動できないためです。

すべての送信が即座に失敗する、またはURLが拒否される

症状。 イベントがキューに入り、即座に失敗する。Recent activityのログが接続エラーで埋まる。または、Perfex CRM URLフィールドがそもそも保存できない。

原因。 HTTPSは設計上必須です。 HTTPトランスポートはhttpsプロトコルに固定されており、TLS証明書を検証します。http://のURLではすべての送信が失敗し、Perfex側のWHMCS URLフィールドも同様に、https://で始まらない限り保存を受け付けません。

対処。

1. WHMCS側でPerfex CRM URLにhttps://のアドレスを設定します。
2. Perfex側でWHMCS URLにhttps://のアドレスを設定します。
3. どちらの証明書も、ブラウザーだけでなく相手側のサーバーから実際に検証が通ることを確認してください。自己署名証明書は、呼び出し元サーバーがそれを信頼している場合にのみ動作します。
4. WHMCSのモジュールページでTest Connectionをクリックします。

HTTPSの検証を無効にする設定はありません

これは意図的な仕様です。共有シークレットと顧客データがこのチャネルを通ります。証明書の検証が通らない場合は、証明書を修正してください。

Perfexのログにauth.rejectedの行が出る

症状。 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フィールドに貼り付け直し、それぞれ保存します。先頭と末尾の空白は自動的に除去されますが、それ以外の部分は1文字単位で一致している必要があります。

シークレットが原因でない場合。 両サーバーの時刻を確認してください。両者の間に300秒を超えるずれがあると、すべてのリクエストがリプレイとみなされて拒否されます。両方のホストをNTPで同期させてください。

拒否された行にはレート制限があります

Perfexが記録するauth.rejectedの行は1分あたり最大10件です。そのため、設定を誤った送信元があってもディスクを埋め尽くすことはありません。1分間にちょうど10件が記録されている場合は、実際にはそれ以上あったと考えてください。

Perfexの送信キューに「Two-way sync requires Pro」と表示される

症状。 Perfexで顧客を編集すると、Setup > WHMCS BridgeのOutbound queueパネルに「Two-way sync requires Pro on the WHMCS side.」というメッセージとUpgrade to Proのリンクを伴う行が表示される。試行回数が増えていき、最終的にその行がdeadになる。

原因。 双方向同期はPro機能であり、ライセンスはWHMCS側に存在します。WHMCS環境がFreeプランであるため、その受信エンドポイントはPerfex発の変更に対して403を返します。Perfex側のコンパニオンは、キューイングと再試行という正しい動作をしています。

対処。 WHMCS側でProライセンスを有効化してください。ライセンスとProの有効化をご覧ください。Proが有効になると、WHMCSは新しいプラン状態を直ちにPerfexへ送信し、アップグレードの案内が消え、pending状態の行は次回のPerfexのcron実行時に配信されます。

Freeプランのうちに既にdeadになった行は、自動的には再試行されません。dead状態のまま止まっている行をご覧ください。

まずプランのパネルを確認してください

WHMCS planパネルは、まさにこの理由から、Perfexの設定ページのOutbound queueのすぐ上に配置されています。Freeと表示されていれば、キューの行を1つも読まずに原因が判明します。

まったく同期されない

症状。 イベントはキューに現れ、Queue pendingが増え続けるのに、Perfexには何も届かない。エラーもなく、ただ静かなまま。

原因は2つあり、チェックリストで見分けられます。

原因A: 同期が一時停止している

Sync enabledのチェックリスト行が赤になっています。

対処。 WHMCSのモジュールページのSettings > Sync behaviourでEnable Syncにチェックを入れ、Save Settingsをクリックします。一時停止中も失われたものはありません。イベントはキューに入り続けており、これから配信されます。

原因B: WHMCSのシステムcronが動作していない

Cron deliveringのチェックリスト行が赤または黄になっています。

対処。

1. Run Sync Nowをクリックして、ブリッジ自体が動作することを確認します。キューが処理されれば配信は正常であり、問題は純粋にcronにあります。
2. WHMCS自身のcronの状態をUtilities > System > System Health Statusで確認します。WHMCSはシステムcronの最終実行時刻を表示します。
3. 最近cronが実行されていない場合は、サーバーレベルで修正してください。WHMCSのcronコマンドは、ホスティングパネルのcron管理機能、またはサーバーのcrontabに設定されています。お使いのバージョンに応じた正確なコマンドは、WHMCSの公式ドキュメントに記載されています。
4. cronが再び実行されるようになると、実際にブリッジの処理が行われた後の次回のページ読み込みで、Cron deliveringの行が緑になります。

Run Sync Nowではcronの行を緑にできません

この行は「誰も見ていないときにも動き続けるか」という問いに答えるものであるため、本物のWHMCSシステムcronの動作だけを意図的に追跡しています。ボタンを押すことでは、その問いに答えられません。Run Sync Nowは成功するのに、この行が何時間も赤のままである場合、cronは動作していません。

cronの行が黄色でも問題とは限りません

この行が追跡しているのは実際のブリッジの処理です。キューの処理、ログの整理、突き合わせが該当します。健全であっても同期すべき変更がない待機状態の環境は、修正すべき点が何もないまま黄色になることがあります。

請求書が滞留してPerfexに届かない

症状。 特定の請求書だけが繰り返し失敗する。ログのメッセージに通貨名が示され、その行は遅延を伸ばしながら再試行を続ける。

原因。 その請求書の通貨がPerfexに設定されていません。Perfexは、認識していない通貨で合計金額を記録できないため、正しくその請求書を拒否しています。

対処。

1. PerfexでSetup > Finance > Currenciesに移動します。
2. WHMCSが使用しているものと正確に同じISOコード（例: EUR、USD）で通貨を追加します。
3. 他に何もする必要はありません。キューに入っているイベントは独自のスケジュールで再試行され、次の試行で成功します。

猶予はおよそ40時間です

再試行のスケジュールは、およそ40時間にわたる15回の試行を許容します。この時間内に通貨を追加してください。間に合わない場合、その行はデッドレターとなり、手動で再実行する必要があります。過去の請求書をこれからバックフィルする場合は、クライアントが使用するすべての通貨を先に追加してください。

関連するケース: 「Not mapped (will retry)」

親より先に子レコードが届いた状態です。クライアントがまだPerfexに存在しないコンタクト、クライアントがまだマッピングされていない請求書、チケットがまだ同期されていないチケット返信などが該当します。

通常はこれで自然に解消されます。キューは順に配信され、親が登録されれば、子は次の試行で成功します。実際に問題になるのは、親がまったく同期されない場合だけです。たとえば、クライアントをバックフィルせずにサービスだけをバックフィルした場合が該当します。その場合は、親をキューに入れれば（WHMCSでクライアントを編集するか、Clientsのバックフィルを実行すれば）、子も後に続きます。

ライセンスが有効化できない

症状。 キーを貼り付けたのに、環境がFreeのまま表示される。

Proには2つの条件が必要です。有効なキー、およびWHMCSサーバーからライセンスサービスへの接続です。どちらが欠けているかはバナーの色でわかりますので、色をご確認ください。

バナー	意味	対処
🔴 赤	ライセンスサーバーがキーを明確に拒否しました。メッセージに理由が示されます。	購入時のメールからキーを一度でコピーし直してください。キーは32文字で記号を含むことがあるため、一部を削ったり書式を変えたりしないでください。メッセージに導入数や上限への言及がある場合は、不要になった環境からキーを削除して有効化スロットを1つ解放してください。
🟠 黄	サーバーからライセンスサービスに到達できませんでした。これは拒否ではありません。	キーは保存されており、再試行は続きます。WHMCSサーバーの外向きファイアウォールやプロキシで、api.freemius.comへのアウトバウンドHTTPSを許可してください。その後Check licence nowをクリックします。
⚪ バナーがまったく表示されない	すでに保存されていたものと同じキーを保存したため、再確認が行われませんでした。	Check licence nowをクリックしてください。
ヘッダーに「awaiting first verification」と表示される	キーは保存されていますが、一度も確認されていません。	Check licence nowをクリックしてください。

その他の確認事項は次のとおりです。

• キーが、モジュール自身のページのSettings > Pro licenceにあるPro License Keyに入力されていることを確認してください。WHMCSのConfigure画面のどこかではありません。
• Check licence nowを押した後は、次に押すまで数秒お待ちください。すぐに2回目を押すと、リクエストを送らずに「checked a moment ago」と応答します。
• WHMCSではProが有効なのにPerfexがFreeのままの場合は、WHMCSでCheck licence nowまたはTest Connectionを押してください。どちらもプランの状態を直ちにPerfexへ届けます。その後、Perfexの設定ページを再読み込みします。

詳細はライセンスとProの有効化をご覧ください。

PerfexにConnection codeが表示されない

症状。 Setup > WHMCS Bridgeでシークレットを保存したのに、Connection codeフィールドがなく、グレーの注記だけが表示される。

原因と対処。 どちらに該当するかは、その注記自体が示しています。

注記	原因	対処
「not served over HTTPS」	ペアリングにはHTTPSのPerfex環境が必要です。	証明書を修正するか、手動セットアップをご利用ください。
「shorter than 32 characters」	保存済みのシークレットが短すぎます。GenerateをクリックしただけでSaveをクリックしていない、というのがよくある原因です。	GenerateをクリックしてからSaveをクリックします。再読み込み後にコードが表示されます。

ペアリングが「the shared secret does not match」で失敗する

症状。 Connection codeをWHMCSへ貼り付けたところ、HTTP 401に言及する赤色のバナーが表示された。

原因。 そのコードには、Perfexがもはや保持していないシークレットが含まれています。ほぼ必ず、後からGenerateとSaveを行う前にコピーしたコードであるか、Generateしたまま保存されなかったケースです。

対処。 Perfexの設定ページでSaveをクリックし、現在のシークレットが確実に保存された状態にしてから、新しいConnection codeをコピーして貼り付けてください。失敗した試行によってWHMCS側に保存されたものは何もないため、それまでの正常な設定はそのまま維持されています。

部門マッピングがドロップダウンではなくテキストエリアで表示される

症状。 Perfexの設定ページで、部門マッピングがWHMCSの部門ごとのドロップダウンではなく、単純なテキストエリアとして表示される。

原因。 ページがWHMCSのサポート部門一覧を取得できませんでした。どのケースに該当するかは、テキストエリアの下のヒントが示しています。

ヒント	原因	対処
「Couldn't fetch WHMCS departments (needs Pro + working connection)」	ブリッジが未設定である、PerfexサーバーからWHMCSに到達できない、またはWHMCSがFreeプランです。部門一覧は、チケット同期と同じライセンスの制限下にあります。	ペアリングを完了し、PerfexからWHMCSのURLへHTTPSで到達できることを確認したうえで、Proを有効化してください。
「Connection OK, but WHMCS has no support departments yet」	取得は成功しています。単にマッピングする対象がありません。	WHMCSのSupport > Support Departmentsで部門を作成してから、Perfexのページを再読み込みしてください。

その間も、whmcs_deptid=perfex_department_idを1行に1つ記述する手動のテキストエリアは常に利用できます。これによって同期が止まることはありません。マッピングされていないチケットは、既定の部門、またはPerfexの最小の部門IDへフォールバックします。

dead状態のまま止まっている行

症状。 WHMCSのモジュールページのDead eventsカウンター、またはPerfexのOutbound queueパネルのdead件数が0より大きい。

原因。 それらの行は、同じ理由でおよそ40時間にわたり15回失敗しました。dead状態の行が自動的に再試行されることも、自動削除されることもありません。これは内容を確認できるようにするための意図的な仕様です。

対処。

1. 理由を特定します。 WHMCSでRecent activityを開くか、PerfexでOutbound queueの「Last error」列を開き、該当する行のエラーを確認します。原因はほぼ必ず次のいずれかです。Perfexの通貨が未登録、シークレットの不一致、Freeプランによる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は、再実行したい行のIDに置き換えてください。Perfex側の対応するテーブルはtblwhmcs_bridge_outboxで、Perfexのテーブルプレフィックスが付きます。

Perfexでの変更がWHMCSに届かない

次のリストを順に確認してください。

1. WHMCS側はProですか。 Perfexの設定ページのWHMCS planパネルを確認してください。双方向同期はProのみの機能です。
2. Perfex側にWHMCS URLが設定されていますか。 Setup > WHMCS Bridge > WHMCS URLを、HTTPSで末尾にパスを付けずに設定します。ペアリングは通常、初回に自動でこれを入力しますが、既に値がある場合は上書きしません。
3. PerfexサーバーからWHMCSへHTTPSで到達できますか。 Perfexの送信クライアントも、WHMCS側とまったく同様にHTTPSに固定され、証明書を検証します。
4. Perfexのcronは動作していますか。 Perfex発の変更は、WHMCSのcronではなくPerfexのcronで配信されます。Perfexのcronジョブをご確認ください。
5. そのレコードはマッピングされていますか。 マッピングされているのは、WHMCSから同期された顧客だけです。Perfexで直接作成した顧客にはWHMCS側の対応レコードがないため、送信されることはありません。同様に、Perfexで直接作成したチケットはPerfexに留まります。
6. Outbound queueパネルを確認してください。 行ごとに直近のエラーが示されています。

変更が戻ってきて、自分の編集が上書きされた

症状。 一方のシステムでレコードを編集したのに、もう一方のシステムの値に戻ってしまった。

原因。 前回の同期以降に両側が同じレコードを変更したため、Two-Way Conflict Policyが優先する側を決定しました。

対処。 WHMCSのモジュールページのSettings > Sync behaviourで、チームの運用に合ったポリシーを選択してください。

• newest_wins（既定） - より新しい編集を優先します。両サーバーの時刻が正確であることが前提です。
• whmcs_wins - 常にWHMCSを正とします。
• perfex_wins - 常にPerfexを正とします。

両ホストの時刻を管理できない場合は、newest_winsを避けてください。時刻のずれの分だけ、判定結果もずれます。

1件のチケット返信で顧客に2通のメールが届く

症状。 Perfexのスタッフが同期されたチケットに返信すると、顧客に2件の通知が届く。

原因。 Perfexが独自のチケット返信メールを送信し、さらにWHMCSへ同期された返信によってWHMCSも独自の通知を送信するためです。これは同期のループではなく、仕様として明記された挙動です。メールの抑止が及ぶのは、WHMCSからPerfexへの方向だけです。

対処。 顧客がWHMCSのクライアントポータルを利用している場合は、PerfexのSetup > Email Templates > Ticketsでticket-replyのメールテンプレートを無効にしてください。

それでも解決しない場合: サポートへ問い合わせる前に用意するもの

以下をご用意いただければ、通常は最初の返信で回答できます。

• 両モジュールのバージョン（現在は1.3.4）と、両側が同じバージョンであることの確認。
• WHMCSのバージョン、Perfex CRMのバージョン、両サーバーのPHPバージョン。
• WHMCSのモジュールページのセットアップチェックリストのスクリーンショット。
• Queue pendingとDead eventsの件数。
• WHMCSのRecent activityとPerfexのRecent inbound eventsの該当する行（メッセージ列を省略せず全文）。
• 失敗したときに行っていた操作と、以前は正常に動作していたかどうか。

共有シークレットやConnection codeは絶対に送らないでください

Connection codeには共有シークレットが含まれています。どちらも、サポートのチケット、スクリーンショット、チャットのメッセージに含めるべきものではありません。サポートが問題を診断するために、これらを必要とすることはありません。