Hosting-Anbieter – Kunden, Dienste und Abrechnung

Die Hosting-API unterstützt Anbieter beim Betrieb verwalteter S3-Dienste mit Kunden- und Resellerzugriff, versionierten Tarifen, Dienstaktionen und monatlichen Nutzungsabrechnungen. Diese Anleitung beschreibt die Ausgabe vom 23. Oktober 2026. Prüfen Sie vor der Kundenaufnahme, ob Ihre installierte eEKAS-Version die Funktionen unterstützt und Hosting, Nutzungserfassung und Überwachung aktiviert sind. Die API-Nutzung erfolgt in eigener Verantwortung und ist nicht durch den Support abgedeckt.

Den passenden Ablauf wählen

/api/v1/object-storage/ dient der administrativen Verwaltung von S3-Benutzern, Buckets und bestehenden Kundenabrechnungsberichten. /api/v1/hosting/ ergänzt tarifbasierte Abonnements und auf Kunden beziehungsweise Reseller begrenzte Automatisierung. Hosting erzeugt eigene Benutzer und Buckets je Dienst; vorhandene S3-Benutzer, Buckets und Abrechnungsregistrierungen werden nicht automatisch übernommen. Der S3 Browser bietet Objektzugriff und Branding. Ein Abonnement- oder Abrechnungsportal erfordert eine separate Integration.

Konten und Berechtigungen

Senden Sie X-API-Key über die konfigurierte HTTPS-API, normalerweise an Port 18443. GUI-Anmeldung, Verwaltungs-API-Zugang, Hosting-Kundendatensatz und S3-Schlüssel haben unterschiedliche Aufgaben. Das Anlegen eines Kontos stellt nicht automatisch einen API-Token aus und gewährt keine Administratorrechte.

Identität	Verwendung
Anbieterpersonal: admin oder s3-admin	Standorte, Tarife, Reseller und Dienste verwalten; anbieterweiten Status, Überwachung und Sicherungsmetadaten lesen.
Hosting-Reseller	Kunden anlegen und deren Dienste innerhalb zugewiesener Tarife und Kapazitätsgrenzen verwalten.
Hosting-Kunde	Eigene Dienste, Nutzung, Vorgänge, Abrechnungen und Ereignisse lesen; Zugangsdaten aktiver Dienste abrufen und eigene Tokens/Webhooks verwalten.

Kunden- und Resellertokens können keine globalen Verwaltungsendpunkte oder globalen Jobs nutzen. Anbieterweite Status-, Überwachungs- und Sicherungsabfragen sind auch für read-only-Schlüssel gesperrt. GET /api/v1/hosting/me zeigt die authentifizierte Identität.

POST /tokens erhält genau eine customer_id oder reseller_id, ein label und optional expires_days (1–366, Standard 90). Bewahren Sie den einmalig angezeigten Token geschützt auf. Pro Identität sind höchstens 20 aktive Tokens zulässig. Widerrufen Sie ungenutzte Tokens mit DELETE /tokens und token_id im JSON-Körper.

Tarife und Kunden vorbereiten

Die folgenden Pfade gelten relativ zu /api/v1/hosting. Änderungen verwenden JSON-Objekte und Content-Type: application/json. Listen unterstützen limit (1–200) und cursor.

1. Registrieren Sie einen vorhandenen S3-Standort mit POST /locations: id, name, site und capacity_gib. Dadurch wird kein neuer S3-Standort angelegt. Die Standortzuordnung kann später nicht geändert werden.
2. Veröffentlichen Sie einen Tarif mit POST /plans: id, name, quota_gib, erlaubte locations und currency. Ergänzen Sie bei Bedarf Objektgrenzen, Aufbewahrung, Versionierung/WORM, Ratenlimits und Preise. Dieselbe Tarif-ID erzeugt bei erneuter Veröffentlichung eine neue unveränderliche Version.
3. Legen Sie optional einen Reseller mit id, name, quota_gib und allowed_plans an. Ein Kunde benötigt id, name und optional email, external_id sowie reseller_id.
4. Prüfen Sie Speichererfassung und S3-Traffic-Erfassung vor Beginn des Abrechnungszeitraums. Eine spätere Aktivierung rekonstruiert keine fehlenden Messwerte.

Standort- und Resellergrenzen reservieren logische GiB-Kontingente. Fehlgeschlagene und gekündigte Dienste reservieren ihre Quota bis zur endgültigen Entfernung weiter. Dies garantiert keine physische Ceph-Kapazität. Ratenlimits gelten je Minute und RGW-Daemon; sie sind keine feste clusterweite Bandbreitenbegrenzung.

Dienst bereitstellen und übergeben

Senden Sie POST /services mit einem eindeutigen Idempotency-Key (8–200 zulässige Zeichen), beispielsweise mit:

{"customer_id":"customer01","plan_id":"standard","plan_version":1,"external_id":"subscription-123","location_id":"eu-central"}

Wiederholen Sie nach einem Verbindungsfehler dieselbe Anfrage mit demselben Schlüssel. Widersprüchliche Tarif- oder Standortangaben liefern 409. HTTP 202 bedeutet angenommen: Fragen Sie die zurückgegebene status_url ab, bis state=complete oder state=failed erreicht ist. Hosting-Vorgänge verwenden /hosting/operations und nicht den globalen Jobs-Endpunkt. Übergeben Sie den Dienst erst nach bestätigtem Abschluss.

POST /credentials mit service_id ruft ausdrücklich die S3-Zugangsdaten eines aktiven eigenen Dienstes ab. Übermitteln Sie diese geschützt und verwenden Sie für Objekte den separaten S3-Endpunkt. rotate=true ergänzt einen zweiten Schlüssel; der alte bleibt aktiv. Höchstens zwei Schlüssel sind zulässig. Ein Anbieteradministrator widerruft ungenutzte Schlüssel über die S3-Verwaltung. Prüfen Sie Bucketzugriff und Quotas vor der Übergabe.

Dienstlebenszyklus verwalten

POST /services/actions benötigt service_id, action und Idempotency-Key; expected_revision schützt optional vor gleichzeitigen Änderungen. Pro Dienst ist nur ein wartender oder laufender Vorgang zulässig.

Aktion	Ergebnis
suspend / resume	S3-Zugriff sperren beziehungsweise freigeben. Bei Sperrung laufen Grund- und Speichergebühren weiter.
change-plan	plan_id und optional plan_version angeben. Die Quota muss vorhandene Daten aufnehmen können; der aktuelle Standort muss erlaubt bleiben. Währung und Schutzvorgaben bleiben gewahrt. Technische Grenzen ändern sich nach Prüfung, der neue Abrechnungstarif ab dem nächsten UTC-Kalendermonat.
cancel	Zugriff sperren und künftige abrechenbare Laufzeit beenden. Daten und reservierte Quota bleiben während der tariflichen Aufbewahrungsfrist erhalten.
purge	Nach Ablauf der Kündigungsaufbewahrung mit confirm="purge:<service_id>" bestätigen. Nur leere eigene Buckets und Benutzer werden entfernt. Geschützte oder nicht leere Inhalte werden nicht zwangsweise gelöscht. Die Kapazität wird erst nach geprüfter Entfernung freigegeben.
retry	Nach Prüfung eines Fehlers ausdrücklich mit neuem Idempotenzschlüssel wiederholen. Ein fehlgeschlagener Vorgang kann den Speicher bereits teilweise verändert haben.

Nutzung und Monatsabrechnungen

GET /usage?service_id=... liefert erfassten Speicher, Objektanzahl, Quota, Erfassungszeit und Traffic-Abdeckung. Fehlende Werte bedeuten unbekannt und nicht null Verbrauch. management_check_ms misst die Verwaltungsabfrage, nicht die S3-Latenz eines Kunden.

Tarife akzeptieren nichtnegative Dezimalzeichenfolgen: monthly_base, included_storage_gib, storage_price_per_gib, included_upload_gib, upload_price_per_gib, included_download_gib und download_price_per_gib. Nicht gesetzte Geldwerte sind null. Ein GiB entspricht 1.073.741.824 Bytes.

1. Rufen Sie nach Monatsende GET /billing/preview?customer_id=customer01&period=2026-09 auf. Zulässig sind abgeschlossene UTC-Kalendermonate.
2. Prüfen Sie Positionen, gültige Tarife, Speicher-/Traffic-Abdeckung und Währungen. Die Grundgebühr wird nach abrechenbaren aktiven Sekunden anteilig berechnet. Speichermehrverbrauch verwendet den erfassten Monatspeak oberhalb des Inklusivkontingents; Traffic verwendet gemessene Zähler. Inklusivkontingente und Speichermehrverbrauch werden nicht zeitanteilig berechnet. Sperrung bleibt abrechenbar; Kündigung beendet die abrechenbare Laufzeit.
3. Schließen Sie mit POST /billing/statements und {"customer_id":"customer01","period":"2026-09"} ab. Unvollständige erforderliche Abdeckung liefert 409 und verhindert den Abschluss.
4. Lesen Sie die Abrechnung mit GET /billing/statements und exportieren Sie über GET /billing/export?statement_id=.... Bewahren Sie Abrechnung und Prüfsumme bei Ihren Unterlagen auf.

Speichermessungen müssen innerhalb von 300 Sekunden an beiden Grenzen der aktiven Zeit vorliegen; zwischen benachbarten Messungen dürfen höchstens 600 Sekunden liegen. Kostenpflichtiger Traffic benötigt vollständige Abdeckung und bekannte Zähler. Kostenloser Traffic darf ausdrücklich unbekannt bleiben, während bekannte Grund-/Speichergebühren abgeschlossen werden. Ersetzen Sie fehlende Messwerte nicht durch Schätzungen. Beträge werden kaufmännisch auf drei Dezimalstellen gerundet; Währungen bleiben getrennt.

Abgeschlossene Abrechnungen sind unveränderlich und je Kunde/Monat eindeutig. Erneuter Abschluss liefert dasselbe Dokument. Tarife, Positionen und Abdeckungsnachweise werden eingefroren; eine SHA-256-Prüfsumme ist enthalten. Anders als bei bestehenden S3-Berichten berechnen spätere Preisänderungen abgeschlossene Abrechnungen nicht neu. Steuern, Rechnungen, Zahlungen und Gutschriften verbleiben im Abrechnungssystem. Importieren Sie externe Referenzen aus CSV als Text.

Ereignisse, Webhooks und Abrechnungsintegration

GET /events?after=0 liefert berechtigungsgerechte Ereignisse; setzen Sie mit next_after fort. Ereignisse umfassen Dienstaktionen, Fehler, Quotagrenzen, fehlende Messwerte und abgeschlossene Abrechnungen. POST /webhooks registriert eine HTTPS-url und Ereignisnamen oder *. Speichern Sie das einmalig zurückgegebene Signaturgeheimnis geschützt.

Prüfen Sie X-Euronas-Signature als HMAC-SHA256 mit dem hexadezimal dekodierten Signaturgeheimnis über X-Euronas-Timestamp + "." + exakter Anfragekörper. Verwenden Sie ein kurzes Zeitfenster und erkennen Sie doppelte X-Euronas-Event-ID-Werte. Zustellung erfolgt mindestens einmal; GET /webhooks/deliveries zeigt Wiederholungen und endgültig fehlgeschlagene Zustellungen. Entfernen eines Webhooks beendet weitere Zustellungen.

Die optionale WHMCS-Anbindung gleicht ausdrücklich registrierte Dienste und konfigurierte Produkt-Tarif-Zuordnungen ab. Prüfen Sie die Vorschau vor der Anwendung. Unterstützt werden Bereitstellung, Sperrung, Freigabe, Tarifwechsel und Kündigung. Die Anbindung nimmt keine Bestellungen an, erstellt keine Rechnungen, zieht keine Zahlungen ein, löscht keine Kundendaten endgültig und übermittelt keine S3-Geheimnisse. Exportieren Sie abgeschlossene Abrechnungen für Ihr Abrechnungssystem.

Überwachung und Wiederherstellung

Anbieterpersonal verwendet GET /status, GET /monitoring und GET /backups. Auch HTTP 200 kann health=degraded enthalten. Prüfen Sie veraltete Messungen, Erfassungslücken, fehlgeschlagene oder verzögerte Vorgänge, Webhookfehler und Sicherungsaktualität. Sicherungsabfragen liefern Metadaten, keinen Download von Kundendaten.

Nach Aktivierung geplanter Sicherungen gelten standardmäßig sechs Stunden Sicherungsintervall und 30 Tage Aufbewahrung. Administratoren können Intervall, Aufbewahrung und Ziel konfigurieren. Diese Sicherungen schützen Hosting-Datensätze und Abrechnungen, aber keine Ceph-Objekte oder separate Traffic-Historie. Planen Sie Objektschutz und Kopien außerhalb der Installation gesondert.

Wiederherstellung erfordert Wartungsmodus, Prüfung der Sicherung und eine ausdrückliche Entscheidung zum Widerrufen oder Beibehalten wiederhergestellter Tokens/Webhooks. Beibehalten kann inzwischen widerrufene Zugriffe reaktivieren und Zustellungen wiederholen. Prüfen Sie Speicherabweichungen und unterbrochene Vorgänge vor der Freigabe. Wiederherstellung wiederholt keine Speicheränderungen automatisch und rekonstruiert keine fehlenden Messwerte. Der Hosting-Koordinator hat keinen automatischen Failover; prüfen Sie sein Wiederherstellungsverfahren vor dem Produktivbetrieb.