Schnittstelle (API)
Version 1 · Stand: 16.11.2026
1. Wozu
Über die Schnittstelle (API) arbeiten andere Systeme mit den Daten eurer Feuerwehr: die Webseite zeigt die Mannschaft, die Alarmierung holt Telefonnummern, ein Lehrgangsportal trägt bestandene Lehrgänge ein. Alles, was dort möglich ist, läuft durch dieselben Regeln wie die Oberfläche: Rechte, Pflichtfelder, Fristen und die Trennung der Feuerwehren gelten genauso.
Die Schnittstelle hat eine eigene Adresse für alle Feuerwehren: https://api.fwmax.de/v1. Welche Feuerwehr gemeint ist, sagt der Schlüssel. Unter api.fwmax.de lässt sich jede Adresse mit Beispielen ansehen und gleich ausprobieren. Antworten und Eingaben sind JSON mit den Fachbegriffen der Oberfläche, zum Beispiel personalnummer, gueltigVon, organisationseinheitId. Datumsangaben haben die Form 2026-11-16.
2. Schlüssel anlegen
In der Anwendung unter Verwaltung, Schnittstelle legt ihr für jedes fremde System einen eigenen Schlüssel an: mit Namen, den Rechten aus der Rechte-Matrix, wahlweise nur für eine Einheit mit allem darunter und wahlweise mit Ablaufdatum.
- Der Schlüssel beginnt mit
fwmax_und wird genau einmal angezeigt. Gespeichert ist nur ein Prüfwert; wir können ihn nicht wieder anzeigen. - Ein Schlüssel kann jederzeit gesperrt, entsperrt oder gelöscht werden. Das wirkt sofort.
- Niemand kann einem Schlüssel mehr Rechte geben, als er selbst hat.
- Benutzer, Schlüssel und das Konto der Feuerwehr kann ein Schlüssel nie verwalten.
3. Anmelden
Der Schlüssel steht bei jedem Aufruf im Kopf Authorization:
curl -H "Authorization: Bearer fwmax_DEIN_SCHLUESSEL" \
https://api.fwmax.de/v1/personen
Die Anmeldung einer Person (Cookie) zählt für die Schnittstelle nicht. Mit dem Schlüssel demo antwortet die Live-Demo, damit ihr sofort etwas ausprobieren könnt; schreiben kann dort niemand.
4. Ausprobieren mit der Live-Demo
curl -H "Authorization: Bearer demo" "https://api.fwmax.de/v1/personen?suche=braun"
[
{
"id": 155,
"personalnummer": "0011",
"vorname": "Mia",
"nachname": "Braun",
"dienstgrad": "Oberfeuerwehrmann/-frau",
"funktionen": ["Atemschutzgeräteträger/in"],
"dienstjahre": 9,
"atemschutz": "Tauglich",
"nachweiseAbgelaufen": 1,
"nachweiseBaldFaellig": 1
}
]
Welche Nachweise laufen in den nächsten 60 Tagen ab?
curl -H "Authorization: Bearer demo" "https://api.fwmax.de/v1/fristen?tage=60"
Schnittstelle im Browser ausprobieren: Dort ist der Schlüssel demo schon eingetragen.
5. Adressen
Die Schnittstelle unter https://api.fwmax.de/v1 ist in Bereiche gegliedert. Jede Adresse mit Feldern, Beispielen und Rechten steht in der interaktiven Referenz und in der OpenAPI-Beschreibung.
| Bereich | Adressen |
|---|---|
| Organisation | /organisationseinheiten |
| Personen | /personen, /fristen |
| Kataloge | /kataloge/dienstgrade, /kataloge/funktionen, /kataloge/nachweisarten, /kataloge/mitgliedschaftsarten, /kataloge/organisationsarten, /kataloge/einsatzarten, /stichworte |
| Fahrzeuge | /fahrzeuge |
| Alarmierung | /alarme |
| Einsätze | /einsaetze, /einsaetze/fe2 (Eingang für Alamos FE2) |
| Dienste | /dienste |
| Lehrgänge | /lehrgaenge, /nachweise |
| Ehrungen | /ehrungen, /ehrungen/vorschlaege, /ehrungen/faellig |
| Statistik | /statistik/einsaetze, /statistik/dienste |
| Material | /material, /material/pruefungen |
| Atemschutz | /atemschutz/traeger, /atemschutz/eintraege |
| Objekte | /objekte, /wasserentnahmestellen |
| Adressbuch | /adressbuch |
| Kleiderkammer | /kleiderkammer/bestand |
| App | /app/… (Anmeldung, Alarme, Dienste, Einsätze, Nachrichten, Ausweis, Anwesenheit) |
| Betrieb | /herzschlag; Änderungen zusätzlich als Webhooks und Ereignisse (CloudEvents) |
Beispiele: Personen und Organisation
| Adresse | Zweck | Nötiges Recht |
|---|---|---|
GET /v1 | Wer bin ich: Feuerwehr, Version, Name des Schlüssels und seine Rechte | keines |
GET /v1/openapi.json | Maschinenlesbare Beschreibung (OpenAPI 3.1), ohne Schlüssel abrufbar | keines |
GET /v1/organisationseinheiten | Alle Einheiten in Baumreihenfolge; ?aufgeloeste=true zeigt auch aufgelöste | keines |
GET /v1/organisationseinheiten/{id} | Eine Einheit | keines |
POST /v1/organisationseinheiten | Einheit anlegen | Organisation bearbeiten |
PUT /v1/organisationseinheiten/{id} | Einheit ändern | Organisation bearbeiten |
GET /v1/personen | Personalliste; Filter suche, einheit, ehemalige, jugend | Personal ansehen |
GET /v1/personen/{id} | Vollständige Personalakte | Personal ansehen |
POST /v1/personen | Person anlegen | Personal bearbeiten |
PUT /v1/personen/{id} | Stammdaten ändern | Personal bearbeiten |
POST /v1/personen/{id}/mitgliedschaften | Mitgliedschaft eintragen | Personal bearbeiten |
POST /v1/personen/{id}/nachweise | Nachweis eintragen (Lehrgang, Untersuchung, Unterweisung, Führerschein, Abzeichen, Ehrung) | Personal bearbeiten |
POST /v1/personen/{id}/kontaktpersonen | Kontaktperson eintragen | Personal bearbeiten |
GET /v1/fristen | Abgelaufene und bald ablaufende Nachweise; ?tage=90 | Personal ansehen |
GET /v1/kataloge/dienstgrade | Katalog der Dienstgrade | keines |
GET /v1/kataloge/funktionen | Katalog der Funktionen | keines |
GET /v1/kataloge/nachweisarten | Katalog der Nachweisarten | keines |
GET /v1/kataloge/mitgliedschaftsarten | Katalog der Mitgliedschaftsarten | keines |
GET /v1/kataloge/organisationsarten | Katalog der Arten von Einheiten | keines |
Die genauen Felder jeder Eingabe stehen in der maschinenlesbaren Beschreibung: openapi.json. Sie lässt sich in gängige Werkzeuge laden.
Lange Listen
Dienste, Lehrgänge, Nachweise und Ehrungen kommen seitenweise: ?seite=2&proSeite=100 (höchstens 500 je Seite). Die Antwort bleibt eine Liste; die Gesamtzahl steht in der Kopfzeile X-Gesamtzahl, die nächste Seite in Link.
curl -i -H "Authorization: Bearer demo" "https://api.fwmax.de/v1/dienste?art=Uebung&proSeite=20"
Alarm aus Alamos FE2
FE2 sendet jeden Alarm per HTTP-Ausgang als JSON an POST /v1/einsaetze/fe2, mit einem Schlüssel mit dem Recht Einsätze bearbeiten. Dieselbe externe Einsatznummer legt im selben Jahr keinen zweiten Einsatz an.
curl -X POST https://api.fwmax.de/v1/einsaetze/fe2 -H "Authorization: Bearer fwmax_DEIN_SCHLUESSEL" -H "Content-Type: application/json" -d '{"data": {"keyword": "B3", "keyword_description": "Wohnungsbrand", "einsatznummer": "LST-2026-004711", "street": "Hauptstraße", "house": "12", "city": "Musterstadt"}}'
Einsätze auf der Homepage
Ohne Programmierung geht es mit dem Einsatz-Widget: in fwMAX.de unter Verwaltung, API-Schnittstelle anlegen, festlegen, was zu sehen ist, und den Einbettungscode in die Homepage kopieren. Namen und Hausnummern zeigt das Widget nie.
6. Schreiben
Eine Person anlegen. Pflicht ist nur der Nachname; die Personalnummer wird vergeben, wenn sie fehlt.
curl -X POST https://api.fwmax.de/v1/personen \
-H "Authorization: Bearer fwmax_DEIN_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{"vorname": "Jana", "nachname": "Keller", "geburtsdatum": "2004-05-12", "eMailAdresse": "jana.keller@example.org"}'
Einen bestandenen Lehrgang eintragen. Ohne gueltigBis gilt die Gültigkeit der Nachweisart aus dem Katalog.
curl -X POST https://api.fwmax.de/v1/personen/155/nachweise \
-H "Authorization: Bearer fwmax_DEIN_SCHLUESSEL" \
-H "Content-Type: application/json" \
-d '{"nachweisartId": 9, "erworbenAm": "2026-11-14", "ausgestelltVon": "Rotes Kreuz"}'
Beim Ändern mit PUT bleiben Felder, die in der Eingabe fehlen, wie sie sind.
7. Rechte
Ein Recht ist immer „worum es geht“ plus „was man tut“, zum Beispiel Personal ansehen oder Personal bearbeiten. Ein Schlüssel hat genau die Rechte, die beim Anlegen angekreuzt wurden.
- Wer etwas bearbeiten darf, darf es auch ansehen.
- Gilt ein Schlüssel nur für eine Einheit, sieht er nur Personen, die dort oder darunter Mitglied sind oder waren.
- Die Gesundheitsangaben einer Akte sind nur mit dem Recht Gesundheitsangaben ansehen gefüllt, sonst leer.
- Einheiten und Kataloge darf jeder Schlüssel lesen.
8. Fehler
Fehler haben immer dieselbe Form, mit einem Text, den man einem Menschen zeigen kann:
{ "fehler": "Dafür fehlt das Recht „Personal bearbeiten“." }
| Status | Bedeutung |
|---|---|
| 400 | Die Eingabe stimmt nicht (Pflichtfeld fehlt, Datum unmöglich, schon vorhanden). |
| 401 | Kein Schlüssel, oder der Schlüssel ist ungültig, gesperrt oder abgelaufen. |
| 403 | Dem Schlüssel fehlt das Recht, oder die Feuerwehr ist nur lesbar (Live-Demo, Testphase abgelaufen). |
| 404 | Das gibt es nicht, oder der Schlüssel darf es nicht sehen. |
| 429 | Zu viele Aufrufe; kurz warten. |
9. Grenzen
Je Schlüssel sind 120 Aufrufe in der Minute möglich. Braucht ein System mehr, meldet euch bei uns. Die Schnittstelle trägt die Version in der Adresse (/v1); innerhalb einer Version kommen Felder und Adressen dazu, vorhandene ändern ihre Bedeutung nicht.
10. KI-Apps (MCP)
Über das Model Context Protocol (MCP) arbeiten Claude, ChatGPT und andere KI-Apps mit den Daten eurer Feuerwehr. Fragt in normalem Deutsch, etwa „Wer hat nächsten Monat ablaufende G26.3?“ oder „Welche Geräte müssen diese Woche zur Prüfung?“. Die Adresse ist https://eure-feuerwehr.fwmax.de/mcp oder https://api.fwmax.de/mcp (Streamable HTTP).
So bleibt es sicher: MCP ist aus, bis die Feuerwehr es unter Verwaltung › KI und MCP einschaltet. Die KI meldet sich mit einem Schlüssel an, der für KI-Apps freigegeben ist, und hat genau dessen Rechte; Werkzeuge, die etwas ändern, braucht zusätzlich die Freigabe „Ändern erlaubt“. Jeder Aufruf steht mit Werkzeug und Angaben im Protokoll. Gesundheitsdaten gibt es nur als gültig oder abgelaufen. Je Zugang sind 60 Werkzeugaufrufe in der Minute möglich, Antworten sind in der Größe begrenzt, und Browser anderer Seiten dürfen die Adresse nicht aufrufen.
Werkzeuge zum Lesen: personen_suchen, person_details, fristen_ablaufend, dienste_listen, einsatz_liste, einsatz_details, fahrzeuge_status, geraete_faellige_pruefungen, kleiderkammer_bestand, lehrgaenge, statistik_dienste, kalender_termine, objekte_suchen. Zum Ändern: dienst_anlegen, rueckmeldung_setzen, mangel_melden, nachricht_entwurf (speichert nur einen Entwurf, gesendet wird nichts).
Ausprobieren ohne Schlüssel mit der Live-Demo (nur lesen): https://demo.fwmax.de/mcp. In Claude Code:
claude mcp add --transport http fwmax-demo https://demo.fwmax.de/mcp
claude mcp add --transport http fwmax https://api.fwmax.de/mcp --header "Authorization: Bearer fwmax_..."
In Claude (claude.ai, Desktop, Mobil) unter Einstellungen › Konnektoren einen eigenen Konnektor mit der Adresse anlegen. Die Anmeldung mit dem eigenen fwMAX-Konto (OAuth) für Konnektoren ohne Schlüssel folgt; die Beschreibung der geschützten Ressource steht schon unter /.well-known/oauth-protected-resource.