Schnittstelle (REST-API)

Adresse: /einstellungen/api · Recht: REST-API & Zugangsschlüssel verwalten (api.manage)

Die Schnittstelle unter /api/v1 erlaubt eigenen Werkzeugen den Zugriff – der Vereinswebsite, einem Anmeldetool, einer eigenen Auswertung.

Zugang beantragen

Die Schnittstelle ist nicht von Haus aus offen. Sie wird beantragt – mit Verwendungszweck – und von der Instanz-Verwaltung freigeschaltet.

Bereiche freigeben

Je Bereich wird eingestellt:

Stufe	Bedeutung
aus	Kein Zugriff
nur lesen	Lesender Zugriff
lesen & bearbeiten	Voller Zugriff

Diese Einstellung ist die Obergrenze für alle Schlüssel. Ein Schlüssel kann nie mehr dürfen als der Bereich hergibt – auch wenn er weiter gefasst ausgestellt wurde. Wird ein Bereich zurückgestellt, verlieren bestehende Schlüssel ihre Rechte darin sofort; niemand muss Schlüssel nachpflegen.

Ab Werk steht jeder Bereich auf „aus". Das gilt auch für Bereiche, die später dazukommen – ein neuer Bereich öffnet sich nie von selbst.

Welche Bereiche es gibt

Bereich	Inhalt
Mitglieder	Stammdaten, Gruppen, Familie, Gruppen-Historie, Kündigung
Gruppen & Verteiler	Stufen und Mail-Verteiler
Material	Exemplare, Artikel, Sets, Kategorien, Lagerorte
Fahrzeuge	Fahrzeugstammdaten
Packlisten	Listen samt Positionen und Fahrzeugen
Verleih	Ausleihen, Verfügbarkeiten, Statuswechsel
Veranstaltungen	Lager und Aktionen samt Teilnehmenden, Zahlungen und Vorlagen
Nachweise	Führungszeugnisse und befristete Nachweise – ohne die Dateien
Bankbuchhaltung	Konten, Buchungen, Belege samt Belegbild, Kostenstellen
Beiträge	Sammlungen und Forderungen
Spendenbescheinigungen	Zuwendungsbestätigungen samt PDF
Fahrtkosten	Abrechnungen samt Fahrten und PDF
Teilnahmebescheinigungen	Die Vorlagen für Bescheinigungen und Sonderurlaub
Abrechnung	Abrechnungen, Belege, Einnahmen
Kalkulation	Budgetplanung
Mails	Nachrichten, Vorlagen, Anhänge, Versand
Dokumente	Ordner und Dateien im Cloudspeicher
Warteliste	Stufen-Wartelisten
Hinweise	Meldungen auf der Startseite
Kalender	Termine – nur lesend
Stammdaten & Protokoll	Konten, Rollen, Rechte, Aktivitätsprotokoll – nur lesend

Ein paar Vorgänge greifen über ihren Bereich hinaus und verlangen deshalb beide Freigaben: Eine Spendenbescheinigung oder eine Fahrtkostenabrechnung „als Beleg ablegen" schreibt in die Buchhaltung und braucht sie zusätzlich; eine Teilnahmebescheinigung braucht Veranstaltungen und die Bescheinigungs-Vorlagen.

Dokumente sehen alles

Die Freigaben je Ordner hängen an Benutzerkonten und Rollen. Ein Schlüssel hat weder das eine noch das andere – ein Schlüssel mit dem Bereich Dokumente sieht deshalb alle Ordner. Wer nur einzelne Ordner nach außen geben will, nimmt die Freigabelinks des Dokumentenbereichs, nicht die Schnittstelle.

Zugangsschlüssel

Ein Zugangsschlüssel ist das Passwort eines Programms.

• Laufzeit: 30, 90 oder 180 Tage – höchstens sechs Monate
• Der Schlüssel wird genau einmal angezeigt. Danach nie wieder.
• Je Schlüssel lässt sich die Zahl der Anfragen pro Minute begrenzen
• Letzte Nutzung und Aufrufzahl sind einsehbar
• Widerrufen macht ihn sofort ungültig

Beim Erzeugen sofort sichern

Der Schlüssel erscheint ein einziges Mal. Leg ihn direkt dort ab, wo er hingehört – in die Konfiguration deines Werkzeugs oder in einen Passwortspeicher. Verloren heißt: neu erzeugen.

Und: Ein Schlüssel gehört niemals in Frontend-Code einer Website. Wer die Seite aufruft, kann ihn auslesen.

Ablauf-Erinnerung

14 Tage und 3 Tage vor Ablauf eines Schlüssels geht automatisch eine Mail heraus. Das verhindert die Website, die an einem Dienstagmorgen ohne Vorwarnung keine Termine mehr anzeigt.

Nachvollziehbarkeit

Jeder schreibende Zugriff steht im Aktivitätsprotokoll unter dem Schlüsselnamen.

Deshalb lohnen sprechende Namen: Website Termine, Anmeldetool, Auswertung Kasse – nicht Test oder Key 2.

Was die Schnittstelle bewusst nicht kann

Diese Grenzen sind keine Lücken:

• Konten, Rollen und Rechte ändern, ebenso Anmeldung, zweiter Faktor, SMTP und Speicheranbindung. Wer das über einen Schlüssel könnte, könnte sich mehr Rechte verschaffen, als der Schlüssel je hatte.
• Schlüssel verwalten. Ein Schlüssel, der sich selbst verlängern kann, hat kein Ablaufdatum.
• Kontoauszüge einlesen und SEPA-Dateien erzeugen – beides bleibt ein bewusster Vorgang in der Anwendung, mit Dubletten-Erkennung bzw. Vorschau.
• Nachweis-Dateien herunterladen. Der Sachstand ja, die Datei nein.
• Veranstaltungen endgültig löschen – Löschen legt sie in den Papierkorb.
• Ausstellungs-Angaben ändern (Anschrift, Unterschriftsbild, Nummernkreise, Kilometersatz). Lesen ja: ein Werkzeug muss den Kilometersatz kennen, um einen Betrag anzeigen zu können.
• Spendenbescheinigungen löschen. Sie tragen eine fortlaufende Nummer und gehen ans Finanzamt; es gibt nur den Storno mit Begründung.
• Entfernungen berechnen lassen. Das kostet Kontingent beim Kartendienst; ein Skript in einer Schleife hätte es aufgebraucht, bevor es jemand merkt.

Ebenfalls nicht angebunden – weniger aus Prinzip, sondern schlicht nicht gebaut: Mitgliederportal, Benachrichtigungen, Aufbewahrungsfristen, CSV-Import, gespeicherte Filter und die Belegerkennung.

Technische Beschreibung

Eine maschinenlesbare Beschreibung für Postman, Insomnia oder Client-Generatoren liegt unter /api/v1/openapi.json. Sie ist immer aktuell: Ein Test vergleicht sie bei jeder Änderung Pfad für Pfad mit der tatsächlichen Schnittstelle.

Auch die Beschreibung braucht einen Schlüssel

Im Browser aufgerufen antwortet /api/v1/openapi.json mit missing_token. Sie lässt sich mit curl -H "Authorization: Bearer …" herunterladen und dann als Datei importieren.

Die vollständige Entwickler-Referenz – alle Endpunkte, Felder, Filter, Fehlercodes und fertige Beispiele – steht unter Referenz → REST-API.

Wann sich das lohnt – und wann nicht

Lohnt sich: Termine automatisch auf der Vereinswebsite anzeigen, eine wiederkehrende Auswertung, die Anbindung eines bestehenden Werkzeugs.

Lohnt sich nicht: Ein einmaliger Datenabzug – dafür gibt es in fast jedem Bereich einen Export als CSV, Excel oder PDF, ohne Antrag und ohne Schlüsselverwaltung.