KeyHelp-Manager-for-WHMCS/KEYHELP_API_REFERENCE.md

# 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