API¶

Die HostAdmin REST API ermöglicht den programmatischen Zugriff auf alle wesentlichen Ressourcen des Systems.

Authentifizierung¶

Die API verwendet Service Accounts mit Sanctum-Tokens. Jeder Token ist an einen Service Account gebunden und trägt eine Teilmenge dessen Berechtigungen.

Authorization: Bearer <token>

Service Accounts und Tokens werden in der Admin-Oberfläche unter System > Service Accounts verwaltet (siehe Anleitung).

Pro Integration ein eigener Account

Lege je Konsument (Webfaktbridge, n8n, MCP-Client, …) einen eigenen Service Account an. Bei Leak oder Wechsel kann genau dieser eine widerrufen werden, ohne andere Integrationen zu stören.

Schnittstellen-Schalter¶

Jeder Service Account aktiviert separat REST API und/oder MCP. Für die REST-API muss allow_rest = true sein — für MCP entsprechend allow_mcp = true.

Berechtigungen (Abilities)¶

Ability	Wirkung
`read`	Lesen aller Ressourcen (`GET`)
`write`	Anlegen / Ändern / Löschen (`POST`, `PUT`, `PATCH`, `DELETE`)
`admin`	Vollzugriff (impliziert `read` + `write`)

Ein Token kann nur Abilities tragen, die der zugehörige Service Account erlaubt. Die Endpoint-Tabellen weiter unten zeigen, welche Ability für welchen Aufruf nötig ist.

HTTP-Statuscodes der Auth-Schicht¶

Status	Bedeutung
`401 Unauthenticated`	Kein Token, ungültiger Token, abgelaufener Token, deaktivierter / gelöschter Service Account
`403 Forbidden`	Token gültig, aber Schnittstelle nicht freigegeben (`allow_rest = false`) oder erforderliche Ability fehlt

Basis-URL¶

https://ihre-domain.de/api/w5t

Stripe Webhook

Der Stripe Webhook verwendet einen eigenen Prefix und ist unter /api/stripe/webhook erreichbar. Er nutzt keine Service-Account-Auth, sondern Stripe-Signaturprüfung.

Verfügbare Ressourcen¶

Ressource	Endpunkt	Beschreibung
Customers	`/api/w5t/customers`	Kundenverwaltung
Service Definitions	`/api/w5t/service-definitions`	Service-Vorlagen / Produkte
Customer Services	`/api/w5t/customer-services`	Kunden-Services
Servers	`/api/w5t/servers`	Serververwaltung
Invoices	`/api/w5t/invoices`	Rechnungen
Payments	`/api/w5t/payments`	Zahlungen
Stripe Webhook	`/api/stripe/webhook`	Stripe Event-Verarbeitung

Erforderliche Abilities pro HTTP-Methode¶

Methode	Abilities
`GET`	`read` (oder `admin`)
`POST`, `PUT`, `PATCH`, `DELETE`	`write` (oder `admin`)

Antwortformat¶

Alle Antworten werden als JSON zurückgegeben.

Erfolgreiche Erstellung (201):

{
  "message": "Customer created successfully",
  "customer": { ... }
}

Erfolgreiche Aktualisierung (200):

{
  "message": "Customer updated successfully",
  "customer": { ... }
}

Validierungsfehler (422):

{
  "message": "Validation failed",
  "errors": {
    "email": ["The email field is required."]
  }
}

Auth-Fehler (401 / 403):

{
  "message": "Unauthenticated"
}

{
  "message": "Missing ability: write"
}

Upsert-Verhalten¶

Die POST-Endpunkte (store) verwenden eine Upsert-Logik: Wird ein Datensatz mit dem gleichen eindeutigen Schlüssel gefunden, wird er aktualisiert statt neu erstellt.

Ressource	Upsert-Schlüssel
Customers	`customer_number`
Service Definitions	`article_number`
Customer Services	`service_number`
Servers	`server_number`
Invoices	`invoice_number`
Payments	`payment_reference`