# Dashboard API Dokumentation

Vollständige REST API für das TeamSpeak Reseller Dashboard.

## Basis-URL

```
https://ihre-domain.de/api/v1
```

## Authentifizierung

Die API verwendet Bearer Token Authentifizierung. Sie erhalten einen API-Key nach der Registrierung oder dem Login.

### Header

```
Authorization: Bearer YOUR_API_KEY
```

Alternativ:

```
X-API-Key: YOUR_API_KEY
```

### API-Key erhalten

1. **Registrierung**: Bei der Registrierung wird automatisch ein API-Key erstellt
2. **Login**: Beim Login erhalten Sie einen API-Key (oder es wird ein neuer erstellt)

API-Keys sind standardmäßig 1 Jahr gültig.

---

## Endpoints

### Authentifizierung

#### POST /auth/register

Registriert einen neuen Benutzer und erstellt automatisch einen API-Key.

**Request Body:**
```json
{
  "username": "benutzername",
  "email": "email@example.com",
  "password": "passwort123",
  "password_confirm": "passwort123"
}
```

**Response (201):**
```json
{
  "success": true,
  "message": "Registrierung erfolgreich",
  "user_id": 1,
  "api_key": "abc123...",
  "expires_at": "2025-12-31 23:59:59"
}
```

**Fehler:**
- `400` - Fehlende Felder, Passwort zu kurz, ungültige E-Mail
- `409` - Benutzername oder E-Mail bereits vergeben

---

#### POST /auth/login

Meldet einen Benutzer an und gibt einen API-Key zurück.

**Request Body:**
```json
{
  "username": "benutzername",
  "password": "passwort123"
}
```

**Response (200):**
```json
{
  "success": true,
  "message": "Login erfolgreich",
  "user": {
    "id": 1,
    "username": "benutzername",
    "email": "email@example.com",
    "role": "customer",
    "balance": 10.50
  },
  "api_key": "abc123...",
  "expires_at": "2025-12-31 23:59:59"
}
```

**Fehler:**
- `400` - Fehlende Anmeldedaten
- `401` - Ungültige Anmeldedaten

---

### Account Management

#### GET /account

Ruft die Account-Informationen des authentifizierten Benutzers ab.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "user": {
    "id": 1,
    "username": "benutzername",
    "email": "email@example.com",
    "role": "customer",
    "balance": 10.50,
    "first_name": "Max",
    "last_name": "Mustermann",
    "address": "Musterstraße 1",
    "zip": "12345",
    "city": "Berlin",
    "state": "Berlin",
    "country": "DE",
    "account_type": "private",
    "company": null,
    "vat_id": null,
    "created_at": "2024-01-01 12:00:00"
  }
}
```

---

#### GET /account/sync

Synchronisiert alle Account-Daten und gibt aktuelle Statistiken zurück.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "user": {
    "id": 1,
    "username": "benutzername",
    "email": "email@example.com",
    "role": "customer",
    "balance": 10.50
  },
  "statistics": {
    "servers": {
      "total": 5,
      "active": 3,
      "pending": 1,
      "total_slots": 128
    },
    "instances": {
      "total": 2,
      "active": 1
    }
  },
  "synced_at": "2024-01-15 14:30:00"
}
```

---

#### PUT /account

Aktualisiert Account-Informationen.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Request Body:**
```json
{
  "email": "neue-email@example.com",
  "first_name": "Max",
  "last_name": "Mustermann",
  "address": "Neue Straße 2",
  "zip": "54321",
  "city": "München",
  "state": "Bayern",
  "country": "DE",
  "account_type": "business",
  "company": "Meine Firma GmbH",
  "vat_id": "DE123456789"
}
```

**Response (200):**
```json
{
  "success": true,
  "message": "Account erfolgreich aktualisiert",
  "user": {
    "id": 1,
    "username": "benutzername",
    "email": "neue-email@example.com",
    "role": "customer",
    "balance": 10.50
  }
}
```

---

### Guthaben

#### GET /balance

Ruft das aktuelle Guthaben und Abrechnungsstatistiken ab.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "balance": 10.50,
  "currency": "EUR",
  "statistics": {
    "total_billed": 45.20,
    "billing_periods": 12,
    "active_servers": 3,
    "total_slots": 128,
    "estimated_monthly_cost": 17.92
  },
  "updated_at": "2024-01-15 14:30:00"
}
```

---

### TeamSpeak Server

#### POST /servers/create

Bestellt einen neuen TeamSpeak Server. Die Abrechnung erfolgt sekündlich automatisch.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Request Body:**
```json
{
  "server_name": "Mein TeamSpeak Server",
  "slots": 32,
  "host_id": 1
}
```

**Response (201):**
```json
{
  "success": true,
  "message": "Server erfolgreich erstellt! Die Abrechnung erfolgt sekündlich automatisch.",
  "server": {
    "id": 1,
    "server_name": "Mein TeamSpeak Server",
    "slots": 32,
    "host_id": 1,
    "status": "pending",
    "created_at": "2024-01-15 14:30:00"
  }
}
```

**Fehler:**
- `400` - Fehlende Felder, unvollständiges Profil, unzureichendes Guthaben
- `404` - Host nicht gefunden
- `429` - Rate-Limit überschritten

**Hinweise:**
- Mindestguthaben: 1.00€ (für sekündliche Abrechnung)
- Profil muss vollständig ausgefüllt sein
- Bei Geschäftskunden müssen Firma und UST-ID ausgefüllt sein

---

#### GET /servers

Listet alle Server des authentifizierten Benutzers auf.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "servers": [
    {
      "id": 1,
      "server_name": "Mein TeamSpeak Server",
      "slots": 32,
      "status": "active",
      "port": 9987,
      "monthly_price": 4.48,
      "created_at": "2024-01-15 14:30:00"
    }
  ],
  "total": 1
}
```

---

#### GET /servers/{id}

Ruft Details eines spezifischen Servers ab.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "server": {
    "id": 1,
    "server_name": "Mein TeamSpeak Server",
    "slots": 32,
    "status": "active",
    "host_id": 1,
    "virtual_server_id": 2,
    "port": 9987,
    "host_ip": "192.168.1.100",
    "query_port": 10011,
    "query_username": "serveradmin",
    "admin_token": "abc123...",
    "price_per_slot": 0.14,
    "monthly_price": 4.48,
    "created_at": "2024-01-15 14:30:00",
    "billing_started_at": "2024-01-15 14:30:00"
  }
}
```

**Fehler:**
- `403` - Keine Berechtigung für diesen Server
- `404` - Server nicht gefunden

---

#### PUT /servers/{id}/start

Startet einen Server.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "message": "Server gestartet"
}
```

---

#### PUT /servers/{id}/stop

Stoppt einen Server.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "message": "Server gestoppt"
}
```

---

#### PUT /servers/{id}/restart

Startet einen Server neu.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "message": "Server neu gestartet"
}
```

---

#### DELETE /servers/{id}

Löscht einen Server permanent.

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "message": "Server erfolgreich gelöscht"
}
```

**Warnung:** Diese Aktion kann nicht rückgängig gemacht werden!

---

### Reseller Instanzen

#### POST /instances/create

Bestellt eine neue Reseller-Instanz. (Nur für Reseller)

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Request Body:**
```json
{
  "instance_name": "Meine Reseller Instanz",
  "host_id": 1
}
```

**Response (201):**
```json
{
  "success": true,
  "message": "Reseller-Instanz erfolgreich erstellt",
  "instance": {
    "id": 1,
    "instance_name": "Meine Reseller Instanz",
    "host_id": 1,
    "status": "pending",
    "created_at": "2024-01-15 14:30:00"
  }
}
```

**Fehler:**
- `403` - Nur Reseller können Instanzen bestellen
- `400` - Fehlende Felder, unzureichendes Guthaben
- `404` - Host nicht gefunden
- `429` - Rate-Limit überschritten

---

#### GET /instances

Listet alle Reseller-Instanzen auf. (Nur für Reseller)

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "instances": [
    {
      "id": 1,
      "instance_name": "Meine Reseller Instanz",
      "host_id": 1,
      "host_name": "Host 1",
      "location": "Deutschland",
      "status": "active",
      "is_initialized": true,
      "created_at": "2024-01-15 14:30:00"
    }
  ],
  "total": 1
}
```

---

#### GET /instances/{id}

Ruft Details einer spezifischen Instanz ab. (Nur für Reseller)

**Headers:**
```
Authorization: Bearer YOUR_API_KEY
```

**Response (200):**
```json
{
  "success": true,
  "instance": {
    "id": 1,
    "instance_name": "Meine Reseller Instanz",
    "host_id": 1,
    "host_name": "Host 1",
    "location": "Deutschland",
    "status": "active",
    "query_ip": "192.168.1.100",
    "query_port": 10011,
    "query_username": "serveradmin",
    "is_initialized": true,
    "created_at": "2024-01-15 14:30:00",
    "tokens": [
      {
        "id": 1,
        "token_type": "serveradmin",
        "token_value": "abc123...",
        "description": "ServerAdmin Token"
      }
    ]
  }
}
```

---

## Fehlerbehandlung

Alle Fehler werden im folgenden Format zurückgegeben:

```json
{
  "success": false,
  "error": "Fehlermeldung",
  "error_code": "ERROR_CODE"
}
```

### HTTP Status Codes

- `200` - Erfolgreich
- `201` - Erfolgreich erstellt
- `400` - Ungültige Anfrage
- `401` - Nicht authentifiziert
- `403` - Keine Berechtigung
- `404` - Nicht gefunden
- `429` - Rate-Limit überschritten
- `500` - Server-Fehler

### Fehler-Codes

- `MISSING_API_KEY` - API-Key fehlt
- `INVALID_API_KEY` - Ungültiger API-Key
- `MISSING_FIELDS` - Fehlende Pflichtfelder
- `INVALID_EMAIL` - Ungültige E-Mail-Adresse
- `PASSWORD_MISMATCH` - Passwörter stimmen nicht überein
- `PASSWORD_TOO_SHORT` - Passwort zu kurz
- `USER_EXISTS` - Benutzer existiert bereits
- `INVALID_CREDENTIALS` - Ungültige Anmeldedaten
- `INSUFFICIENT_BALANCE` - Unzureichendes Guthaben
- `INCOMPLETE_PROFILE` - Profil unvollständig
- `RATE_LIMIT_EXCEEDED` - Rate-Limit überschritten
- `SERVER_NOT_FOUND` - Server nicht gefunden
- `ACCESS_DENIED` - Keine Berechtigung
- `HOST_NOT_FOUND` - Host nicht gefunden
- `INSUFFICIENT_SLOTS` - Nicht genügend Slots verfügbar
- `QUOTA_EXCEEDED` - Kontingent überschritten

---

## Rate Limiting

Die API implementiert Rate-Limiting zum Schutz vor Missbrauch:

- **Server erstellen**: Maximal X Server pro Stunde
- **Server-Aktionen**: Maximal X Aktionen pro Stunde
- **Instanzen erstellen**: Maximal X Instanzen pro Stunde

Bei Überschreitung erhalten Sie einen `429` Status-Code mit der Fehlermeldung.

---

## Beispiele

### cURL

#### Registrierung
```bash
curl -X POST https://ihre-domain.de/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "benutzername",
    "email": "email@example.com",
    "password": "passwort123",
    "password_confirm": "passwort123"
  }'
```

#### Login
```bash
curl -X POST https://ihre-domain.de/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "benutzername",
    "password": "passwort123"
  }'
```

#### Server erstellen
```bash
curl -X POST https://ihre-domain.de/api/v1/servers/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "server_name": "Mein Server",
    "slots": 32,
    "host_id": 1
  }'
```

#### Server auflisten
```bash
curl -X GET https://ihre-domain.de/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Account synchronisieren
```bash
curl -X GET https://ihre-domain.de/api/v1/account/sync \
  -H "Authorization: Bearer YOUR_API_KEY"
```

---

### JavaScript (Fetch API)

#### Registrierung
```javascript
const response = await fetch('https://ihre-domain.de/api/v1/auth/register', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    username: 'benutzername',
    email: 'email@example.com',
    password: 'passwort123',
    password_confirm: 'passwort123'
  })
});

const data = await response.json();
console.log(data);
```

#### Server erstellen
```javascript
const response = await fetch('https://ihre-domain.de/api/v1/servers/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    server_name: 'Mein Server',
    slots: 32,
    host_id: 1
  })
});

const data = await response.json();
if (data.success) {
  console.log('Server erstellt:', data.server);
} else {
  console.error('Fehler:', data.error);
}
```

---

### Python

#### Registrierung
```python
import requests

url = "https://ihre-domain.de/api/v1/auth/register"
data = {
    "username": "benutzername",
    "email": "email@example.com",
    "password": "passwort123",
    "password_confirm": "passwort123"
}

response = requests.post(url, json=data)
result = response.json()
print(result)
```

#### Server erstellen
```python
import requests

url = "https://ihre-domain.de/api/v1/servers/create"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "server_name": "Mein Server",
    "slots": 32,
    "host_id": 1
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

if result.get("success"):
    print("Server erstellt:", result["server"])
else:
    print("Fehler:", result.get("error"))
```

---

## Best Practices

1. **API-Key sicher aufbewahren**: Teilen Sie Ihren API-Key niemals öffentlich
2. **HTTPS verwenden**: Verwenden Sie immer HTTPS für API-Aufrufe
3. **Fehlerbehandlung**: Implementieren Sie eine ordentliche Fehlerbehandlung
4. **Rate-Limiting beachten**: Respektieren Sie die Rate-Limits
5. **Profil vollständig ausfüllen**: Vor der Server-Bestellung muss das Profil vollständig sein
6. **Guthaben überwachen**: Überwachen Sie das Guthaben regelmäßig

---

## Support

Bei Fragen oder Problemen kontaktieren Sie bitte den Support.

**API Version:** 1.0  
**Letzte Aktualisierung:** 2024-01-15