Zum Hauptinhalt springen

Konfiguration

Alles auf dieser Seite setzt voraus, dass beide Module installiert und aktiviert sind und dass Sie in WHMCS Addons > Perfex CRM Bridge sowie in Perfex CRM Setup > WHMCS Bridge erreichen. Fehlt eines von beiden, kehren Sie zur Installation zurück. In WHMCS ist die übliche Ursache das fehlende Häkchen bei Access Control.

Wie sich die beiden Seiten authentifizieren

Beide Endpunkte authentifizieren jede Anfrage mit einer HMAC-SHA256-Signatur, die aus einem gemeinsamen Secret abgeleitet wird.

In einfachen Worten: Der Sender signiert den Anfragekörper mit dem Secret und versieht ihn mit einem Zeitstempel. Der Empfänger berechnet die Signatur mit seiner eigenen Kopie des Secrets neu und weist alles zurück, dessen Signatur nicht übereinstimmt oder dessen Zeitstempel älter als 300 Sekunden ist. Genau dieses Zeitfenster verhindert, dass jemand eine abgefangene Anfrage später erneut abspielt.

Die Konsequenz: Das Secret muss auf beiden Seiten Byte für Byte identisch sein, sonst schlägt jede einzelne Anfrage mit einem 401 fehl. Zusätzlich weist jeder Endpunkt sämtlichen Verkehr ab, solange sein eigenes Secret leer ist, sodass eine halb konfigurierte Bridge geschlossen und nicht offen ist.

Beide Seiten entfernen führende und nachfolgende Leerzeichen vor der Verwendung, ein beim Kopieren aufgeschnapptes Leerzeichen oder ein Zeilenumbruch bringt Sie also nicht zu Fall. Alles dazwischen muss exakt übereinstimmen.

Behandeln Sie das gemeinsame Secret wie ein Zugangsdatum

Das gemeinsame Secret gewährt Schreibzugriff auf Perfex-Kunden und -Kontakte und, mit einer Pro-Lizenz, auf Rechnungen, Zahlungen, Bestellungen und Tickets auf beiden Seiten. Wechseln Sie es sofort auf beiden Seiten, wenn eine der Datenbanken oder eine Sicherung davon jemals offengelegt wurde. Secrets werden im Klartext in tbladdonmodules (WHMCS) und tbloptions (Perfex) gespeichert, was in beiden Ökosystemen üblich ist, das heißt jede Person mit Datenbankzugriff kennt das Secret.

Kopplung: der schnelle Weg (empfohlen)

Sie müssen Einstellungen nicht von Hand hin und her kopieren. Perfex erzeugt einen einzigen Connection code, der sowohl die Perfex-URL als auch das gemeinsame Secret enthält, und WHMCS verarbeitet ihn mit einem einzigen Einfügen.

Schritt 1: Das Secret in Perfex erzeugen

  1. Gehen Sie in Perfex CRM zu Setup > WHMCS Bridge.
  2. Klicken Sie neben Shared Secret auf Generate. Das Feld füllt sich mit einem starken, 64 Zeichen langen Zufallswert und wird sichtbar, damit Sie sehen, was Sie gleich speichern. Die Augen-Schaltfläche schaltet die Sichtbarkeit wieder um.
  3. Klicken Sie auf Save.

Schritt 2: Den Connection code kopieren

Die Seite lädt neu und zeigt nun ein schreibgeschütztes Feld Connection code. Sein Wert ist eine einzelne Zeichenkette, die mit PBC1. beginnt.

Klicken Sie auf Copy. Die Schaltfläche blinkt "Copied!", sobald der Code in Ihrer Zwischenablage liegt.

Der Connection code ist ein Passwort

Der Code besteht aus PBC1. gefolgt von base64url-kodiertem JSON, das Ihre Perfex-URL und Ihr gemeinsames Secret enthält. Das ist Kodierung, keine Verschlüsselung. Wer den Code erlangt, kann mit Ihren Bridge-Endpunkten kommunizieren. Fügen Sie ihn niemals in ein öffentliches Ticket, einen Chat-Kanal, einen Screenshot oder eine Support-Anfrage ein.

Wenn kein Connection code erscheint

Der Code wird nur dargestellt, wenn zwei Bedingungen erfüllt sind: Ihre Perfex-Installation wird über HTTPS ausgeliefert, und das gespeicherte gemeinsame Secret ist mindestens 32 Zeichen lang. Die übliche Ursache ist ein Klick auf Generate ohne anschließenden Klick auf Save. Die Seite nennt Ihnen die nicht erfüllte Bedingung:

  • "not served over HTTPS" - die Kopplung benötigt HTTPS. Nutzen Sie stattdessen die manuelle Einrichtung, oder bringen Sie das Zertifikat in Ordnung.
  • "shorter than 32 characters" - klicken Sie auf Generate, dann auf Save, und der Code erscheint.

Schritt 3: Den Code in WHMCS einfügen

  1. Öffnen Sie in WHMCS Addons > Perfex CRM Bridge.
  2. Suchen Sie das grüne Feld Quick setup im oberen Bereich der Seite.
  3. Fügen Sie den Code in das Eingabefeld ein.
  4. Klicken Sie auf Connect.

Was Connect tatsächlich tut

In einem einzigen Schritt und in dieser Reihenfolge:

  1. Es dekodiert den Code und validiert ihn streng: das Präfix PBC1., striktes base64url, ein wohlgeformtes JSON-Objekt, eine URL, die mit https:// beginnt und die URL-Prüfung besteht, sowie ein Secret von mindestens 32 Zeichen.
  2. Es sendet einen signierten Ping mit der dekodierten URL und dem dekodierten Secret an Ihre Perfex-Installation und wartet auf das pong.
  3. Nur wenn dieser Ping erfolgreich ist, speichert es die Perfex CRM URL und das Shared Secret auf der WHMCS-Seite.
  4. Ausschließlich bei der ersten Kopplung überträgt der Ping zusätzlich Ihre WHMCS-Basis-URL, sodass das Feld WHMCS URL auf der Perfex-Seite für Sie ausgefüllt wird. Das geschieht nur, wenn Ihr WHMCS über HTTPS ausgeliefert wird, und es überschreibt niemals einen bereits gesetzten Wert.
  5. Es hält die erfolgreiche Prüfung fest, sodass die Checklistenzeile Connection verified noch beim selben Seitenaufbau grün wird.

Bei Erfolg erhalten Sie ein grünes Banner, das die gekoppelte Perfex-URL nennt. Bei einem Fehler erhalten Sie ein rotes Banner, das genau erklärt, was schiefgelaufen ist, und es wird nichts gespeichert. Ein Code, der die Prüfung nicht besteht, kann niemals eine derzeit funktionierende Konfiguration überschreiben.

Später neu koppeln

Sobald WHMCS konfiguriert ist, wird aus dem Feld Quick setup ein unaufdringliches Re-pair-Formular. Fügen Sie jederzeit einen frischen Code ein, wenn Sie das Secret wechseln oder Perfex auf eine neue Domain umziehen. Es gilt dieselbe Regel: Ein Code, der die Prüfung nicht besteht, ändert nichts.

Erst das Secret wechseln, dann neu koppeln, in genau dieser Reihenfolge

Wenn Sie auf der Perfex-Seite auf Generate und Save klicken, schlägt jede bestehende WHMCS-Anfrage sofort mit HTTP 401 fehl, bis Sie den neuen Code in WHMCS einfügen. Führen Sie die beiden Schritte unmittelbar nacheinander aus. Ein alter, vor dem Wechsel kopierter Code wird zurückgewiesen, und das Banner teilt Ihnen mit, dass Perfex mit 401 geantwortet hat.

Kopplung: der manuelle Weg

Der Connection code ist Bequemlichkeit, keine Zauberei. Alles, was er tut, lässt sich auch von Hand erledigen, und Sie benötigen diesen Weg, wenn Ihre Perfex-Installation noch nicht über HTTPS läuft oder wenn Ihre Arbeitsabläufe das Einfügen kombinierter Zugangsdaten untersagen.

  1. Erzeugen Sie ein starkes Zufalls-Secret von mindestens 32 Zeichen. Nutzen Sie die Schaltfläche Generate auf der Perfex-Einstellungsseite oder Ihr eigenes Werkzeug, zum Beispiel openssl rand -hex 32.
  2. In Perfex, unter Setup > WHMCS Bridge, fügen Sie es in Shared Secret ein und klicken auf Save.
  3. In WHMCS öffnen Sie Addons > Perfex CRM Bridge, scrollen zu Settings > Connection und gehen wie folgt vor:
    • setzen Sie Perfex CRM URL auf Ihre Perfex-Basis-URL, zum Beispiel https://crm.example.com, über HTTPS und ohne angehängten Pfad;
    • fügen Sie dasselbe Secret in Shared Secret ein.
  4. Klicken Sie auf Save Settings.
  5. Klicken Sie oben auf der Seite auf Test Connection. Sie möchten das grüne Banner "Connection OK" sehen.
  6. Für die Pro-Zwei-Wege-Synchronisierung setzen Sie zusätzlich WHMCS URL auf der Perfex-Einstellungsseite. Die Kopplung hätte das für Sie erledigt.

WHMCS-Einstellungen, Abschnitt für Abschnitt

Alle Einstellungen liegen auf der eigenen Modulseite

Öffnen Sie Addons > Perfex CRM Bridge und scrollen Sie zu Settings. Suchen Sie nicht auf dem WHMCS-Bildschirm Configure unter System Settings > Addon Modules; dieser Bildschirm enthält ausschließlich Access Control, das vom WHMCS-Kern gerendert wird und nicht verschoben werden kann.

Klicken Sie auf Save Settings, um die Änderungen zu übernehmen. Das Formular gilt als Ganzes: Ein ungültiger Eintrag, zum Beispiel eine URL ohne HTTPS, lässt die gesamte Übermittlung scheitern, und nichts wird geändert.

Die beiden Secret-Felder zeigen niemals ihren gespeicherten Wert

Shared Secret und Pro License Key werden immer leer dargestellt, damit ein gespeichertes Zugangsdatum nicht im Seitenquelltext jedes Administrators steht, der das Modul öffnen kann. Lassen Sie ein Feld leer, um den aktuellen Wert beizubehalten. Tippen Sie hinein, um diesen Wert zu ersetzen. Um einen Pro-Schlüssel vollständig zu entfernen, haken Sie Remove the stored key an.

Connection

EinstellungFunktionSinnvoller Standardwert
Perfex CRM URLDie Basis-URL Ihrer Perfex-Installation, zum Beispiel https://crm.example.com. Muss HTTPS sein: Die Bridge sendet grundsätzlich nicht über einfaches HTTP.Wird durch die Kopplung automatisch gesetzt
Shared SecretDas HMAC-Secret. Es muss mit dem in Perfex unter Setup > WHMCS Bridge konfigurierten Secret übereinstimmen. Leer lassen, um das gespeicherte zu behalten.Wird durch die Kopplung automatisch gesetzt

Sync behaviour

EinstellungFunktionSinnvoller Standardwert
Enable SyncDer Hauptschalter. Häkchen entfernen, um die gesamte ausgehende Auslieferung anzuhalten. Ereignisse werden weiterhin eingereiht, während die Auslieferung pausiert, es geht also nichts verloren; sie werden beim nächsten Durchlauf nach dem Wiedereinschalten ausgeliefert.An, sobald konfiguriert
Order Sync Target (Pro)Was aus einer WHMCS-Bestellung in Perfex wird. lead erzeugt einen Perfex-Lead je Bestellung. note fügt stattdessen eine Notiz beim Perfex-Kunden hinzu. off synchronisiert Bestellungen überhaupt nicht.lead
Two-Way Conflict Policy (Pro)Welche Seite gewinnt, wenn beide Systeme denselben Kunden oder Kontakt seit der letzten Synchronisierung geändert haben. Siehe unten.newest_wins

Die Optionen der Konfliktregel, je eine Zeile:

  • newest_wins (Standard) - vergleicht den Zeitpunkt des eingehenden Perfex-Ereignisses mit dem Zeitpunkt der letzten Synchronisierung; die neuere Änderung gewinnt.
  • whmcs_wins - behält die WHMCS-Daten und verwirft die konkurrierende Perfex-Änderung.
  • perfex_wins - wendet die Perfex-Änderung auf die WHMCS-Daten an.
Die Konfliktregel greift nur bei einem echten Konflikt

Sie gilt ausschließlich dann, wenn beide Seiten denselben Datensatz seit der letzten erfolgreichen Synchronisierung geändert haben. Eine gewöhnliche Änderung auf einer Seite, während die andere Seite unberührt bleibt, wird immer übernommen. Sie entscheiden also nicht, welches System generell "gewinnt", sondern lediglich, wie ein Gleichstand aufgelöst wird.

Ein Hinweis zu newest_wins und Serveruhren

"Neuer" vergleicht den Zeitstempel des sendenden Servers mit dem Zeitpunkt der letzten Synchronisierung auf dem empfangenden Server, es kommt also auf die Uhren beider Hosts an. Betreiben Sie beide Server mit NTP. Wenn die Uhrenabweichung zwischen Ihrem WHMCS-Host und Ihrem Perfex-Host außerhalb Ihrer Kontrolle liegt, bevorzugen Sie whmcs_wins oder perfex_wins, denn diese sind deterministisch.

Tickets

EinstellungFunktionSinnvoller Standardwert
Ticket Reply Admin (Pro)Der WHMCS-Administrator-Benutzername, der verwendet wird, wenn eine Antwort eines Perfex-Mitarbeiters in ein WHMCS-Ticket synchronisiert wird. Leer lassen, um die Antwort stattdessen dem Namen des Perfex-Mitarbeiters zuzuschreiben; sie wird dann als Nicht-Administrator-Antwort veröffentlicht.Leer

Pro licence

EinstellungFunktionSinnvoller Standardwert
Pro License KeyFür den Free-Plan leer lassen. Fügen Sie hier Ihren Pro-Schlüssel ein, um die Pro-Funktionen freizuschalten. Schlüssel beginnen mit sk_. Das Speichern eines geänderten Schlüssels prüft ihn unmittelbar live.Leer (Free)
Remove the stored keyEin Kontrollkästchen, das nur erscheint, wenn ein Schlüssel gespeichert ist. Anhaken und speichern setzt die Installation auf Free zurück und gibt den Aktivierungs-Slot dieser Website frei, sodass die Lizenz anderweitig genutzt werden kann.Nicht angehakt
Check licence now (Schaltfläche, oben auf der Seite)Erzwingt eine sofortige erneute Prüfung des bereits gespeicherten Schlüssels und umgeht die tägliche Drosselung.-
Upgrade to Pro / Buy a Pro licence (Links)Öffnen den Bestellvorgang. Bei einer Installation ohne Pro erscheinen sie neben dem Schlüsselfeld, in der Lizenzzeile der Checkliste und in den Pro-Hinweisboxen.-

Alle Details finden Sie unter Lizenzierung und Pro-Aktivierung.

Pro-Einstellungen lassen sich gefahrlos im Free-Plan konfigurieren

Order Sync Target, Two-Way Conflict Policy und Ticket Reply Admin lassen sich in einer Free-Installation problemlos speichern. Sie bleiben lediglich wirkungslos, bis eine gültige Lizenz aktiv ist, und die Seite weist unter jedem Feld darauf hin. Konfigurieren Sie sie ruhig im Voraus.

Perfex CRM-Einstellungen, Feld für Feld

Öffnen Sie Setup > WHMCS Bridge im Perfex-Verwaltungsbereich und klicken Sie anschließend auf Save.

Connection

FeldFunktionStandard / Rückfallwert
Shared SecretMuss mit dem WHMCS Shared Secret übereinstimmen. Nutzen Sie Generate für einen starken Wert und anschließend Save. Die Augen-Schaltfläche zeigt ihn an oder verbirgt ihn. Der Endpunkt weist sämtlichen Verkehr ab, solange dieses Feld leer ist.Leer, Endpunkt geschlossen
Connection codeSchreibgeschützt. Erscheint, sobald das gespeicherte Secret mindestens 32 Zeichen lang ist und Perfex über HTTPS läuft. Kopieren Sie ihn in das WHMCS-Feld Quick setup.Wird automatisch dargestellt
WHMCS URLDie Basis-URL der WHMCS-Installation, auf der das Addon läuft. Nur für den Verkehr von Perfex nach WHMCS erforderlich, was eine Pro-Funktion ist. Muss mit https:// beginnen, sonst wird der Wert nicht gespeichert.Wird bei der ersten Kopplung automatisch gefüllt, danach nie überschrieben

Ticket sync (Pro)

FeldFunktionStandard / Rückfallwert
Department mapping (WHMCS to Perfex)Ordnet jede WHMCS-Ticketabteilung einer Perfex-Abteilung zu. Wird als ein Dropdown je WHMCS-Abteilung dargestellt, sofern das Verzeichnis abgerufen werden kann, andernfalls als manuelles Textfeld.Leer, nichts zugeordnet
Default department for unmapped WHMCS ticketsDie Perfex-Abteilung, die für jedes WHMCS-Ticket verwendet wird, dessen Abteilung nicht in der Zuordnung steht."Lowest department id (automatic)"
Staff author for synced WHMCS staff repliesDer Perfex-Mitarbeiter, dem die nach Perfex gespiegelten WHMCS-Mitarbeiterantworten als Autor zugeschrieben werden."First active admin (automatic)"
Create a Perfex task per synced ticketWenn angehakt, erhält jedes synchronisierte Ticket eine verknüpfte Perfex-Aufgabe, sodass Ihre Mitarbeitenden mit den nativen Perfex-Timesheets Zeit darauf buchen können.Aus

Wie die Abteilungszuordnung dargestellt wird

Der Normalfall sind Dropdowns. Beim Laden der Einstellungsseite wird Ihr WHMCS-Verzeichnis der Support-Abteilungen über die signierte Bridge abgerufen und je WHMCS-Abteilung eine Zeile mit einem Dropdown Ihrer Perfex-Abteilungen dargestellt. Wählen Sie für jede Zeile ein Ziel oder belassen Sie sie auf - not mapped - und klicken Sie auf Save.

Dieser Abruf benötigt eine funktionierende Verbindung und ein WHMCS mit Pro-Lizenz, denn das Abteilungsverzeichnis liegt hinter derselben Lizenzschranke wie die Ticket-Synchronisierung. Ist der Abruf nicht möglich, fällt die Seite automatisch auf ein manuelles Textfeld zurück und nennt Ihnen den Grund:

Was Sie sehenWas es bedeutet
Dropdowns, eines je WHMCS-AbteilungAlles funktioniert
Textfeld, "Couldn't fetch WHMCS departments (needs Pro + working connection)"Die Bridge ist noch nicht konfiguriert, WHMCS ist vom Perfex-Server aus nicht erreichbar, oder die WHMCS-Installation läuft im Free-Plan
Textfeld, "Connection OK, but WHMCS has no support departments yet"Der Abruf hat funktioniert. Legen Sie in WHMCS unter Support > Support Departments Abteilungen an und laden Sie diese Seite anschließend neu

Der Abruf ist auf wenige Sekunden begrenzt, ein nicht erreichbares WHMCS verlangsamt die Einstellungsseite also geringfügig, blockiert sie aber nie.

Das manuelle Format ist eine Zuordnung je Zeile, links die WHMCS-Abteilungs-ID, rechts die Perfex-Abteilungs-ID:

1=2
2=5
3=5

Werden Dropdowns angezeigt, öffnet der Link Advanced: edit the mapping manually dasselbe Textfeld. Solange dieser manuelle Editor geöffnet ist, wird sein Text gespeichert und überschreibt die Auswahl in den Dropdowns.

Die Auflösungsreihenfolge für die Abteilung eines eingehenden Tickets:

  1. Eine exakte Übereinstimmung in der Zuordnung.
  2. Andernfalls die konfigurierte Default department.
  3. Andernfalls die niedrigste Perfex-Abteilungs-ID, automatisch gewählt.

Ein Tippfehler in einer Zuordnungszeile führt sauber auf den Rückfallwert. Er verhindert weder das Speichern noch die Synchronisierung.

Auf der Aufgabe je Ticket erfasste Zeit bleibt in Perfex

Die optionale Perfex-Aufgabe existiert, damit Ihre Mitarbeitenden die nativen Perfex-Timesheets für ein Ticket nutzen können. Diese Zeiteinträge werden nicht zurück nach WHMCS synchronisiert, und die Aufgabe wird nicht automatisch geschlossen, wenn das Ticket geschlossen wird.

Panels auf derselben Seite

Die rechte Spalte von Setup > WHMCS Bridge enthält drei schreibgeschützte Panels:

  • WHMCS plan - welchen Plan die WHMCS-Seite zuletzt gemeldet hat (Pro, Free oder Unknown), wann die Lizenz zuletzt geprüft wurde, und eine Schaltfläche Upgrade to Pro, sofern es etwas zu kaufen gibt.
  • Outbound queue - Änderungen der Perfex-Seite, die auf die Übertragung nach WHMCS warten, mit den Zählern für ausstehende und tote Einträge, Wiederholungszahlen, dem Zeitpunkt des nächsten Versuchs und dem letzten Fehler je Zeile.
  • Recent inbound events - was WHMCS an diese Perfex-Installation gesendet hat, mit Status und Meldung.

Das sind Ihre Diagnosewerkzeuge auf der Perfex-Seite. Siehe Funktionsweise und täglicher Betrieb.

Die Setup checklist, Zeile für Zeile

Die WHMCS-Modulseite öffnet sich mit einer sechszeiligen Setup checklist. Jede Zeile trägt ein grünes Häkchen, eine gelbe Warnung, ein rotes Kreuz oder einen grauen Strich, dazu einen einzeiligen Hinweis. Durchgehend Grün, mit Grau in der Lizenzzeile, wenn Sie den Free-Plan nutzen, bedeutet, dass die Bridge gesund ist.

ZeileGrün bedeutetAlles andere bedeutet
Module tables presentDie Tabellen für Outbox, Zuordnung und Protokoll existieren alle.🔴 Eine Tabelle fehlt. Deaktivieren und reaktivieren Sie das Modul unter System Settings > Addon Modules, um sie neu anzulegen.
Connection configuredDie Perfex-URL und das gemeinsame Secret sind beide gesetzt.🔴 Noch nicht gesetzt. Fügen Sie einen Connection code in Quick setup ein, oder füllen Sie beide Felder unter Settings > Connection aus.
Connection verifiedEin signierter Ping hat ein pong zurückerhalten, und die Zeile zeigt, wie lange das her ist.🔴 Die letzte Prüfung ist fehlgeschlagen, und die Zeile nennt den Fehler. Beheben Sie ihn und klicken Sie dann auf Test Connection. ⚪ Nie geprüft, oder die letzte Prüfung liegt mehr als 24 Stunden zurück. Klicken Sie auf Test Connection, um sie aufzufrischen.
Sync enabledDie ausgehende Auslieferung ist eingeschaltet.🔴 Die Synchronisierung ist pausiert. Ereignisse werden weiter eingereiht, aber nicht ausgeliefert. Haken Sie Enable Sync unter Settings > Sync behaviour an und speichern Sie.
Cron deliveringDer WHMCS-System-Cron hat kürzlich echte Bridge-Arbeit erledigt, und die Zeile zeigt, wie kürzlich.🟠 Seit einiger Zeit keine Cron-Aktivität. Prüfen Sie, ob der WHMCS-System-Cron läuft. 🔴 Es wurde noch nie Cron-Aktivität protokolliert. Bei einer brandneuen Installation ist das bis zur ersten Auslieferung normal; hält es an, läuft Ihr Cron nicht.
License / planPro ist aktiv.⚪ Kein Lizenzschlüssel, also der Free-Plan, was eine vollkommen unterstützte Betriebsart dieses Moduls ist. 🔴 Ein Schlüssel ist gesetzt, wird aber nicht validiert. Prüfen Sie den Schlüssel und klicken Sie dann auf Check licence now.
Die Zeile "Cron delivering" lässt sich bewusst nur schwer vortäuschen

Nur ein echter Durchlauf des WHMCS-System-Crons färbt diese Zeile grün. Run Sync Now liefert Ihre eingereihten Ereignisse aus und belegt, dass die Auslieferung funktioniert, rührt diese Zeile aber nicht an. Genau darum geht es: Die Zeile beantwortet die Frage "Funktioniert das auch weiter, wenn niemand zusieht?", und ein Tastendruck kann diese Frage nicht beantworten.

Die Zeile verfolgt tatsächliche Bridge-Arbeit: das Leeren der Warteschlange, das Aufräumen der Protokolle und Abgleichläufe. Eine lange untätige, aber vollkommen gesunde Installation kann daher gelb stehen, ohne dass es etwas zu beheben gäbe - schlicht, weil es nichts zu tun gab.

Sowohl Connect (Kopplung) als auch Test Connection frischen die Zeile Connection verified auf.

Wie es weitergeht