Installation

Auf dieser Seite installieren Sie beide Hälften von Perfex CRM Integration for WHMCS. Halten Sie sich an die Reihenfolge. Der gesamte Vorgang läuft über zwei Browser-Tabs und den File Manager Ihres Hosting-Panels. SSH oder eine Kommandozeile sind nicht erforderlich.

Sie sollten upload.zip (themesic.com/marketplace/whmcs-perfex.zip) bereits entpackt haben, sodass Ihnen zwei Dateien vorliegen:

Datei	Bestimmt für
🧩 perfex-module/module.zip	Perfex CRM
⚙️ whmcs-addon/addon.zip	WHMCS

Schnellinstallation (die Kurzfassung)

Für einen erfahrenen Hosting-Administrator besteht die gesamte Aufgabe aus fünf Schritten. Führen Sie sie in dieser Reihenfolge aus.

1. 🧩 Zuerst Perfex. Gehen Sie in Perfex CRM zu Setup > Modules > Upload Module, laden Sie module.zip hoch und klicken Sie dann auf Activate. Wenn Sie die Perfex-Seite zuerst installieren, existiert der empfangende Endpunkt, bevor WHMCS überhaupt etwas sendet.
2. ⚙️ WHMCS-Addon. Laden Sie addon.zip nach modules/addons/ hoch und entpacken Sie es dort, sodass Sie am Ende modules/addons/perfexbridge/perfexbridge.php erhalten, und aktivieren Sie anschließend Perfex CRM Bridge unter System Settings > Addon Modules.
3. 🔓 Access Control anhaken. Haken Sie auf dem Bildschirm Configure des Addons Full Administrator an (dazu jede weitere Rolle, die es nutzen soll) und klicken Sie auf Save Changes. Ohne diesen Schritt ist das Modul unsichtbar - es erscheint überhaupt nicht im Menü Addons.
4. 🔗 Beide Seiten koppeln. Öffnen Sie Addons > Perfex CRM Bridge, fügen Sie den aus Perfex kopierten Connection code in das Feld Quick setup ein und klicken Sie auf Connect. Einzelheiten in der Konfiguration.
5. ✅ Prüfen. Legen Sie in WHMCS einen Testkunden an, klicken Sie auf Run Sync Now und bestätigen Sie, dass er in Perfex unter Customers erscheint.

Jeder Klick, jede Zeile der Checkliste und die vollständige durchgängige Prüfung finden sich unten in der Ausführlichen Anleitung.

Ausführliche Anleitung

Die Reihenfolge ist wichtig

Installieren Sie zuerst das Perfex-Companion. Es erzeugt den empfangenden Endpunkt. Wenn Sie zuerst das WHMCS-Addon installieren und mit der Synchronisierung beginnen, schlägt jedes Ereignis fehl, solange die Perfex-Seite nicht existiert, und Sie verbringen Zeit damit, Fehlerprotokolle zu einem Problem zu lesen, das Sie noch gar nicht verursacht haben.

Schritt 1: Das Perfex CRM Companion installieren

Das Perfex-Companion ist kostenlos, benötigt keinen Lizenzschlüssel und wird vollständig aus dem Perfex-Verwaltungsbereich heraus installiert.

1. Melden Sie sich in Perfex CRM als Administrator an.
2. Gehen Sie zu Setup > Modules.
3. Klicken Sie auf die Schaltfläche Upload Module.
4. Wählen Sie module.zip im Dateiauswahldialog und laden Sie die Datei hoch.
5. Perfex führt das Modul als WHMCS Bridge auf. Klicken Sie auf Install, sofern Sie dazu aufgefordert werden, und anschließend auf Activate.

Wenn der Upload wegen der Dateigröße abgelehnt wird

Die Schaltfläche Upload Module überträgt das Zip-Archiv über PHP, daher müssen die Limits upload_max_filesize und post_max_size Ihres Servers beide größer sein als die Datei. Schlägt der Upload fehl, erhöhen Sie entweder diese Limits in Ihrer PHP-Konfiguration, oder Sie nutzen den manuellen Weg unten.

Manueller Weg: Entpacken Sie module.zip auf Ihrem Rechner und laden Sie den entstandenen Ordner whmcs_bridge per FTP oder über den File Manager Ihres Hosting-Panels in das Verzeichnis modules/ Ihrer Perfex-Installation hoch. Das Ergebnis muss modules/whmcs_bridge/whmcs_bridge.php sein. Kehren Sie anschließend zu Setup > Modules zurück und klicken Sie auf Activate.

Prüfen, ob die Perfex-Seite korrekt installiert wurde

• Ein neuer Eintrag WHMCS Bridge erscheint im Perfex-Menü Setup. Auf dieser Seite erzeugen Sie im nächsten Kapitel das gemeinsame Secret.

Schritt 2: Das WHMCS-Addon installieren

WHMCS besitzt keinen Modul-Installer innerhalb der Verwaltung. Sie legen die Dateien selbst auf der Festplatte ab und aktivieren sie anschließend im Verwaltungsbereich. Der File Manager Ihres Hosting-Panels genügt dafür vollständig.

1. Öffnen Sie den File Manager Ihres Hosting-Panels und wechseln Sie in das Verzeichnis modules/addons/ Ihrer WHMCS-Installation.
2. Laden Sie addon.zip nach modules/addons/ hoch.
3. Nutzen Sie die Aktion Extract des File Managers für die hochgeladene Datei und entpacken Sie sie in dasselbe Verzeichnis modules/addons/.
4. Vergewissern Sie sich, dass das Ergebnis modules/addons/perfexbridge/perfexbridge.php lautet. Falls Sie bei modules/addons/perfexbridge/perfexbridge/perfexbridge.php gelandet sind, wurde eine Ebene zu tief entpackt. Verschieben Sie den inneren Ordner eine Ebene nach oben und löschen Sie die leere Hülle.
5. Löschen Sie die hochgeladene addon.zip vom Server, sobald das Entpacken erfolgreich war.

Alternative über FTP

Entpacken Sie addon.zip zuerst auf Ihrem eigenen Rechner und laden Sie den entstandenen Ordner perfexbridge anschließend per FTP nach modules/addons/ hoch. Der Endzustand ist identisch.

Nun aktivieren Sie das Addon:

6. Gehen Sie in WHMCS zu System Settings > Addon Modules.
7. Suchen Sie Perfex CRM Bridge in der Liste und klicken Sie auf Activate.

Schritt 3: Access Control anhaken, sonst bleibt das Modul unsichtbar

Das ist die häufigste Meldung "es hat sich nicht installiert"

Nach der Aktivierung zeigt WHMCS das Konfigurationspanel des Moduls mit einem Abschnitt Access Control, in dem Ihre Administratorrollen aufgeführt sind. Sie müssen mindestens Full Administrator anhaken, dazu jede weitere Rolle, die das Modul nutzen soll, und anschließend auf Save Changes klicken.

Solange keine Rolle angehakt ist, erscheint das Modul überhaupt nicht im linken Addons-Menü. Das Modul ist installiert, seine Tabellen existieren und seine Einstellungsseite funktioniert einwandfrei, aber es gibt nirgends im Verwaltungsbereich einen Link darauf. In neun von zehn Fällen bedeutet "das Modul hat sich nicht installiert" genau, dass dieses Kästchen nie angehakt wurde.

Konkret:

1. Klicken Sie, weiterhin unter System Settings > Addon Modules, neben Perfex CRM Bridge auf Configure. WHMCS öffnet dieses Panel meist automatisch direkt nach der Aktivierung.
2. Haken Sie unter Access Control die Rolle Full Administrator an. Haken Sie jede weitere Administratorrolle an, die die Bridge öffnen und konfigurieren können soll.
3. Klicken Sie auf Save Changes.
4. Aktualisieren Sie den Verwaltungsbereich. Perfex CRM Bridge erscheint nun im Menü Addons.

Access Control ist das Einzige auf dem Configure-Bildschirm

Jede echte Einstellung dieses Moduls liegt auf der eigenen Modulseite unter Addons > Perfex CRM Bridge, nicht auf dem WHMCS-Configure-Bildschirm. Dieser Bildschirm enthält ausschließlich Access Control, weil dieser Bereich vom WHMCS-Kern gerendert wird und nicht verschoben werden kann. Wenn Sie Configure öffnen, um dort die Perfex-URL oder den Lizenzschlüssel zu suchen, sind Sie auf dem falschen Bildschirm. Siehe Konfiguration.

Schritt 4: Die Modulseite öffnen

Gehen Sie zu Addons > Perfex CRM Bridge.

Die Seite öffnet sich mit der Setup checklist. Bei einer frischen Installation sieht sie so aus:

Zeile der Checkliste	Erwarteter Zustand zu diesem Zeitpunkt
Module tables present	🟢 Grünes Häkchen
Connection configured	🔴 Rotes Kreuz, noch nichts gekoppelt
Connection verified	⚪ Grauer Strich, noch nie geprüft
Sync enabled	🔴 Rotes Kreuz, bis Sie Enable Sync anhaken
Cron delivering	🔴 Rotes Kreuz, noch keine Cron-Aktivität protokolliert
License / plan	⚪ Grauer Strich, Free-Plan

Das ist der korrekte Zustand für eine frisch installierte, noch nicht konfigurierte Bridge. Jede Zeile wird in der Konfiguration erläutert.

Als Nächstes koppeln Sie die beiden Seiten: Konfiguration.

Schritt 5: Die erste Synchronisierung durchgängig prüfen

Führen Sie dies einmal aus, unmittelbar nach der Kopplung, bevor Sie der Bridge echte Daten anvertrauen. Es dauert zwei Minuten und belegt, dass die gesamte Verarbeitungskette funktioniert.

1. Schließen Sie die in der Konfiguration beschriebene Kopplung ab. Die Checklistenzeilen Connection configured und Connection verified müssen beide grün sein.
2. Vergewissern Sie sich auf derselben Seite unter Settings > Sync behaviour, dass Enable Sync angehakt ist, und klicken Sie auf Save Settings. Die Zeile Sync enabled wird grün.
3. Legen Sie in WHMCS einen Testkunden an. Ein beliebiger Name und eine beliebige E-Mail-Adresse genügen, zum Beispiel eine Firma namens Bridge Test Ltd.
4. Kehren Sie zu Addons > Perfex CRM Bridge zurück. Der Zähler Queue pending im oberen Bereich sollte mindestens 1 anzeigen.
5. Klicken Sie auf Run Sync Now. Damit erzwingen Sie einen sofortigen Auslieferungsversuch, ohne auf den Cron zu warten. Die Seite meldet, wie viele Ereignisse gesendet wurden, fehlgeschlagen sind und im Dead-Letter-Status gelandet sind.
6. Öffnen Sie in Perfex CRM den Bereich Customers. Der Testkunde ist nun als Kunde vorhanden, mit Name und E-Mail-Adresse des WHMCS-Kunden als primärem Kontakt.
7. Prüfen Sie, ob beide Protokolle den Vorgang erfasst haben:
   • WHMCS-Seite: Die Tabelle Recent activity weiter unten auf der Modulseite zeigt eine Zeile client.upsert mit dem Status ok.
   • Perfex-Seite: Setup > WHMCS Bridge, Panel Recent inbound events, zeigt eine passende Zeile client.upsert mit einem grünen ok-Abzeichen.
8. Löschen Sie den Testkunden in beiden Systemen, wenn Sie ihn nicht behalten möchten.

"Run Sync Now" beweist nicht, dass Ihr Cron funktioniert

Run Sync Now beweist die Auslieferung. Die Checklistenzeile Cron delivering wird dadurch nicht grün, denn diese Zeile verfolgt bewusst nur echte Aktivität des WHMCS-System-Crons. Ist diese Zeile eine Stunde später immer noch rot oder gelb, läuft Ihr WHMCS-System-Cron nicht, und es wird nichts automatisch synchronisiert. Bringen Sie den Cron in Ordnung, bevor Sie in den Produktivbetrieb gehen. Siehe Fehlerbehebung.

Auf eine neuere Version aktualisieren

Beide Module tragen dieselbe Version und sollten immer gemeinsam aktualisiert werden.

Perfex-Seite. Laden Sie die neue module.zip über Setup > Modules > Upload Module hoch und überschreiben Sie das bestehende Modul, dann rufen Sie eine beliebige Verwaltungsseite auf. Das Companion erkennt die veraltete Datenbankversion und wendet seine Migrationen selbständig an. Alternativ können Sie das Modul deaktivieren und wieder aktivieren. Beide Wege sind sicher: Jede Migrationsanweisung ist abgesichert, sodass ein erneuter Durchlauf nichts verändert, was bereits korrekt ist.

WHMCS-Seite. Laden Sie die neue addon.zip hoch und entpacken Sie sie über modules/addons/perfexbridge/. WHMCS führt die Upgrade-Routine des Moduls aus, sobald es die neue Versionsnummer erkennt. Im Zweifelsfall deaktivieren und reaktivieren Sie das Addon unter System Settings > Addon Modules.

Ihre Einstellungen überstehen ein Upgrade

Einstellungen, das gemeinsame Secret, der Lizenzschlüssel, die Entitätszuordnung und die Protokolle liegen sämtlich in Datenbanktabellen, die bei Upgrades nie gelöscht werden. Auch das Deaktivieren des WHMCS-Addons löscht dessen Daten nicht.

Deinstallation

1. WHMCS: System Settings > Addon Modules > Perfex CRM Bridge > Deactivate, anschließend modules/addons/perfexbridge/ von der Festplatte löschen.
2. Perfex: Setup > Modules, WHMCS Bridge deaktivieren und das Modul anschließend entfernen.
3. Wenn Sie auch die Daten entfernen möchten, löschen Sie die Datenbanktabellen des Moduls in jedem System (erstellen Sie zuvor eine Sicherung).
4. Falls eine Pro-Lizenz aktiv war, entfernen Sie den Schlüssel vor der Deinstallation, damit der Aktivierungs-Slot freigegeben und die Lizenz anderweitig genutzt werden kann. Siehe Lizenzierung und Pro-Aktivierung.