fwMAX.de
Für Entwickler

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.

BereichAdressen
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

AdresseZweckNötiges Recht
GET /v1Wer bin ich: Feuerwehr, Version, Name des Schlüssels und seine Rechtekeines
GET /v1/openapi.jsonMaschinenlesbare Beschreibung (OpenAPI 3.1), ohne Schlüssel abrufbarkeines
GET /v1/organisationseinheitenAlle Einheiten in Baumreihenfolge; ?aufgeloeste=true zeigt auch aufgelöstekeines
GET /v1/organisationseinheiten/{id}Eine Einheitkeines
POST /v1/organisationseinheitenEinheit anlegenOrganisation bearbeiten
PUT /v1/organisationseinheiten/{id}Einheit ändernOrganisation bearbeiten
GET /v1/personenPersonalliste; Filter suche, einheit, ehemalige, jugendPersonal ansehen
GET /v1/personen/{id}Vollständige PersonalaktePersonal ansehen
POST /v1/personenPerson anlegenPersonal bearbeiten
PUT /v1/personen/{id}Stammdaten ändernPersonal bearbeiten
POST /v1/personen/{id}/mitgliedschaftenMitgliedschaft eintragenPersonal bearbeiten
POST /v1/personen/{id}/nachweiseNachweis eintragen (Lehrgang, Untersuchung, Unterweisung, Führerschein, Abzeichen, Ehrung)Personal bearbeiten
POST /v1/personen/{id}/kontaktpersonenKontaktperson eintragenPersonal bearbeiten
GET /v1/fristenAbgelaufene und bald ablaufende Nachweise; ?tage=90Personal ansehen
GET /v1/kataloge/dienstgradeKatalog der Dienstgradekeines
GET /v1/kataloge/funktionenKatalog der Funktionenkeines
GET /v1/kataloge/nachweisartenKatalog der Nachweisartenkeines
GET /v1/kataloge/mitgliedschaftsartenKatalog der Mitgliedschaftsartenkeines
GET /v1/kataloge/organisationsartenKatalog der Arten von Einheitenkeines

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“." }
StatusBedeutung
400Die Eingabe stimmt nicht (Pflichtfeld fehlt, Datum unmöglich, schon vorhanden).
401Kein Schlüssel, oder der Schlüssel ist ungültig, gesperrt oder abgelaufen.
403Dem Schlüssel fehlt das Recht, oder die Feuerwehr ist nur lesbar (Live-Demo, Testphase abgelaufen).
404Das gibt es nicht, oder der Schlüssel darf es nicht sehen.
429Zu 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.