Menschen

Vier Bereiche rund um Personen: Mitglieder (Stammdaten), Gruppen & Verteiler (wer gehört zu wem), Warteliste (wer möchte dazu) und Nachweise (Führungszeugnisse und befristete Nachweise).

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

---

Mitglieder

Bereich mitglieder · Repository derselbe wie in der Oberfläche. Ein über die Schnittstelle angelegtes Mitglied bekommt seine Mitgliedsnummer genauso automatisch wie eines aus der Anwendung.

Methode	Pfad	Bereich	Beschreibung
GET	/mitglieder	mitglieder:read	Liste
POST	/mitglieder	mitglieder:write	Anlegen
GET	/mitglieder/{id}	mitglieder:read	Einzeln lesen
PUT	/mitglieder/{id}	mitglieder:write	Ändern
DELETE	/mitglieder/{id}	mitglieder:write	Löschen
POST	/mitglieder/{id}/kuendigen	mitglieder:write	Mitgliedschaft kündigen
GET	/mitglieder/beitragsstufen	mitglieder:read	Beitragsstufen (Liste)
GET	/mitglieder/felder	mitglieder:read	Die selbst angelegten Felder
GET	/mitglieder/{id}/familie	mitglieder:read	Familien-Verknüpfungen (Liste)
POST	/mitglieder/{id}/familie	mitglieder:write	Verknüpfung anlegen
DELETE	/mitglieder/{id}/familie/{relatedId}	mitglieder:write	Verknüpfung lösen
GET	/mitglieder/{id}/gruppen-historie	mitglieder:read	Zeiträume (Liste)
POST	/mitglieder/{id}/gruppen-historie	mitglieder:write	Zeitraum anlegen
PUT	/mitglieder/{id}/gruppen-historie/{eintragId}	mitglieder:write	Zeitraum korrigieren
DELETE	/mitglieder/{id}/gruppen-historie/{eintragId}	mitglieder:write	Zeitraum entfernen

Liste filtern

Parameter	Bedeutung
q	Suche über Name, E-Mail und Mitgliedsnummer
gruppe_id	Nur Mitglieder dieser Gruppe
art	member oder contact
status	applicant, active oder cancelled
nur_aktive	true = nur aktive
label	Nur Mitglieder mit diesem Label

Sortierbar: last_name (Standard), first_name, member_number, email, join_date, leave_date, created_at, updated_at.

Diese Liste blättert in der Datenbank – sie ist die größte des Systems und wird nicht für jede Seite komplett geladen. updated_since wirkt hier echt filternd.

Felder

Feld	Typ	Anmerkung
kind	member | contact	Mitglied oder reiner Kontakt
membership_status	applicant | active | cancelled
salutation	du | sie	Anrede in Serienmails
title, first_name, last_name	Text
gender	weiblich | maennlich | nonbinaer | ""
email, email_cc	E-Mail	wird auf Gültigkeit geprüft
phone	Text
phones	Liste aus label + number	mehrere Nummern mit Beschriftung
street, address_extra, zip, city, country	Text
member_number	Text	beim Anlegen automatisch, wenn kind = member
group_ids	Liste von UUIDs	Mehrfachzugehörigkeit ist möglich
birth_date, join_date, leave_date	JJJJ-MM-TT
diet, intolerances, health_info, swim	Text	Gesundheits- und Verpflegungsangaben
fee_level_id	UUID	gültige Werte über /mitglieder/beitragsstufen
membership_fee	Zahl ≥ 0	abweichender Einzelbetrag
payment_method, iban, bic, account_holder	Text	Bankverbindung
custom_values	Objekt	Schlüssel über /mitglieder/felder
labels	Liste von Texten
notes	Text
is_active	Wahrheitswert

Beim Anlegen ist ein Merkmal Pflicht

Mindestens Vorname, Nachname oder E-Mail muss gesetzt sein. Ein Kontakt ohne Name und ohne Adresse ist eine leere Zeile, die niemandem hilft.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"kind":"member","first_name":"Maja","last_name":"Beispiel","email":"maja@example.org","group_ids":["…"]}' \
  "$BASIS/mitglieder"

Kündigen

POST /mitglieder/{id}/kuendigen mit optionalem austritt_am (ohne Angabe: heute).

Warum ein eigener Endpunkt und nicht PUT {"membership_status":"cancelled"}

Am Kündigen hängen das Austrittsdatum, die Bestätigungsmail an das Mitglied und die Benachrichtigung der Verwaltung. Wer nur die Spalte setzt, bekommt ein stilles Ende ohne beides.

Familie

Familien-Verknüpfungen gelten gegenseitig – deshalb gibt es kein Richtungsfeld. POST erwartet {"related_id":"<uuid>"} und antwortet mit der vollständigen Liste. Eine Person lässt sich nicht mit sich selbst verknüpfen.

Gruppen-Historie

Die aktuelle Zugehörigkeit steht in group_ids am Mitglied. Hier liegen die Zeiträume, aus denen sich Stufenwechsel nachvollziehen lassen.

Feld	Typ	Anmerkung
group_id	UUID	nur beim Anlegen; ein PUT ändert die Gruppe nicht
from_date, to_date	JJJJ-MM-TT
note	Text

---

Gruppen & Verteiler

Bereich gruppen. Beides liegt zusammen, weil beides dieselbe Frage beantwortet: wer gehört zu wem. Eine Gruppe ist die fachliche Zugehörigkeit eines Mitglieds, ein Verteiler eine frei zusammengestellte Empfängerliste.

Methode	Pfad	Bereich	Beschreibung
GET	/gruppen	gruppen:read	Liste
POST	/gruppen	gruppen:write	Anlegen
GET	/gruppen/{id}	gruppen:read	Einzeln lesen
PUT	/gruppen/{id}	gruppen:write	Ändern
DELETE	/gruppen/{id}	gruppen:write	Löschen
GET	/gruppen/{id}/mitglieder	gruppen:read	Mitglieder dieser Gruppe (Liste)
GET	/gruppen/verteiler	gruppen:read	Verteiler (Liste)
POST	/gruppen/verteiler	gruppen:write	Verteiler anlegen
GET	/gruppen/verteiler/{id}	gruppen:read	Verteiler samt Empfängern
PUT	/gruppen/verteiler/{id}	gruppen:write	Verteiler ändern
DELETE	/gruppen/verteiler/{id}	gruppen:write	Verteiler löschen
PUT	/gruppen/verteiler/{id}/mitglieder	gruppen:write	Empfängerliste vollständig ersetzen

Gruppe: name (Pflicht, max. 120), description (max. 500), sort_order (Zahl). Sortierbar nach name, sort_order (Standard), created_at.

Verteiler: name (Pflicht), description.

Empfänger setzen:

{
  "members": [
    { "contact_id": "8f2c…" },
    { "email": "presse@example.org", "name": "Presse" }
  ]
}

Je Eintrag ist entweder contact_id oder email nötig – Verteiler dürfen auch Leute enthalten, die kein Mitglied sind. Der Aufruf ersetzt die Liste vollständig; ein Einzel-Hinzufügen gibt es bewusst nicht, weil ein Abgleich von außen die Menge als Ganzes schreibt.

Der häufigste Lesezugriff überhaupt

GET /gruppen/{id}/mitglieder – die Mitglieder einer Stufe für die Vereinswebsite oder einen Serienbrief.

---

Warteliste

Bereich warteliste. Typischer Fall von außen: Das Anmeldeformular der Website trägt Interessierte direkt in die Warteliste der passenden Stufe ein.

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

Filter: gruppe_id, q (Namen und E-Mail). Sortierbar: waitlist_date (Standard), last_name, birth_date, status.

Feld	Typ	Anmerkung
group_id	UUID	die gewünschte Stufe
first_name, last_name	Text	das Kind
birth_date	JJJJ-MM-TT	Grundlage fürs Aufrücken
contact_name, email, phone	Text	die Eltern
note	Text
status	wartend | kontaktiert | aufgenommen | abgesagt
waitlist_date	JJJJ-MM-TT	ohne Angabe: heute; bestimmt die Reihenfolge

---

Nachweise

Bereich nachweise. Führungszeugnisse und befristete Nachweise (Juleica, Erste Hilfe …).

Die Dateien gibt es über die Schnittstelle nicht

Dass für eine Person ein Führungszeugnis vorliegt, ist eine besonders schutzwürdige Angabe. Über die Schnittstelle kommt nur der Sachstand – vorgelegt, geprüft, gültig bis. Wer die Datei braucht, öffnet sie in der Anwendung; die Aufbewahrungsregel „FZ-Dateisperre“ bleibt so unangetastet.

Methode	Pfad	Bereich	Beschreibung
GET	/nachweise/typen	nachweise:read	Nachweis-Arten (Liste)
GET	/nachweise/uebersicht	nachweise:read	Sachstand: wer braucht was, und wie steht es darum
GET	/nachweise/typen/{typId}/anforderungen	nachweise:read	Wer diesen Nachweis braucht
PUT	/nachweise/typen/{typId}/anforderungen	nachweise:write	Anforderungen setzen
GET	/nachweise/mitglied/{contactId}	nachweise:read	Nachweise einer Person (Liste)
GET	/nachweise/{id}	nachweise:read	Einzeln lesen
POST	/nachweise	nachweise:write	Anlegen bzw. Stand aktualisieren
PUT	/nachweise/{id}	nachweise:write	Ändern
DELETE	/nachweise/{id}	nachweise:write	Löschen

Filter der Übersicht: typ_id, gruppe_id, mitglied_id.

Feld	Typ	Anmerkung
contact_id	UUID	Pflicht beim Anlegen, danach unveränderlich
type_id	UUID	Pflicht beim Anlegen, danach unveränderlich
issued_on, valid_from, valid_until	JJJJ-MM-TT
inspected	Wahrheitswert	Einsichtnahme erfolgt
inspector_name	Text
inspected_at	JJJJ-MM-TT
exempt	Wahrheitswert	von der Pflicht befreit
notes	Text
custom_values	Objekt	eigene Felder der Nachweis-Art

Je Person und Art gibt es genau einen aktuellen Stand: Ein zweites POST ersetzt ihn, der alte wandert in die Historie. Ist für die Art die Bestätigung „Erhalten“ eingeschaltet, geht sie auch dann raus, wenn der Stand über die Schnittstelle kommt – meta.mailed in der Antwort sagt, ob eine Mail verschickt wurde.

Anforderungen setzen:

{ "gruppen": ["<uuid>", "<uuid>"], "mitglieder": ["<uuid>"] }

Jede mitgeschickte Liste wird vollständig ersetzt, eine weggelassene bleibt unangetastet – so lassen sich Gruppen ändern, ohne die einzeln benannten Personen zu verlieren.

updated_since auf der Übersicht

Der Sachstand entsteht aus mehreren Tabellen und trägt keinen eigenen Zeitstempel. Ein updated_since läuft hier bewusst in einen 400 statt eine leere Liste vorzutäuschen – siehe Konventionen.