kevin/KeyHelp-Manager-for-WHMCS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Dokumentation

Browse Source
This commit is contained in:
Kevin Feiler
2025-10-16 03:42:47 +02:00
parent f5cf6ee08f
commit e9e48ff314
4 changed files with 480 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
CHANGELOG.md
View File

@@ -7,6 +7,14 @@ und dieses Projekt folgt [Semantic Versioning](https://semver.org/lang/de/).
## [Unreleased] ## [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 ### Hinzugefügt
- **Automatische SSL-Verifizierung bei IP-Adressen:** - **Automatische SSL-Verifizierung bei IP-Adressen:**
- SSL-Verifizierung wird automatisch deaktiviert wenn eine IP-Adresse als Hostname verwendet wird - 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" - Manuelle Deaktivierung möglich über HTTP Prefix "no-verify"
- Logging-Hinweis wenn SSL-Verifizierung deaktiviert wird - 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 ### Dokumentation
- Neue Datei `KEYHELP_API_REFERENCE.md` mit vollständiger API-Dokumentation
- Neue Datei `SSL_TROUBLESHOOTING.md` mit umfassender SSL-Fehlerbehandlung - Neue Datei `SSL_TROUBLESHOOTING.md` mit umfassender SSL-Fehlerbehandlung
- README.md erweitert um SSL-Konfigurationshinweise - README.md erweitert um SSL-Konfigurationshinweise
- QUICKSTART.md aktualisiert mit SSL-Best-Practices - QUICKSTART.md aktualisiert mit SSL-Best-Practices
- Korrekte API-Endpunkte und Parameter dokumentiert
### Geplant ### Geplant
- Multi-Language Support (Deutsch/Englisch) - Multi-Language Support (Deutsch/Englisch)

455
KEYHELP_API_REFERENCE.md Normal file
View File

@@ -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

BIN
modules/servers/keyhelpmanager.zip
View File

Binary file not shown.

23
modules/servers/keyhelpmanager/keyhelpmanager.php
View File

@@ -179,12 +179,12 @@ function keyhelpmanager_CreateAccount(array $params)
// Use template if selected (skip if manual or empty) // Use template if selected (skip if manual or empty)
if (!empty($templateId) && $templateId !== "manual") { if (!empty($templateId) && $templateId !== "manual") {
$accountData["plan_id"] = $templateId; $accountData["id_hosting_plan"] = $templateId;
} }
$result = _keyhelpmanager_APIRequest( $result = _keyhelpmanager_APIRequest(
$params, $params,
"/users", "/clients",
"POST", "POST",
$accountData, $accountData,
); );
@@ -200,12 +200,9 @@ function keyhelpmanager_CreateAccount(array $params)
} }
// Create domain with template settings // 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 // KeyHelp API doesn't use template_id for domains, template is applied via user
if (!empty($templateId) && $templateId !== "manual") {
$domainData["template_id"] = $templateId;
}
$domainResult = _keyhelpmanager_APIRequest( $domainResult = _keyhelpmanager_APIRequest(
$params, $params,
@@ -215,7 +212,7 @@ function keyhelpmanager_CreateAccount(array $params)
); );
if (!$domainResult["success"]) { if (!$domainResult["success"]) {
_keyhelpmanager_APIRequest($params, "/users/" . $userId, "DELETE"); _keyhelpmanager_APIRequest($params, "/clients/" . $userId, "DELETE");
return "Domain creation failed: " . $domainResult["error"]; return "Domain creation failed: " . $domainResult["error"];
} }
@@ -247,7 +244,7 @@ function keyhelpmanager_SuspendAccount(array $params)
$result = _keyhelpmanager_APIRequest( $result = _keyhelpmanager_APIRequest(
$params, $params,
"/users/" . $userId, "/clients/" . $userId,
"PUT", "PUT",
["is_locked" => true], ["is_locked" => true],
); );
@@ -269,7 +266,7 @@ function keyhelpmanager_UnsuspendAccount(array $params)
$result = _keyhelpmanager_APIRequest( $result = _keyhelpmanager_APIRequest(
$params, $params,
"/users/" . $userId, "/clients/" . $userId,
"PUT", "PUT",
["is_locked" => false], ["is_locked" => false],
); );
@@ -291,7 +288,7 @@ function keyhelpmanager_TerminateAccount(array $params)
$result = _keyhelpmanager_APIRequest( $result = _keyhelpmanager_APIRequest(
$params, $params,
"/users/" . $userId, "/clients/" . $userId,
"DELETE", "DELETE",
); );
@@ -366,7 +363,7 @@ function keyhelpmanager_ClientArea(array $params)
if (!empty($userId)) { if (!empty($userId)) {
$statsResult = _keyhelpmanager_APIRequest( $statsResult = _keyhelpmanager_APIRequest(
$params, $params,
"/users/" . $userId . "/statistics", "/clients/" . $userId . "/statistics",
"GET", "GET",
); );
@@ -489,7 +486,7 @@ function keyhelpmanager_ChangePassword(array $params)
$result = _keyhelpmanager_APIRequest( $result = _keyhelpmanager_APIRequest(
$params, $params,
"/users/" . $userId, "/clients/" . $userId,
"PUT", "PUT",
["password" => $newPassword], ["password" => $newPassword],
); );