API-Zugang

Die API (Schnittstelle) ermöglicht es fortgeschrittenen Nutzerinnen und Nutzern, selbstverwalten. mit externen Programmen zu verbinden, z. B. für eigene Auswertungen oder die Anbindung an andere Tools.

Wann die API sinnvoll ist

• Automatische Abfragen aus eigenen Skripten
• Kopplung mit Buchhaltungs- oder BI-Tools (sofern vom jeweiligen Anbieter unterstützt)
• Eigenentwicklungen in der WEG (nur mit entsprechender Fachkenntnis)

Für den täglichen Gebrauch durch Eigentümer ist die normale App vorgesehen; die API ist optional.

API-Schlüssel erstellen

1. Öffne die Seite Daten & API (häng /daten an die App-Adresse an, siehe Daten & API) und wähl den Reiter API.
2. Klick auf Neuer API-Schlüssel.
3. Gib einen Namen ein (z. B. „Backup-Skript Heim-PC" oder „DATEV-Export").
4. Wähl die Berechtigungen (Scopes) des Schlüssels: read (lesen), write (schreiben) und/oder delete (löschen). Vergib nur, was das externe Programm wirklich braucht.
5. Speichere. Der Schlüssel wird einmalig angezeigt. Kopier ihn sofort an einen sicheren Ort (z. B. einen Passwort-Manager). Danach ist er aus Sicherheitsgründen nicht mehr lesbar.

Nur WEG-Administratoren können API-Schlüssel anlegen. Jeder Schlüssel ist WEG-spezifisch und gewährt Zugriff auf genau diese eine WEG. Nicht mehr benötigte Schlüssel kannst du in der Liste jederzeit löschen.

Verwendung in Programmen

Sende bei jeder Anfrage den Schlüssel entweder als:

• HTTP-Header X-API-Key: <DEIN-SCHLUESSEL>, oder
• Authorization: Bearer <DEIN-SCHLUESSEL>

Beide Varianten sind gleichwertig. Details zu URLs, Parametern und Response-Formaten findest du in der interaktiven API-Dokumentation unter /api-docs oder in der OpenAPI-Spezifikation (siehe unten).

Verfügbare Bereiche (Beispiele)

Über die API sind u. a. folgende Daten erreichbar:

• Einheiten und Personen
• Transaktionen (Finanzbewegungen)
• Rechnungen
• Beschlüsse
• Vorgänge
• Dokumente (Metadaten)
• WEG-Stammdaten

Die vollständige, aktuelle Liste entnimmst du der OpenAPI-Beschreibung (siehe unten).

Grenzen und Dokumentation

• Häufigkeitsgrenze: Maximal 100 Anfragen pro Minute pro API-Schlüssel. Darüber hinausgehende Anfragen werden mit einem Fehler abgewiesen, warte kurz und versuch es erneut.
• Interaktive Dokumentation: unter /api-docs deiner Installation (z. B. https://app.selbstverwalten.com/api-docs).
• Maschinenlesbare Übersicht aller Endpunkte:
  OpenAPI-Spezifikation unter /api/v1/openapi.json (vollständige URL deiner Installation, z. B. https://app.selbstverwalten.com/api/v1/openapi.json).