diff --git a/CHANGELOG.md b/CHANGELOG.md index abef9ca..e802a2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,14 @@ und dieses Projekt folgt [Semantic Versioning](https://semver.org/lang/de/). ## [Unreleased] +### Behoben +- **API-Endpunkte korrigiert:** + - ✅ Alle `/users` Endpunkte auf korrekte `/clients` Endpunkte umgestellt + - ✅ Parameter `user_id` auf `id_client` korrigiert + - ✅ Parameter `plan_id` auf `id_hosting_plan` korrigiert + - ✅ Behebt "Endpoint not found" Fehler beim Server hinzufügen + - KeyHelp API verwendet `/clients`, nicht `/users` + ### Hinzugefügt - **Automatische SSL-Verifizierung bei IP-Adressen:** - SSL-Verifizierung wird automatisch deaktiviert wenn eine IP-Adresse als Hostname verwendet wird @@ -14,10 +22,17 @@ und dieses Projekt folgt [Semantic Versioning](https://semver.org/lang/de/). - Manuelle Deaktivierung möglich über HTTP Prefix "no-verify" - Logging-Hinweis wenn SSL-Verifizierung deaktiviert wird +- **Template-System mit Fallback:** + - Automatischer Fallback auf "Manual Configuration" wenn `/plans` Endpunkt nicht verfügbar + - Kompatibel mit KeyHelp Free (ohne Hosting-Pläne) + - Optional: Hosting-Pläne wenn verfügbar (KeyHelp Pro) + ### Dokumentation +- Neue Datei `KEYHELP_API_REFERENCE.md` mit vollständiger API-Dokumentation - Neue Datei `SSL_TROUBLESHOOTING.md` mit umfassender SSL-Fehlerbehandlung - README.md erweitert um SSL-Konfigurationshinweise - QUICKSTART.md aktualisiert mit SSL-Best-Practices +- Korrekte API-Endpunkte und Parameter dokumentiert ### Geplant - Multi-Language Support (Deutsch/Englisch) diff --git a/KEYHELP_API_REFERENCE.md b/KEYHELP_API_REFERENCE.md new file mode 100644 index 0000000..016e15d --- /dev/null +++ b/KEYHELP_API_REFERENCE.md @@ -0,0 +1,455 @@ +# KeyHelp API v2 Referenz + +Diese Datei dokumentiert die tatsächlich verwendeten KeyHelp API v2 Endpunkte und Parameter. + +## Offizielle Dokumentation + +- **Swagger API Docs:** https://app.swaggerhub.com/apis-docs/keyhelp/api/2.12 +- **KeyHelp Wiki:** https://wiki.keyhelp.de/books/api + +## Wichtige Unterschiede + +⚠️ **ACHTUNG:** KeyHelp verwendet `/clients` statt `/users`! + +## Verwendete Endpunkte + +### 1. Client (Benutzer) erstellen + +**Endpunkt:** `POST /api/v2/clients` + +**Request Body:** +```json +{ + "login_name": "example_com", + "password": "SecurePassword123!", + "email": "user@example.com", + "display_name": "Max Mustermann", + "id_hosting_plan": 5 // Optional: Hosting-Plan ID +} +``` + +**Response:** +```json +{ + "id": 42, + "login_name": "example_com", + "email": "user@example.com", + "display_name": "Max Mustermann", + "is_locked": false, + "created_at": "2024-01-20 10:30:00" +} +``` + +**Verwendung im Modul:** `keyhelpmanager_CreateAccount()` + +--- + +### 2. Client-Details abrufen + +**Endpunkt:** `GET /api/v2/clients/{id}` + +**Response:** +```json +{ + "id": 42, + "login_name": "example_com", + "email": "user@example.com", + "display_name": "Max Mustermann", + "is_locked": false, + "id_hosting_plan": 5, + "created_at": "2024-01-20 10:30:00", + "updated_at": "2024-01-20 10:30:00" +} +``` + +**Verwendung im Modul:** Integriert in verschiedenen Funktionen + +--- + +### 3. Client aktualisieren + +**Endpunkt:** `PUT /api/v2/clients/{id}` + +**Request Body (Beispiele):** + +**Passwort ändern:** +```json +{ + "password": "NewSecurePassword456!" +} +``` + +**Client sperren:** +```json +{ + "is_locked": true +} +``` + +**Client entsperren:** +```json +{ + "is_locked": false +} +``` + +**Verwendung im Modul:** +- `keyhelpmanager_SuspendAccount()` - Client sperren +- `keyhelpmanager_UnsuspendAccount()` - Client entsperren +- `keyhelpmanager_ChangePassword()` - Passwort ändern + +--- + +### 4. Client löschen + +**Endpunkt:** `DELETE /api/v2/clients/{id}` + +**Response:** `204 No Content` bei Erfolg + +**Verwendung im Modul:** `keyhelpmanager_TerminateAccount()` + +--- + +### 5. Domain erstellen + +**Endpunkt:** `POST /api/v2/domains` + +**Request Body:** +```json +{ + "domain_name": "example.com", + "id_client": 42 +} +``` + +**Response:** +```json +{ + "id": 123, + "domain_name": "example.com", + "id_client": 42, + "document_root": "/home/example_com/www", + "created_at": "2024-01-20 10:30:00" +} +``` + +**Hinweis:** Template/Hosting-Plan wird über den Client angewendet, nicht über die Domain! + +**Verwendung im Modul:** `keyhelpmanager_CreateAccount()` + +--- + +### 6. Domain-Details abrufen + +**Endpunkt:** `GET /api/v2/domains/{id}` + +**Response:** +```json +{ + "id": 123, + "domain_name": "example.com", + "id_client": 42, + "document_root": "/home/example_com/www", + "php_version": "8.2", + "is_enabled": true, + "created_at": "2024-01-20 10:30:00", + "updated_at": "2024-01-20 10:30:00" +} +``` + +**Verwendung im Modul:** Integriert in verschiedenen Funktionen + +--- + +### 7. Client-Statistiken abrufen + +**Endpunkt:** `GET /api/v2/clients/{id}/statistics` + +**Response:** +```json +{ + "disk_usage": 2415919104, + "disk_quota": 5368709120, + "traffic_usage": 16106127360, + "traffic_quota": 107374182400, + "domain_count": 3, + "database_count": 2, + "email_count": 5 +} +``` + +**Hinweis:** Werte sind in Bytes + +**Verwendung im Modul:** `keyhelpmanager_ClientArea()` + +--- + +### 8. Session erstellen (SSO) + +**Endpunkt:** `POST /api/v2/sessions` + +**Request Body:** +```json +{ + "id_client": 42 +} +``` + +**Response:** +```json +{ + "token": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz", + "expires_at": "2024-01-20 10:35:00" +} +``` + +**Login-URL Format:** +``` +https://your-keyhelp-server.com/login?token={token} +``` + +**Verwendung im Modul:** `keyhelpmanager_LoginLink()` + +--- + +### 9. Server-Version prüfen (Connection Test) + +**Endpunkt:** `GET /api/v2/server/version` + +**Response:** +```json +{ + "version": "24.3.1", + "build": "3456" +} +``` + +**Verwendung im Modul:** `keyhelpmanager_TestConnection()` + +--- + +### 10. Hosting-Pläne abrufen (Optional - KeyHelp Pro) + +**Endpunkt:** `GET /api/v2/hosting-plans` + +**Response:** +```json +[ + { + "id": 1, + "name": "Basic Plan", + "disk_quota": 5368709120, + "traffic_quota": 107374182400, + "max_domains": 3, + "max_databases": 5, + "max_email_accounts": 10 + }, + { + "id": 2, + "name": "Pro Plan", + "disk_quota": 21474836480, + "traffic_quota": 429496729600, + "max_domains": 10, + "max_databases": 20, + "max_email_accounts": 50 + } +] +``` + +**Hinweis:** Dieser Endpunkt ist möglicherweise nur in KeyHelp Pro verfügbar! + +**Verwendung im Modul:** `_keyhelpmanager_GetTemplates()` - mit Fallback auf manuelle Konfiguration + +--- + +## API-Authentifizierung + +Alle Requests benötigen einen API-Key im Header: + +``` +X-API-Key: your-api-key-here +Content-Type: application/json +Accept: application/json +``` + +## Fehlerbehandlung + +### Typische Fehler-Responses + +**404 Not Found:** +```json +{ + "error": "Endpoint not found" +} +``` + +**401 Unauthorized:** +```json +{ + "error": "Invalid API key" +} +``` + +**400 Bad Request:** +```json +{ + "error": "Validation failed", + "details": { + "login_name": "This field is required", + "email": "Invalid email format" + } +} +``` + +**500 Internal Server Error:** +```json +{ + "error": "Internal server error" +} +``` + +--- + +## SSL/TLS-Konfiguration + +### Empfohlene Einstellungen + +**Produktion:** +``` +https://your-domain.com +SSL-Verifizierung: ON +``` + +**Entwicklung/Test mit IP:** +``` +https://5.83.148.129 +SSL-Verifizierung: Automatisch deaktiviert (IP-Erkennung) +``` + +**Selbstsigniertes Zertifikat:** +``` +https://your-domain.com +HTTP Prefix: no-verify +``` + +--- + +## Häufige Probleme + +### 1. "Endpoint not found" bei `/users` + +**Problem:** KeyHelp verwendet `/clients`, nicht `/users` + +**Lösung:** Alle Endpunkte verwenden `/clients` + +### 2. "Endpoint not found" bei `/plans` oder `/hosting-plans` + +**Problem:** Endpunkt existiert nur in KeyHelp Pro oder älteren Versionen + +**Lösung:** Modul nutzt automatisch "Manual Configuration" als Fallback + +### 3. SSL-Zertifikat-Fehler bei IP-Adressen + +**Problem:** SSL-Zertifikat ist für Domain ausgestellt, nicht für IP + +**Lösung:** Modul erkennt IP-Adressen automatisch und deaktiviert SSL-Verifizierung + +### 4. Parameter-Namen falsch + +**Häufige Fehler:** +- ❌ `user_id` → ✅ `id_client` +- ❌ `plan_id` → ✅ `id_hosting_plan` +- ❌ `template_id` → ✅ Nicht bei Domains verwenden + +--- + +## Code-Beispiele + +### cURL-Beispiel: Client erstellen + +```bash +curl -X POST https://your-keyhelp-server.com/api/v2/clients \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "login_name": "testuser", + "password": "SecurePass123!", + "email": "test@example.com", + "display_name": "Test User" + }' +``` + +### cURL-Beispiel: Domain erstellen + +```bash +curl -X POST https://your-keyhelp-server.com/api/v2/domains \ + -H "X-API-Key: your-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "domain_name": "example.com", + "id_client": 42 + }' +``` + +### cURL-Beispiel: Statistiken abrufen + +```bash +curl -X GET https://your-keyhelp-server.com/api/v2/clients/42/statistics \ + -H "X-API-Key: your-api-key" \ + -H "Accept: application/json" +``` + +### PHP-Beispiel mit Guzzle + +```php +use GuzzleHttp\Client; + +$client = new Client([ + 'base_uri' => 'https://your-keyhelp-server.com', + 'verify' => true, // oder false bei selbstsigniertem Zert + 'timeout' => 30, +]); + +$response = $client->post('/api/v2/clients', [ + 'headers' => [ + 'X-API-Key' => 'your-api-key', + 'Content-Type' => 'application/json', + 'Accept' => 'application/json', + ], + 'json' => [ + 'login_name' => 'testuser', + 'password' => 'SecurePass123!', + 'email' => 'test@example.com', + 'display_name' => 'Test User', + ], +]); + +$data = json_decode($response->getBody(), true); +$clientId = $data['id']; +``` + +--- + +## Versionsinformationen + +- **KeyHelp API Version:** 2.12+ +- **Modul Version:** 2.0.0 +- **Letzte Aktualisierung:** 2024 + +--- + +## Support & Feedback + +Bei Fragen zur KeyHelp API: +- **KeyHelp Forum:** https://community.keyhelp.de/ +- **KeyHelp Wiki:** https://wiki.keyhelp.de/ +- **KeyHelp Support:** support@keyhelp.de + +Bei Fragen zum WHMCS-Modul: +- **E-Mail:** info@avvgo.de +- **Website:** https://avvgo.de + +--- + +**Entwickelt von:** Kevin Feiler / AVVGO +**Lizenz:** MIT \ No newline at end of file diff --git a/modules/servers/keyhelpmanager.zip b/modules/servers/keyhelpmanager.zip deleted file mode 100644 index 6f7bae5..0000000 Binary files a/modules/servers/keyhelpmanager.zip and /dev/null differ diff --git a/modules/servers/keyhelpmanager/keyhelpmanager.php b/modules/servers/keyhelpmanager/keyhelpmanager.php index 02fdde0..d7d0744 100644 --- a/modules/servers/keyhelpmanager/keyhelpmanager.php +++ b/modules/servers/keyhelpmanager/keyhelpmanager.php @@ -179,12 +179,12 @@ function keyhelpmanager_CreateAccount(array $params) // Use template if selected (skip if manual or empty) if (!empty($templateId) && $templateId !== "manual") { - $accountData["plan_id"] = $templateId; + $accountData["id_hosting_plan"] = $templateId; } $result = _keyhelpmanager_APIRequest( $params, - "/users", + "/clients", "POST", $accountData, ); @@ -200,12 +200,9 @@ function keyhelpmanager_CreateAccount(array $params) } // Create domain with template settings - $domainData = ["domain_name" => $domain, "user_id" => $userId]; + $domainData = ["domain_name" => $domain, "id_client" => $userId]; - // Only add template_id if it's set and not manual mode - if (!empty($templateId) && $templateId !== "manual") { - $domainData["template_id"] = $templateId; - } + // KeyHelp API doesn't use template_id for domains, template is applied via user $domainResult = _keyhelpmanager_APIRequest( $params, @@ -215,7 +212,7 @@ function keyhelpmanager_CreateAccount(array $params) ); if (!$domainResult["success"]) { - _keyhelpmanager_APIRequest($params, "/users/" . $userId, "DELETE"); + _keyhelpmanager_APIRequest($params, "/clients/" . $userId, "DELETE"); return "Domain creation failed: " . $domainResult["error"]; } @@ -247,7 +244,7 @@ function keyhelpmanager_SuspendAccount(array $params) $result = _keyhelpmanager_APIRequest( $params, - "/users/" . $userId, + "/clients/" . $userId, "PUT", ["is_locked" => true], ); @@ -269,7 +266,7 @@ function keyhelpmanager_UnsuspendAccount(array $params) $result = _keyhelpmanager_APIRequest( $params, - "/users/" . $userId, + "/clients/" . $userId, "PUT", ["is_locked" => false], ); @@ -291,7 +288,7 @@ function keyhelpmanager_TerminateAccount(array $params) $result = _keyhelpmanager_APIRequest( $params, - "/users/" . $userId, + "/clients/" . $userId, "DELETE", ); @@ -366,7 +363,7 @@ function keyhelpmanager_ClientArea(array $params) if (!empty($userId)) { $statsResult = _keyhelpmanager_APIRequest( $params, - "/users/" . $userId . "/statistics", + "/clients/" . $userId . "/statistics", "GET", ); @@ -489,7 +486,7 @@ function keyhelpmanager_ChangePassword(array $params) $result = _keyhelpmanager_APIRequest( $params, - "/users/" . $userId, + "/clients/" . $userId, "PUT", ["password" => $newPassword], );