kevin/KeyHelp-Manager-for-WHMCS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
760019da3a3731dcf7c79f49111cd1075a2bd90b
KeyHelp-Manager-for-WHMCS/KEYHELP_API_REFERENCE.md
Kevin Feiler e9e48ff314 Dokumentation
2025-10-16 03:42:47 +02:00

8.1 KiB
Raw Blame History

KeyHelp API v2 Referenz

Diese Datei dokumentiert die tatsächlich verwendeten KeyHelp API v2 Endpunkte und Parameter.

Offizielle Dokumentation

Wichtige Unterschiede

⚠️ ACHTUNG: KeyHelp verwendet /clients statt /users!

Verwendete Endpunkte

1. Client (Benutzer) erstellen

Endpunkt: POST /api/v2/clients

Request Body:

{
  "login_name": "example_com",
  "password": "SecurePassword123!",
  "email": "user@example.com",
  "display_name": "Max Mustermann",
  "id_hosting_plan": 5  // Optional: Hosting-Plan ID
}

Response:

{
  "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:

{
  "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:

{
  "password": "NewSecurePassword456!"
}

Client sperren:

{
  "is_locked": true
}

Client entsperren:

{
  "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:

{
  "domain_name": "example.com",
  "id_client": 42
}

Response:

{
  "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:

{
  "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:

{
  "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:

{
  "id_client": 42
}

Response:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "error": "Endpoint not found"
}

401 Unauthorized:

{
  "error": "Invalid API key"
}

400 Bad Request:

{
  "error": "Validation failed",
  "details": {
    "login_name": "This field is required",
    "email": "Invalid email format"
  }
}

500 Internal Server Error:

{
  "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

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

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

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

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:

Bei Fragen zum WHMCS-Modul:

Entwickelt von: Kevin Feiler / AVVGO
Lizenz: MIT

Reference in New Issue View Git Blame Copy Permalink