# KeyHelp Manager - WHMCS Provisioning Modul

Ein professionelles WHMCS-Provisioning-Modul für die automatische Verwaltung von KeyHelp-Webhosting-Accounts.

**Entwickelt von:** Kevin Feiler / AVVGO  
**Website:** https://avvgo.de  
**Version:** 2.0.0

## 🆕 NEU in Version 2.0.0

- 🎯 **Zentralisierte Server-Konfiguration** - API-Keys nur einmal in WHMCS Server-Einstellungen eintragen
- 📋 **Template/Vorlagen-System** - Automatische Synchronisation von KeyHelp-Plänen als Dropdown
- 🚀 **Template-basierte Provisionierung** - Domains werden automatisch mit gewählter Vorlage erstellt
- 🔗 **Admin-Panel-Link** - Direkter Zugriff zur Domain-Verwaltung im KeyHelp-Panel
- 📊 **Template-Anzeige** - Kunden sehen ihr verwendetes Template im Client Area

**[→ Update-Anleitung von v1.x auf v2.0](UPDATE.md)**

## 📋 Inhaltsverzeichnis

- [Features](#features)
- [Systemanforderungen](#systemanforderungen)
- [Installation](#installation)
- [Konfiguration](#konfiguration)
- [Verwendung](#verwendung)
- [API-Endpunkte](#api-endpunkte)
- [Fehlerbehebung](#fehlerbehebung)
- [Support](#support)

## ✨ Features

### Core Features
- ✅ **Automatische Account-Erstellung** - Erstellt KeyHelp-Accounts direkt nach der Bezahlung
- ✅ **Account-Verwaltung** - Sperren, Entsperren und Löschen von Accounts
- ✅ **Passwort-Management** - Sichere Passwortverwaltung und -änderung
- ✅ **Client-Area-Integration** - Übersichtliche Darstellung von Login-Daten und Statistiken
- ✅ **Single Sign-On** - Ein-Klick-Login für Admins direkt in den Kundenaccount
- ✅ **Live-Statistiken** - Echtzeit-Anzeige von Speicherplatz, Traffic, Domains, etc.
- ✅ **SSL-Unterstützung** - Sichere HTTPS-Verbindungen zur KeyHelp-API
- ✅ **Detailliertes Logging** - Alle API-Calls werden in WHMCS protokolliert
- ✅ **Fehlerbehandlung** - Robuste Error-Handling-Mechanismen

### Neue Features v2.0
- 🎯 **Zentralisierte API-Konfiguration** - API-Keys werden nur einmal in WHMCS Server-Einstellungen eingegeben
- 📋 **Template-Synchronisation** - KeyHelp-Pläne/Vorlagen werden automatisch als Dropdown geladen
- 🔄 **Sync Templates Button** - Manuelles Aktualisieren der verfügbaren Templates
- 🏷️ **Template-basierte Erstellung** - Accounts werden mit gewähltem Template/Plan erstellt
- 🔗 **Admin-Panel-Link** - Direkter Link zur Domain-Verwaltung im KeyHelp-Panel
- 📊 **Template-Anzeige** - Template-Name wird im Client Area angezeigt
- ⚡ **Template-Cache** - Bessere Performance durch 5-Minuten-Cache
- 🎨 **Verbessertes UI** - Übersichtlichere Button-Anordnung und Design

## 🔧 Systemanforderungen

### WHMCS-Server
- **WHMCS:** Version 8.13 oder höher
- **PHP:** Version 8.3 oder höher
- **Guzzle HTTP Client:** Wird von WHMCS mitgeliefert
- **MySQL/MariaDB:** Von WHMCS unterstützte Version

### KeyHelp-Server
- **KeyHelp:** Neueste stabile Version (mit API v2)
- **API-Zugang:** API-Key mit Admin-Rechten
- **SSL-Zertifikat:** Empfohlen für sichere API-Kommunikation

## 📦 Installation

### Schritt 1: Dateien hochladen

1. Laden Sie das komplette `keyhelpmanager`-Verzeichnis in Ihr WHMCS-Installationsverzeichnis hoch:

```
/pfad/zu/whmcs/modules/servers/keyhelpmanager/
```

Die Verzeichnisstruktur sollte wie folgt aussehen:

```
whmcs/
└── modules/
    └── servers/
        └── keyhelpmanager/
            ├── keyhelpmanager.php
            └── templates/
                └── clientarea.tpl
```

### Schritt 2: Dateirechte setzen

Stellen Sie sicher, dass die Dateien die korrekten Rechte haben:

```bash
chmod 644 modules/servers/keyhelpmanager/keyhelpmanager.php
chmod 644 modules/servers/keyhelpmanager/templates/clientarea.tpl
chmod 755 modules/servers/keyhelpmanager/
```

### Schritt 3: KeyHelp API-Key generieren

1. Loggen Sie sich in Ihr KeyHelp-Panel ein
2. Navigieren Sie zu **Einstellungen → API**
3. Erstellen Sie einen neuen API-Key mit **Admin-Rechten**
4. Kopieren Sie den generierten API-Key (wird nur einmal angezeigt!)

### Schritt 4: Server in WHMCS hinzufügen

1. Loggen Sie sich in den WHMCS-Admin-Bereich ein
2. Navigieren Sie zu **Setup → Products/Services → Servers**
3. Klicken Sie auf **Add New Server**
4. Füllen Sie die Felder aus:
   - **Name:** z.B. "KeyHelp Server 1"
   - **Hostname:** IP-Adresse oder FQDN Ihres KeyHelp-Servers (ohne http://)
   - **Type:** Wählen Sie **KeyHelp Manager**
   - **Username:** Kann leer bleiben
   - **Password:** Tragen Sie hier Ihren **API-Key** ein
   - **Accesshash:** Kann leer bleiben
   - **Secure:** Aktivieren Sie dies, wenn Sie SSL verwenden

5. Klicken Sie auf **Test Connection** um die Verbindung zu prüfen
6. Speichern Sie die Konfiguration

### Schritt 5: Produkt/Service erstellen

1. Navigieren Sie zu **Setup → Products/Services → Products/Services**
2. Erstellen Sie ein neues Produkt oder bearbeiten Sie ein bestehendes
3. Im Tab **Module Settings**:
   - **Module Name:** Wählen Sie **KeyHelp Manager**
   - **Server:** Wählen Sie Ihren KeyHelp-Server
   - Konfigurieren Sie die Modul-Einstellungen (siehe unten)

4. Speichern Sie das Produkt

## ⚙️ Konfiguration

### Server-Konfigurationsoptionen

Bei der Einrichtung des Servers in WHMCS können Sie folgende Optionen konfigurieren:

| Option | Typ | Beschreibung | Standard |
|--------|-----|--------------|----------|
| **Hostname (IP or FQDN)** | Text | Hostname oder IP-Adresse des KeyHelp-Servers | - |
| **API Key** | Password | Ihr KeyHelp API-Schlüssel | - |
| **Use SSL** | Yes/No | SSL für API-Verbindungen verwenden | On |
| **HTTP Prefix** | Text | Optional: "no-verify" für manuelles Deaktivieren der SSL-Verifizierung | - |

> **Hinweis zur SSL-Verifizierung:** 
> - Bei Verwendung einer **IP-Adresse** wird die SSL-Verifizierung automatisch deaktiviert
> - Bei selbstsignierten SSL-Zertifikaten mit Domain-Namen: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein
> - Für Produktivumgebungen wird immer ein gültiges SSL-Zertifikat empfohlen

### Produkt-Konfiguration

#### Automatische Werte

Das Modul verwendet automatisch folgende Werte aus WHMCS:

- **Domain:** Die vom Kunden gewählte Domain
- **Username:** Automatisch generiert aus der Domain (oder manuell festgelegt)
- **Password:** Automatisch generiert (sicheres 16-stelliges Passwort)
- **E-Mail:** Aus den Kundendaten

#### Konfigurierbare Optionen (Optional)

Sie können zusätzliche konfigurierbare Optionen für KeyHelp-Pläne erstellen:

1. Navigieren Sie zu **Setup → Products/Services → Configurable Options**
2. Erstellen Sie eine neue Konfigurationsgruppe
3. Fügen Sie eine Option hinzu:
   - **Option Name:** "KeyHelp Plan"
   - **Option Type:** Dropdown/Radio
   - **Options:** Liste Ihrer KeyHelp-Pläne (z.B. "Basic", "Professional", "Enterprise")

4. Verknüpfen Sie die Konfigurationsgruppe mit Ihrem Produkt

### Custom Fields (Automatisch erstellt)

Das Modul erstellt automatisch folgendes Custom Field:

- **KeyHelp User ID** - Speichert die interne KeyHelp-User-ID (Admin-only)

## 🚀 Verwendung

### Für Kunden (Client Area)

Nachdem ein Kunde das Produkt bestellt und bezahlt hat:

1. Der Account wird automatisch in KeyHelp erstellt
2. Im **Services**-Bereich sieht der Kunde:
   - KeyHelp Login-URL
   - Benutzername und Passwort (mit Copy-Funktion)
   - Domain-Name
   - Live-Statistiken (Speicherplatz, Traffic, Anzahl Domains/DBs/E-Mails)
   - "Jetzt zu KeyHelp einloggen"-Button

### Für Admins

Im WHMCS-Admin-Bereich haben Sie folgende Optionen:

#### Account-Verwaltung

- **Create** - Erstellt einen neuen KeyHelp-Account
- **Suspend** - Sperrt den Account (bei Zahlungsverzug)
- **Unsuspend** - Entsperrt einen gesperrten Account
- **Terminate** - Löscht den Account unwiderruflich
- **Change Password** - Ändert das Account-Passwort

#### Single Sign-On

Klicken Sie auf den "Login zu KeyHelp"-Button neben dem Service, um sich direkt als der jeweilige Kunde in KeyHelp einzuloggen (ohne Passwort).

## 🔌 API-Endpunkte

Das Modul verwendet folgende KeyHelp API v2 Endpunkte:

### Benutzer-Verwaltung

- `POST /api/v2/users` - Benutzer erstellen
- `GET /api/v2/users/{id}` - Benutzer-Details abrufen
- `PUT /api/v2/users/{id}` - Benutzer aktualisieren (Passwort, Status)
- `DELETE /api/v2/users/{id}` - Benutzer löschen

### Domain-Verwaltung

- `POST /api/v2/domains` - Domain hinzufügen
- `GET /api/v2/domains/{id}` - Domain-Details abrufen

### Statistiken

- `GET /api/v2/users/{id}/statistics` - Account-Statistiken abrufen

### Sessions (SSO)

- `POST /api/v2/sessions` - Login-Session erstellen

### Server-Informationen

- `GET /api/v2/server/version` - Server-Version abrufen (für Connection-Test)

## 🔍 Funktionsweise

### Account-Erstellung

```
Kunde bestellt → WHMCS aktiviert Service → keyhelpmanager_CreateAccount()
    ↓
1. Validiere Parameter (Domain, Username, etc.)
2. Generiere sicheres Passwort falls nicht vorhanden
3. API-Call: POST /users (Benutzer erstellen)
4. API-Call: POST /domains (Domain hinzufügen)
5. Speichere Credentials in WHMCS-Datenbank
6. Return "success"
    ↓
Kunde erhält Zugriff auf Service mit Login-Daten
```

### Account-Sperrung

```
Admin sperrt Account → keyhelpmanager_SuspendAccount()
    ↓
1. Hole User-ID aus WHMCS-Datenbank
2. API-Call: PUT /users/{id} mit {"is_locked": true}
3. Return "success"
    ↓
Kunde kann sich nicht mehr in KeyHelp einloggen
```

### Client Area

```
Kunde öffnet Service → keyhelpmanager_ClientArea()
    ↓
1. Lade Account-Details aus WHMCS-Datenbank
2. API-Call: GET /users/{id}/statistics (Live-Daten)
3. Formatiere Daten (Bytes → MB/GB, Prozentangaben)
4. Return Template-Variablen
    ↓
Smarty-Template rendert die Anzeige
```

### Single Sign-On

```
Admin klickt auf "Login" → keyhelpmanager_LoginLink()
    ↓
1. Hole User-ID aus WHMCS-Datenbank
2. API-Call: POST /sessions mit User-ID
3. Erhalte Session-Token
4. Erstelle Login-URL mit Token
5. Return Redirect-URL
    ↓
Admin wird direkt in KeyHelp eingeloggt
```

## 🐛 Fehlerbehebung

### "KeyHelp-Hostname ist nicht konfiguriert"

**Lösung:** Stellen Sie sicher, dass Sie den Hostname/IP in der Server-Konfiguration eingetragen haben (ohne `http://` oder `https://`).

### "KeyHelp API-Schlüssel ist nicht konfiguriert"

**Lösung:** 
1. Generieren Sie einen neuen API-Key in KeyHelp
2. Tragen Sie ihn im **Password**-Feld der Server-Konfiguration ein

### "Verbindung zum KeyHelp-Server fehlgeschlagen"

**Mögliche Ursachen:**
- Firewall blockiert Verbindung
- Falscher Hostname/IP
- KeyHelp-Server ist nicht erreichbar
- SSL-Zertifikat-Problem bei selbstsigniertem Zertifikat

**Lösung:**
1. Prüfen Sie die Firewall-Einstellungen
2. Testen Sie die Verbindung manuell: `curl -k https://ihr-server.de/api/v2/server/version -H "X-API-Key: IHR_KEY"`
3. Bei selbstsigniertem Zertifikat: Tragen Sie "no-verify" im Feld "HTTP Prefix" ein

### "cURL error 60: SSL certificate problem"

**Ursache:** SSL-Zertifikat stimmt nicht mit dem Hostnamen überein (häufig bei IP-Adressen oder selbstsignierten Zertifikaten)

**Lösung:**
1. **Bei IP-Adresse:** Das Modul deaktiviert die SSL-Verifizierung automatisch
2. **Bei selbstsigniertem Zertifikat mit Domain:** Tragen Sie "no-verify" im Feld "HTTP Prefix" der Server-Konfiguration ein
3. **Empfohlen für Produktion:** Verwenden Sie ein gültiges SSL-Zertifikat von Let's Encrypt oder einem anderen CA

### "Domain konnte nicht hinzugefügt werden"

**Mögliche Ursachen:**
- Domain existiert bereits in KeyHelp
- Ungültiges Domain-Format
- DNS-Probleme

**Lösung:**
1. Prüfen Sie, ob die Domain bereits in KeyHelp existiert
2. Validieren Sie das Domain-Format (keine Leerzeichen, gültige TLD)

### "Benutzer-ID nicht gefunden"

**Ursache:** Der Account wurde nicht korrekt erstellt oder die Custom Fields fehlen.

**Lösung:**
1. Prüfen Sie das WHMCS Module Log: **Utilities → Logs → Module Log**
2. Erstellen Sie den Account manuell neu
3. Stellen Sie sicher, dass das Custom Field "KeyHelp User ID" existiert

### Logs prüfen

WHMCS protokolliert alle API-Calls:

1. Navigieren Sie zu **Utilities → Logs → Module Log**
2. Filtern Sie nach "keyhelpmanager"
3. Prüfen Sie Request und Response für Details

## 📊 Logging

Das Modul nutzt die integrierte WHMCS `logModuleCall()`-Funktion:

- **Modul-Name:** keyhelpmanager
- **Protokolliert:** Alle API-Requests und Responses
- **Maskiert:** API-Keys werden automatisch maskiert
- **Speicherort:** WHMCS → Utilities → Logs → Module Log

## 🔒 Sicherheit

### Best Practices

1. **Verwenden Sie immer SSL** für API-Verbindungen
2. **API-Key-Schutz:** 
   - Teilen Sie Ihren API-Key niemals mit Dritten
   - Speichern Sie ihn nur im WHMCS-Server-Passwort-Feld
   - WHMCS verschlüsselt dieses Feld automatisch
3. **Regelmäßige Updates:** Halten Sie WHMCS und KeyHelp auf dem neuesten Stand
4. **Firewall:** Beschränken Sie den API-Zugriff auf die IP Ihres WHMCS-Servers
5. **2FA:** Aktivieren Sie Zwei-Faktor-Authentifizierung für KeyHelp-Admin-Accounts

### Passwort-Generierung

Das Modul generiert sichere Passwörter:
- **Länge:** 16 Zeichen
- **Zeichensatz:** a-z, A-Z, 0-9, Sonderzeichen
- **Methode:** `random_int()` (kryptografisch sicher)

## 🆘 Support

### Dokumentation

- **KeyHelp Dokumentation:** https://www.keyhelp.de/dokumentation
- **WHMCS Developer Docs:** https://developers.whmcs.com/

### Debugging

Bei Problemen:

1. Aktivieren Sie das Debug-Logging in WHMCS
2. Prüfen Sie die Module Logs
3. Testen Sie die API-Verbindung manuell
4. Prüfen Sie die PHP-Error-Logs

### Community

- **KeyHelp Forum:** https://forum.keyhelp.de/
- **WHMCS Community:** https://whmcs.community/

## 📝 Changelog

### Version 1.0.0 (Initial Release)

- ✅ Basis-Funktionalität: Create, Suspend, Unsuspend, Terminate
- ✅ Client Area mit Login-Details und Statistiken
- ✅ Admin Single Sign-On
- ✅ Passwort-Management
- ✅ SSL-Unterstützung
- ✅ Umfassendes Error-Handling
- ✅ Smarty-Template für Client Area
- ✅ API v2 Unterstützung

## 👨‍💻 Entwickler

Dieses Modul wurde entwickelt von:

- **Name:** Kevin Feiler
- **Firma:** AVVGO
- **Website:** https://avvgo.de
- **E-Mail:** info@avvgo.de

## 📜 Lizenz

MIT License - Copyright (c) 2024 Kevin Feiler / AVVGO

Siehe LICENSE-Datei für vollständige Details.

## 🔧 Technische Anforderungen

- **PHP:** 8.3+
- **WHMCS:** 8.13+
- **KeyHelp:** Neueste stabile Version mit API v2

## 💬 Support & Kontakt

Bei Fragen, Problemen oder Feature-Wünschen:

- **E-Mail:** info@avvgo.de
- **Website:** https://avvgo.de
- **GitHub Issues:** Für Bug-Reports und Feature-Requests

---

**Hinweis:** Dieses Modul wurde mit Fokus auf Stabilität, Sicherheit und Benutzerfreundlichkeit entwickelt von Kevin Feiler / AVVGO.