kundencenter/docs/connector-keyhelp.md

KeyHelp-Connector: API-Fähigkeiten und Abbildung

Umsetzungsstand (27.09.2026)

Paket packages/connector-keyhelp, getestet gegen einen nach der Definition nachgebauten Server (test/fake.ts), nicht gegen eine echte Instanz. Zugang: KeyHelp-Adresse + API-Schlüssel (IP-beschränkt); die Version wird über GET /server erkannt.

• Lesen/Abgleich: Kunden mit Nutzung und Limits (Statistik je Kunde), Tarife, Health mit Version. Der Abgleich arbeitet rein lesend.
• Kunden übernehmen (Kunden → Aus Verbindung übernehmen): Kontaktdaten → Kunde und Rechnungsanschrift, Inhaber als „eingeladen“ ohne E-Mail-Versand (Einladung später gezielt), Konto wird zugeordnet, optional Bestandsvertrag zum passenden Produkt (Beginn wählbar, Laufzeit wird in die Zukunft fortgeschrieben, keine Rechnung). Doppelte Übernahme ist ausgeschlossen (organizations.legacy_ref); Verknüpfung mit vorhandenem Kunden möglich.
• Tarife/Produkte: vorhandene Tarife über „Produkte → Aus Verbindung übernehmen“; neue Tarife über „Neuen Hosting-Tarif anlegen“ (legt den Tarif in KeyHelp an und das Produkt im Kundencenter). Name muss frei sein, „unbegrenzt“ nur, wenn die Instanz es bereits kennt.
• Bereitstellung (Bestellung): Konto anlegen, Benutzername kc + Ziffern der Vertragsnummer (stabil, bei Wiederholung wird das eigene Konto übernommen), Vermerk „Kundencenter K-… V-…“, Zugangsdaten gehen per KeyHelp an die Kunden-E-Mail (Passwort wird nie gelesen/gespeichert).
• Aktionen: Sperren/Entsperren, Tarifwechsel (Connector; UI folgt mit Upgrade/Downgrade), Löschen nur manuell und nie automatisch wiederholt.
• Kundenpanel-Login (SSO, 60 Min., nicht gespeichert, im Audit).
• Hosting-Ressourcen je Konto: Domains, E-Mail, Datenbanken, FTP lesen und ändern (als Auftrag, Passwörter nur verschlüsselt bis zur Ausführung), SSL-Zertifikate nur lesen. Freigabe pro Produkt/Ressource (domain.manage, email.manage, database.manage, ftp.manage, panel.login) plus Rolle Inhaber/Admin.
• Mandantentrennung: Der API-Schlüssel ist ein Administratorzugang, deshalb prüft der Connector vor jeder Änderung, dass das Objekt dem Konto gehört; neue Objekte bekommen immer die Kunden-ID; Namenskonflikte mit fremden Objekten werden abgelehnt (getestet).

Annahmen, die an der echten Instanz zu prüfen sind

1. Speicher/Traffic in Byte (Definition gibt keine Einheit an; Anzeige und Tarif-Anlage gehen davon aus).
2. Zeitstempel ohne Zeitzone werden als UTC gelesen.
3. Negative Limits = unbegrenzt (nur beim Anlegen genutzt, wenn die Instanz es schon kennt).
4. Pflichtfelder von POST /clients (E-Mail, Benutzername; Passwort wird vom Panel erzeugt) und Benutzernamensregeln (kc + Ziffern).
5. FTP-Anlage setzt ein vollständig eingerichtetes System-Konto voraus (Panel meldet sonst 400).
6. Verhalten bei Tarifwechsel, wenn neue Limits unterschritten werden.
7. Listen liefern alles (kein Paging): bei sehr vielen Kunden dauert der Abgleich (Statistik je Kunde, 4 parallel).

Noch nicht umgesetzt

DNS-Editor, Cronjobs, Verzeichnisschutz, PHP-Einstellungen je Kunde, Zertifikate hochladen, Fail2Ban-Entsperren, Backup-Liste anzeigen; Hauptdomain bei der Bestellung erfragen; Kündigung mit delete_on statt Sperre; Tarifwechsel in der Oberfläche.

(Auswertung der API-Definition)

Quelle: offizielle OpenAPI-Definition KeyHelp RESTful API 2.15 (geändert 25.09.2026), Kopie: docs/api-specs/keyhelp-api-2.15.openapi.json. Stand: nur die Definition gelesen, nicht gegen eine echte KeyHelp-Instanz geprüft (kein Testzugang, Version der Instanz unbekannt).

Grundregeln der API

• URL https://<host>/api/v2/<Endpunkt>, Anmeldung per Header X-API-Key. Formate: JSON (Standard), XML, YAML.
• API ist standardmäßig aus. Schlüssel legt man in KeyHelp an (Admin-Bereich → Konfiguration → API) und soll auf IP/IP-Bereich beschränkt werden. Es gibt keine Rechte-Stufen pro Schlüssel: Ein Schlüssel ist praktisch ein Administratorzugang → höchste Vertraulichkeit (verschlüsselt speichern, nur Superadmin).
• Objekte sind per numerischer ID oder Name ansprechbar (/clients/{id} und /clients/name/{name}).
• Listen liefern alles auf einmal (nur sort/order, kein Paging). Bei sehr vielen Kunden Antwortzeit beachten.
• Fehlerformat {code, message}, Statuscodes 200/201/202/204/400/401/404.
• Beim Neuladen des Webservers antwortet KeyHelp kurz mit 500/503 → Aufrufer muss nach einigen Sekunden erneut versuchen.
• Objekte haben ein Feld status: 0 unbekannt, 1 ok, 2 Fehler, 3 Konfiguration neu, 4 Konfiguration wird aktualisiert (→ Zustand „in Bearbeitung“).
• Keine Webhooks, keine Paginierung, keine Rechnungs-/Ticket-Funktionen.

Abbildung auf den Connector-Vertrag

Fähigkeit	KeyHelp	Bemerkung
Health / Version	GET /ping, GET /server	Server-Info mit Komponenten (Apache, PHP, MariaDB, Postfix …), Auslastung, Ports
Ressourcen lesen	GET /clients, /clients/{id}, /clients/{id}/resources	Kunde = Hosting-Konto; Ressourcen-Liste enthält die Unterobjekte
Nutzung	GET /clients/{id}/stats, /traffic	Speicher und Traffic (value/max), Anzahl Domains, Postfächer, DBs, FTP, Cronjobs; Traffic je Protokoll (HTTP, FTP, POP3, IMAP, SMTP)
Limits/Tarif	client.resource_limits (nur lesend), GET /hosting-plans	Limits nur über den Tarif änderbar, keine Einzelabweichung pro Kunde per API (dafür eigenen Tarif anlegen)
lifecycle.create	POST /clients → 201 {id}	Pflicht/Optionen: Benutzername, E-Mail, Passwort oder generiert, id_hosting_plan (sonst Standardtarif), Kontaktdaten, create_system_domain, send_login_credentials. Natürliche Idempotenz über den eindeutigen Benutzernamen (vorher GET /clients/name/{name})
lifecycle.suspend/unsuspend	PUT /clients/{id} {is_suspended}	Zielzustand → idempotent. Zusätzlich geplant: suspend_on und delete_on (Datum oder „+30 days“) → passt zu Kündigung, Kulanz- und Sperrregeln
lifecycle.terminate	DELETE /clients/{id}	Löscht Konto und ALLE Ressourcen (destruktiv): nie automatisch wiederholen, immer manuelle Bestätigung; besser delete_on mit Kulanzfrist
plan.change	PUT /clients/{id} {id_hosting_plan}	Up-/Downgrade über Tarifwechsel (Verhalten bei Überschreitung der neuen Limits an der Instanz prüfen)
Passwort/Zugang	PUT /clients/{id} {password}	Optional Zugangsdaten per E-Mail (send_login_credentials)
sso.login	GET /login/{id} bzw. /login/name/{name}	Offiziell unterstützt: URL 60 Minuten gültig, mit Brute-Force-Schutz. Passt zu „sicherer Panel-Login“
Domains	/domains (CRUD), php_version, is_disabled, delete_on, security (Let’s Encrypt, HTTPS erzwingen, HSTS), is_email_domain	Haupt- und Subdomains, System-Domains filterbar
DNS	/dns/{id} lesen/ersetzen/zurücksetzen	Datensätze, DKIM
SSL	/certificates (CRUD)	valid_till, issuer, secured_domains → Ablaufdaten verfügbar
E-Mail	/emails (CRUD)	Postfachgröße/-limit, Aliase, Weiterleitungen, Catch-all, Passwort
Datenbanken	/databases (CRUD)	Name, Benutzer, Passwort, Größe, Remote-Hosts
FTP	/ftp-users (CRUD)	Benutzer, Heimverzeichnis
Weiteres	/scheduled-tasks (Cronjobs), /directory-protections, /backups/operations (nur Liste), /fail2ban/banned-ips (Liste, Entsperren)	Backup-Wiederherstellung ist nicht per API möglich
Nicht vorhanden	Webhooks, Paging, Limits pro Kunde, Rechnungen/Tickets	Abgleich daher per Polling (Sync-Job)
Nie freigeben	/admins/*, POST /server/reboot	Administratorkonten und Server-Neustart gehören nicht in das Kundencenter

Vorschlag für den Umfang

1. Lesend zuerst: Health, Kunden mit Nutzung/Limits/Status, Domains, SSL-Ablauf, Übernahme der Hosting-Tarife als Produktvorlagen (wie beim Lizenzsystem: Limits aus hosting-plans).
2. Lebenszyklus: anlegen, sperren/entsperren, Tarifwechsel, geplantes Löschen (delete_on) statt sofortigem DELETE.
3. Panel-Login (SSO) und Unterobjekte (E-Mail, Datenbanken, FTP) für Kunden gemäß Produktregeln.

Benötigt für die Umsetzung

• KeyHelp-URL und Version (Definition kennt 2.1–2.15; Abweichungen kapselt der Connector).
• Ein Test-API-Schlüssel, auf die IP des Kundencenter-Servers beschränkt (idealerweise gegen eine Testinstanz; sonst Schlüssel mit Bedacht, da er Administratorrechte hat).
• Entscheidung, welche Tarife als Produkte angeboten werden und ob Kunden Unterobjekte selbst verwalten dürfen.