Kommunikation & System

Fünf Bereiche: Mails (der einzige Weg nach außen), Dokumente (Cloudspeicher), Hinweise (Dashboard-Meldungen), Kalender (nur lesend) und Stammdaten (Benutzer, Rollen, Protokoll – ebenfalls nur lesend). Dazu die beiden allgemeinen Endpunkte.

Alle Pfade sind relativ zu https://<domain>/api/v1.

---

Mails

Bereich mails.

Der einzige Endpunkt, der etwas Unwiderrufliches nach außen schickt

Deshalb ist der Versand zweistufig: Ein Werkzeug legt einen Entwurf mit Empfängern an und löst den Versand anschließend ausdrücklich aus. Es gibt kein „anlegen und sofort senden“ in einem Aufruf – ein Schleifenfehler im fremden Skript soll nicht in hundertfachem Mailversand enden.

Methode	Pfad	Bereich	Beschreibung
GET	/mails	mails:read	Nachrichten (Liste)
POST	/mails	mails:write	Entwurf anlegen
GET	/mails/{id}	mails:read	Eine Nachricht
PUT	/mails/{id}	mails:write	Entwurf ändern
DELETE	/mails/{id}	mails:write	Nachricht löschen
POST	/mails/{id}/senden	mails:write	Entwurf versenden
GET	/mails/{id}/anhaenge	mails:read	Anhänge (Liste)
PUT	/mails/{id}/anhaenge	mails:write	Anhang hochladen
GET	/mails/{id}/anhaenge/{anhangId}/inhalt	mails:read	Anhang herunterladen
DELETE	/mails/{id}/anhaenge/{anhangId}	mails:write	Anhang entfernen
GET	/mails/vorlagen	mails:read	Vorlagen (Liste)
POST	/mails/vorlagen	mails:write	Vorlage anlegen
GET	/mails/vorlagen/{id}	mails:read	Eine Vorlage
PUT	/mails/vorlagen/{id}	mails:write	Vorlage ändern
DELETE	/mails/vorlagen/{id}	mails:write	Vorlage löschen
GET	/mails/ordner	mails:read	Ordner (Liste)

Filter: q (Betreff, Empfänger), status (draft oder sent), ordner_id, archiviert. Sortierung: fest, neueste zuerst – diese Liste kennt kein sort.

Felder einer Nachricht

Feld	Typ	Anmerkung
subject	Text	Pflicht
body_html	Text	der Inhalt; Platzhalter wie in der Anwendung
reply_to	E-Mail	abweichendes „Antwort an“
include_signature, signature_id	Signatur
template_id	UUID	verwendete Vorlage
folder_id	UUID	Ordner, siehe /mails/ordner
targets	Liste	die Empfänger

Ein Empfänger-Eintrag hat target_type (group, list, contact oder email) und je nachdem target_id oder email, optional label:

{
  "subject": "Sommerlager 2026",
  "body_html": "<p>Hallo {{vorname}},</p><p>…</p>",
  "targets": [
    { "target_type": "group", "target_id": "<uuid>" },
    { "target_type": "email", "email": "presse@example.org", "label": "Presse" }
  ]
}

Wird ein PUT mit targets geschickt, ersetzt es die Empfängerliste vollständig. Eine versendete Nachricht lässt sich nicht mehr ändern (400).

Versenden

curl -X POST -H "Authorization: Bearer $KEY" "$BASIS/mails/<id>/senden"

Ohne Empfänger und bei bereits versendeten Nachrichten kommt 400. Der Versand läuft über denselben Dienst wie die Anwendung: dieselbe Personalisierung, dieselben Platzhalter, dieselbe Protokollierung. Bleibt der Mailserver stumm, greift die Warteschlange der Anwendung.

Anhänge

Anhänge gehören zum Entwurf. Nach dem Versand lassen sie sich weder hinzufügen noch entfernen: Was im Postfach der Empfänger liegt, ändert kein späterer Aufruf mehr.

curl -X PUT -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/pdf" --data-binary @programm.pdf \
  "$BASIS/mails/<id>/anhaenge?name=programm.pdf"

Obergrenze 10 MB – Anhänge liegen in der Datenbank und gehen anschließend als Kopie an jede Empfängerin.

Vorlage: name (Pflicht), subject, body_html.

---

Dokumente

Bereich dokumente. Ordner und Dateien im Cloudspeicher.

Ein Schlüssel sieht alle Ordner

Die Freigaben je Ordner hängen an Benutzerkonten und Rollen; ein Schlüssel hat weder das eine noch das andere. Er kann also nicht „nur die freigegebenen Ordner“ sehen. Wer nur einzelne Ordner nach außen geben will, nimmt die Freigabelinks der Anwendung.

System-Ordner der Anwendung (z. B. Anhänge von Hinweisen) bleiben auch hier tabu.

Methode	Pfad	Bereich	Beschreibung
GET	/dokumente/ordner	dokumente:read	Ordner einer Ebene (Liste)
POST	/dokumente/ordner	dokumente:write	Ordner anlegen
GET	/dokumente/ordner/{id}	dokumente:read	Ordner samt Inhalt
DELETE	/dokumente/ordner/{id}	dokumente:write	Ordner in den Papierkorb
GET	/dokumente/{id}	dokumente:read	Angaben zur Datei
GET	/dokumente/{id}/inhalt	dokumente:read	Datei herunterladen
PUT	/dokumente/upload	dokumente:write	Datei hochladen
DELETE	/dokumente/{id}	dokumente:write	Datei in den Papierkorb

GET /dokumente/ordner listet die oberste Ebene; mit eltern_id die Ebene darunter. GET /dokumente/ordner/{id} liefert den Ordner mit ordner (Unterordner) und dateien.

Ordner anlegen: {"name":"Protokolle","eltern_id":"<uuid oder weglassen>"}.

Hochladen – Ziel und Name kommen als Query-Parameter, der Rumpf ist die Datei:

curl -X PUT -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/pdf" --data-binary @bericht.pdf \
  "$BASIS/dokumente/upload?ordner_id=<uuid>&name=bericht.pdf"

Bis 2 GB; nichts läuft dabei durch den Arbeitsspeicher des Servers. Dateinamen mit Pfadtrennern werden abgewiesen.

DELETE legt Datei oder Ordner in den Papierkorb ("papierkorb": true); endgültiges Löschen bleibt der Anwendung vorbehalten.

---

Hinweise

Bereich hinweise. Zentrale Meldungen auf dem Dashboard – nützlich, um Meldungen aus einem anderen System einzuspielen („Hallenbad gesperrt“, „Anmeldung öffnet Montag“).

Methode	Pfad	Bereich	Beschreibung
GET	/hinweise	hinweise:read	Liste
POST	/hinweise	hinweise:write	Anlegen
GET	/hinweise/{id}	hinweise:read	Einzeln lesen
PUT	/hinweise/{id}	hinweise:write	Ändern
DELETE	/hinweise/{id}	hinweise:write	Löschen

Sortierbar: created_at (Standard), title, starts_at, expires_at.

Feld	Typ	Anmerkung
title	Text	Pflicht
body	Text
level	info | warn | critical	bestimmt die Farbe
starts_at, expires_at	Zeitpunkt	befristete Anzeige
is_active	Wahrheitswert
dismissible	Wahrheitswert	darf weggeklickt werden
pinned	Wahrheitswert	oben anheften
audience	Text	Zielgruppe
show_on_dashboard	Wahrheitswert
show_on_login	Wahrheitswert	öffentlich sichtbar auf der Anmeldeseite
show_in_portal	Wahrheitswert	im Mitgliederportal
link_url	Text	weiterführender Link

Zwei Felder mit Wirkung nach außen

show_on_login und show_in_portal machen eine Meldung für Leute sichtbar, die nicht angemeldet sind bzw. keine Verwaltungsrechte haben. Im Zweifel aus.

link_url wird geprüft und normalisiert (pfadfinder.de → https://pfadfinder.de/). Nur http und https – ein javascript:-Ziel wird gar nicht erst gespeichert.

Anhänge lassen sich hier nicht setzen: Sie liegen als Dateien in einem System-Ordner, den die Schnittstelle bewusst nicht anfasst.

---

Kalender

Bereich kalender, nur lesend.

Methode	Pfad	Bereich	Beschreibung
GET	/kalender	kalender:read	Termine (Liste)

Filter: von, bis (je JJJJ-MM-TT).

{
  "data": [
    { "art": "veranstaltung", "id": "…", "titel": "Sommerlager", "ort": "Wiese",
      "start_date": "2026-08-01", "end_date": "2026-08-10" },
    { "art": "packliste", "id": "…", "titel": "Sommerlager Material",
      "start_date": "2026-07-30", "end_date": "2026-08-11" },
    { "art": "ausleihe", "id": "…", "titel": "Verliehen an Maja Beispiel",
      "start_date": "2026-08-14", "end_date": "2026-08-16" }
  ],
  "meta": { "total": 3, "von": null, "bis": null }
}

Termine gibt es hier nicht als eigenes Ding – sie sind immer die Sicht auf eine Veranstaltung, eine Packliste oder eine Ausleihe. Wer einen Termin anlegen will, legt eine Veranstaltung an. Deshalb hat dieser Bereich gar keinen Schreibweg.

Termine, die in den Zeitraum hineinragen, kommen mit – ein zweiwöchiges Lager taucht auch dann auf, wenn man nur nach der mittleren Woche fragt. Archivierte Veranstaltungen und Geburtstage bleiben draußen.

---

Stammdaten

Bereich stammdaten, nur lesend. Wer über einen Schlüssel Konten anlegen oder Rollen ändern könnte, könnte sich damit selbst mehr Rechte verschaffen, als der Schlüssel je hatte.

Methode	Pfad	Bereich	Beschreibung
GET	/stammdaten/benutzer	stammdaten:read	Konten der Verwaltung (Liste)
GET	/stammdaten/rollen	stammdaten:read	Rollen samt Rechten
GET	/stammdaten/rechte	stammdaten:read	Der Rechte-Katalog der Anwendung
GET	/stammdaten/protokoll	stammdaten:read	Aktivitätsprotokoll (Liste)
GET	/stammdaten/einstellungen	stammdaten:read	Öffentliche Systemeinstellungen

Protokoll-Filter: q (Objekt und Konto), benutzer_id, objekt_art, objekt_id, aktion (created, updated, deleted …). Sortierung: fest, neueste zuerst. updated_since heißt hier seither angelegt – ein Protokolleintrag ändert sich nie.

Externe Überwachung ist ein guter Grund für eine Schnittstelle

„Hat sich in den letzten 24 Stunden jemand an den Bankdaten zu schaffen gemacht?“ soll man von außen beantworten können – deshalb ist das Protokoll lesbar.

GET /stammdaten/einstellungen liefert system_name, system_subtitle, primary_color, secondary_color, contact_email, required_fields, portal_enabled und documents_enabled – ohne Zugangsdaten und ohne Logo/Favicon, die als Data-URL mehrere hundert Kilobyte groß wären.

---

Allgemein

Methode	Pfad	Bereich	Beschreibung
GET	/me	–	Prüft den Schlüssel und nennt seine wirksamen Bereiche
GET	/openapi.json	–	Die maschinenlesbare Beschreibung (OpenAPI 3.1)

Beide brauchen keinen Bereich, aber sehr wohl einen gültigen Schlüssel – auch openapi.json. Details unter Zugang & Schlüssel.