API Dokumentation

Diese Dokumentation richtet sich an Entwickler, die eigene Web-Interfaces, Dashboard-Tools oder Integrationen auf Basis der MyNexVoice-API bauen möchten. Alle Endpunkte liefern JSON und sind unter https://mynexvoice.com/api/ erreichbar.

Quickstart

In drei Schritten zu deiner ersten API-Abfrage: Registrieren, Token holen, Profil abrufen.

1. Konto registrieren oder anmelden

# Registrieren
curl -s -X POST https://mynexvoice.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"MaxMuster","email":"max@example.de","password":"sicher123"}'

# Antwort:
{
  "token": "a3f2b1...",
  "user": { "id": 42, "username": "MaxMuster", "email": "max@example.de" }
}

2. Token im Header mitsenden

curl -s https://mynexvoice.com/api/profile/me \
  -H "Authorization: Bearer a3f2b1..."

# Antwort:
{
  "id": 42, "username": "MaxMuster", "email": "max@example.de",
  "bio": "", "avatar_url": null
}

3. Eigene Lizenzen abrufen

curl -s https://mynexvoice.com/api/licenses/me \
  -H "Authorization: Bearer a3f2b1..."

# Antwort:
[
  {
    "id": 1, "license_key": "NEXV-PRIV-1A2B3C4D-5E6F7A8B-9C0D1E2F",
    "plan_name": "Private 32", "status": "active",
    "max_slots": 32, "expires_at": "2026-05-06 12:00:00"
  }
]

Authentifizierung

Nach Login/Registrierung erhältst du einen Bearer-Token (gültig 90 Tage). Alle markierten Endpunkte erfordern diesen Token im Authorization-Header. Token sind sofort nach dem Erstellen des Accounts revozierbar.

POST /api/auth/register

# Body (JSON)
{ "username": "MaxMuster", "email": "max@example.de", "password": "sicher123" }

# Antwort 200
{ "token": "...", "user": { "id": 1, "username": "...", "email": "..." } }

# Regeln: Username 3–32 Zeichen, Passwort min. 8 Zeichen

POST /api/auth/login

# Body (JSON)
{ "email": "max@example.de", "password": "sicher123" }

# Antwort 200
{ "token": "a3f2b1c9d8e7...", "user": { ... } }

# Antwort 401 bei falschen Daten
{ "error": "Ungültige Anmeldedaten." }

PUT /api/auth/password 🔒 Token

{ "current_password": "alt", "new_password": "neu1234" }

Profil

GET /api/profile/me 🔒 Token

# Eigenes Profil abrufen – typischer Einstiegspunkt nach Login
curl https://mynexvoice.com/api/profile/me \
  -H "Authorization: Bearer TOKEN"

# Antwort:
{
  "id": 42, "username": "MaxMuster", "email": "max@example.de",
  "bio": "", "custom_status": "", "profile_id": "maxmuster_a1b2c3",
  "avatar_url": null, "banner_url": null, "role": "user"
}

PUT /api/profile/me 🔒 Token

# Felder die geändert werden können:
{ "bio": "Gamer aus Berlin", "custom_status": "Zockt gerade" }

GET /api/profile/search?q=max 🔒 Token

# Benutzer nach Name/E-Mail suchen
[ { "id": 42, "username": "MaxMuster", "profile_id": "..." } ]

Lizenzen

Lizenzen steuern, wie viele Slots und Instanzen ein NexVoice-Server betreiben darf. Nach dem Kauf im Shop bekommst du einen Schlüssel per E-Mail — der wird hier aktiviert und danach vom Serverprozess validiert.

GET /api/licenses/plans Öffentlich

[ { "id": 1, "name": "Private 32", "type": "private", "max_slots": 32, "price_eur": 4.99 }, ...]

GET /api/licenses/me 🔒 Token

# Alle Lizenzen des eingeloggten Benutzers
[
  {
    "id": 1,
    "license_key": "NEXV-PRIV-1A2B3C4D-5E6F7A8B-9C0D1E2F",
    "plan_name": "Private 32",
    "type": "private",
    "max_slots": 32,
    "status": "active",          // pending | active | suspended | expired
    "expires_at": "2026-06-06 12:00:00",
    "bound_ip": "123.45.67.89"     // IP des registrierten Servers
  }
]

POST /api/licenses/activate 🔒 Token

# Lizenzschlüssel dem eigenen Konto zuordnen
{ "license_key": "NEXV-PRIV-1A2B3C4D-5E6F7A8B-9C0D1E2F" }

# Antwort 200
{ "message": "Lizenz erfolgreich aktiviert." }

POST /api/licenses/validate Server-intern

# Wird automatisch vom NexVoice-Serverprozess beim Start aufgerufen.
# Nicht für Web-Interfaces gedacht.
{ "license_key": "NEXV-...", "ip": "123.45.67.89", "port": 9987 }

# Antwort 200
{ "valid": true, "max_slots": 32, "type": "private", "expires_at": "..." }

Nickname Discovery

Ermöglicht die Auflösung kurzer Namen zu IP:Port-Paaren. Der NexVoice-Client erkennt Nicknames anhand des Musters /^[A-Za-z0-9_\-]{2,32}$/ automatisch.

GET /api/resolve/:nickname Öffentlich

# Verwendung: Nutzer gibt "meinserver" statt "123.45.67.89:9987" ein
curl https://mynexvoice.com/api/resolve/meinserver

# Antwort 200
{ "ip": "123.45.67.89", "port": 9987, "nickname": "meinserver" }

# Antwort 404
{ "error": "Nickname nicht gefunden." }

POST /api/nickname 🔒 Token

{ "nickname": "meinserver", "ip": "123.45.67.89", "port": 9987 }

GET /api/nickname/me 🔒 Token

# Eigenen Nickname abrufen — 404 wenn noch keiner registriert
{ "nickname": "meinserver", "ip": "...", "port": 9987 }

DELETE /api/nickname 🔒 Token

{ "success": true }

Server Browser

Öffentliche Liste aller registrierten NexVoice-Server — wird vom WPF-Client im Server-Browser angezeigt und kann auch in eigenen Web-Interfaces eingebettet werden.

GET /api/servers Öffentlich

# Alle öffentlich gelisteten Server mit aktiver Lizenz
[
  {
    "id": 1,
    "name": "Mein NexVoice Server",
    "ip": "123.45.67.89",
    "port": 9987,
    "description": "Gaming-Community Server",
    "country": "DE",
    "current_users": 12,
    "max_slots": 32,
    "password_protected": false,
    "version": "1.0.0"
  }
]

# JavaScript-Beispiel für eigene Website:
const res = await fetch('https://mynexvoice.com/api/servers');
const servers = await res.json();
servers.forEach(s => console.log(`${s.name}: ${s.current_users}/${s.max_slots} online`));

News

GET /api/news Öffentlich

[
  {
    "id": 1, "title": "NexVoice 3.0 released",
    "summary": "...", "content": "...",
    "category": "release", "author": "Team NexVoice",
    "created_at": "2026-05-06 10:00:00", "pinned": false
  }
]

Fehlerbehandlung

Alle Fehler werden als JSON mit einem error-Feld zurückgegeben. HTTP-Statuscodes nach Standard:

# 400 – Ungültige Eingabe
{ "error": "Alle Felder sind erforderlich." }

# 401 – Nicht angemeldet / Token ungültig
{ "error": "Unauthorized" }

# 403 – Falsches Passwort / IP-Mismatch
{ "error": "Aktuelles Passwort falsch." }

# 404 – Nicht gefunden
{ "error": "Nickname nicht gefunden." }

# 500 – Serverfehler (im Produktionsbetrieb immer generisch)
{ "error": "Internal server error" }

Prüfe stets response.ok (HTTP 2xx) bevor du die Daten verarbeitest. Bei Fehlern enthält das Objekt immer ein error-Feld.

PHP Beispiel

Vollständiges Beispiel für ein eigenes PHP-Dashboard: Login → Lizenzliste anzeigen.

// nexvoice-api.php — einfacher API-Wrapper
function nexvoice_api(string $method, string $path, ?array $body = null, ?string $token = null): array {
    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL            => 'https://mynexvoice.com' . $path,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => array_filter([
            'Content-Type: application/json',
            $token ? 'Authorization: Bearer ' . $token : null,
        ]),
        CURLOPT_POSTFIELDS     => $body ? json_encode($body) : null,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_TIMEOUT        => 10,
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true) ?? [];
}

// ── Login ──────────────────────────────────────────────────────────────────
$auth = nexvoice_api('POST', '/api/auth/login', [
    'email'    => 'max@example.de',
    'password' => 'sicher123',
]);

if (!isset($auth['token'])) {
    die('Login fehlgeschlagen: ' . ($auth['error'] ?? 'unbekannt'));
}

$token = $auth['token'];
echo 'Angemeldet als: ' . $auth['user']['username'] . PHP_EOL;

// ── Lizenzen abrufen ───────────────────────────────────────────────────────
$licenses = nexvoice_api('GET', '/api/licenses/me', null, $token);

foreach ($licenses as $lic) {
    echo sprintf(
        "[%s] %s – %d Slots – läuft ab: %s\n",
        strtoupper($lic['status']),
        $lic['plan_name'],
        $lic['max_slots'],
        $lic['expires_at'] ?? '—'
    );
}

// ── Nickname registrieren ──────────────────────────────────────────────────
$result = nexvoice_api('POST', '/api/nickname', [
    'nickname' => 'meinserver',
    'ip'       => '123.45.67.89',
    'port'     => 9987,
], $token);

var_dump($result); // ['success' => true]