Für Technik und Leitstelle
Drittsystem-Anbindung (API)
Wie andere Systeme Meldungen hereingeben und Daten abholen - absichtlich einfach gehalten, mit gewöhnlichen HTTP-Aufrufen und ohne eigene Bibliothek.
Die Schnittstelle ist bewusst einfach und wird ständig erweitert. Sie deckt heute die Fälle ab, nach denen am häufigsten gefragt wurde - nicht mehr. Wenn Euch etwas fehlt: fragt danach. Das ist der Weg, auf dem alles hier Beschriebene entstanden ist.
Wofür das gut ist
Vier Fälle. Die ersten drei laufen über die Schnittstelle, der vierte ganz ohne sie:
- Alarmeingang. Die Leitstelle meldet einen Einsatz. Das Einsatzprotokoll legt daraus selbsttätig einen Datensatz an - mit der Alarmzeit und allem, was mitgeschickt wurde. Wer danach das Protokoll öffnet, findet den Einsatz schon vor und muss ihn nur noch vervollständigen.
- Export in Office-Anwendungen. Der Dienstplan eines Zeitraums als CSV-Datei, die Excel und LibreOffice ohne Zutun richtig lesen. Für Abrechnungen, Statistiken und alles, wofür es bei Euch schon eine Tabelle gibt.
- Zusatzalarmierung. Ein fremdes System fragt ab, wer gerade im Dienst ist, und alarmiert daraufhin selbst - über Melder, Messenger oder Telefonanlage.
- Meldungen und Bilder per E-Mail. Für alles, was keine Schnittstelle bedienen kann - und für den Menschen, der vom Einsatz ein PDF Protokoll oder Foto schickt. Jede App kann dafür eine eigene Postfachadresse bekommen.
Was Ihr zuerst braucht: ein Token
Ein Token ist der Schlüssel zur Schnittstelle. Es wird unter Organisation › API angelegt und dort auch wieder gelöscht. Zwei Dinge gehören zu jedem Token:
- Die Apps, die es erreichen darf. Ein Token für die Leitstelle kommt an Euer Einsatzprotokoll heran und an nichts sonst. Was eine App an Schnittstellen mitbringt, kann das Token nutzen - mehr braucht es nicht einzustellen.
- Personenbezogene Daten ja oder nein. Ohne diesen Haken enthalten Abfragen weder Namen noch Anmeldenamen, E-Mail-Adressen oder Telefonnummern - auch dann nicht, wenn sonst alles stimmt. Initialen und taktische Kennung gehen weiterhin heraus; sie benennen eine Rolle, keine Person.
Im Free-Paket nicht enthalten
Im Free-Paket lassen sich keine neuen Token anlegen. Bereits vergebene Token arbeiten weiter und lassen sich jederzeit löschen.
Das Token wird nur einmal angezeigt
Nach dem Anlegen erscheint es ein einziges Mal. Es gibt keinen Weg, es später noch einmal abzurufen - auch nicht für uns. Tragt es sofort im Fremdsystem ein. Ist es verloren, legt Ihr ein neues an und löscht das alte.
Wie das Token übergeben wird
Im Regelfall als Kopfzeile X-Api-Token. Das ist der
sichere Weg und die Vorgabe:
X-Api-Token: dpo_AbCdEf...
Manche Programme können keine eigene Kopfzeile mitschicken - eine Webabfrage in Excel zum Beispiel, oder ein Lesezeichen im Browser. Für diesen Fall lässt sich je Token der Weg über die Adresse freischalten:
https://<eure-adresse>/api/v1/outbound/<instanz>/duty-now?token=dpo_AbCdEf...
Unsicherer - bitte nur wenn es nicht anders geht
Steht das Token in der Adresse, landet es im Zugriffsprotokoll des Servers, in jedem Proxy dazwischen und im Verlauf des Browsers. Wer eines dieser Protokolle lesen kann, hat Euer Token. Anders als ein abgefangenes Passwort fällt das niemandem auf.
Deshalb ist der Weg abgeschaltet, bis Ihr ihn beim jeweiligen Token ausdrücklich erlaubt. Benutzt ihn nur für Abfragen (GET), nie für den Alarmeingang, und vergebt dafür ein eigenes Token, das Ihr im Verdachtsfall löschen könnt, ohne alles andere mitzureißen.
Alarmeingang
Die Leitstelle - oder ein Alarmserver dazwischen - schickt die Einsatzmeldung als JSON. Daraus entsteht ein Einsatzprotokoll-Eintrag.
| Kopfzeilen |
X-Api-Token (Pflicht),
Content-Type: application/json
|
|---|---|
| Pfadteil <instanz> |
Kurzname der App. Hängt nur eine einzige App am
Token, genügt /api/v1/inbound/<instanz> ohne
weiteren Zusatz.
|
| Körper |
Beliebiges JSON-Objekt. Erkannt wird die Alarmzeit aus
alarm_at, alarmzeit,
alarm, timestamp oder
zeit. Alles Übrige wird als Tabelle
„Schlüssel: Wert“ in das Protokollfeld geschrieben - es geht
also nichts verloren, auch wenn wir das Feld nicht kennen.
|
| Antwort |
202 angenommen ·
200 mit duplicate bei einer
Wiederholung · 400 leer oder unlesbar ·
413 zu groß · 429 zu viele ·
409 App gesperrt
|
Beispielaufruf:
curl -X POST \
-H "X-Api-Token: dpo_AbCdEf..." \
-H "Content-Type: application/json" \
-d '{"alarm_at":"2026-10-23T19:04:00+02:00",
"stichwort":"H1 - Türöffnung",
"ort":"Musterstadt, Hauptstraße 7",
"einsatzmittel":["FL Musterstadt 11/1"]}' \
https://<eure-adresse>/api/v1/inbound/einsatzprotokoll/alarm
Fehlt die Alarmzeit?
Dann gilt der Zeitpunkt, zu dem die Meldung hier ankam, und im Protokoll steht ein Vermerk darüber. Ein Einsatz ohne Zeit wäre schlimmer als einer mit einer Zeit, die um Sekunden danebenliegt.
Nachalarm: gleiche Meldung, kein zweiter Einsatz
Leitstellen schicken dieselbe Meldung oft mehrfach - als Nachalarm, als Wiederholung nach ausgebliebener Bestätigung, oder weil die erste Antwort in eine Zeitüberschreitung lief. Fachlich ist das ein Einsatz.
Kommt eine inhaltsgleiche Meldung innerhalb von 15 Minuten erneut an, wird kein zweiter Datensatz angelegt. Die Antwort lautet dann:
HTTP 200
{ "ok": true, "duplicate": true, "record_id": 4711 }
Die mitgelieferte Nummer ist der bereits vorhandene Eintrag - Ihr könnt also nachsehen, statt weiter zu wiederholen. Verglichen wird der Inhalt, nicht die Schreibweise: Eine andere Reihenfolge der Felder oder ein anderes Einrücken ändert nichts. Flüchtige Angaben wie eine Meldungsnummer oder ein Sendezeitpunkt bleiben beim Vergleich außen vor, die Alarmzeit dagegen nicht - zwei echte Einsätze an derselben Adresse unterscheiden sich oft nur in ihr.
Per E-Mail statt per Schnittstelle
Nicht jedes System, das etwas zu melden hat, kann eine Schnittstelle bedienen - und ein Mensch, der vom Einsatz ein Bild schickt, schon gar nicht. Dafür gibt es die Postfachadresse: eine E-Mail-Adresse, die zu einer Eurer Apps gehört.
Angelegt wird sie in Organisation → API → Postfachadressen. Sie sieht so aus:
musterwehr-a7k2m9x4pq@dipla.org
Der hintere Teil ist zufällig und lässt sich nicht aussuchen. Das ist Absicht: Eine Adresse, die man erraten kann, ist eine Adresse, über die jeder Einträge anlegen kann. Für den Alltag gilt - einmal ins Adressbuch, fertig.
Was an diese Adresse geschrieben wird, legt im Einsatzprotokoll einen Eintrag an. Bilder und PDF im Anhang kommen mit und werden verschlüsselt abgelegt; alles andere wird verworfen.
Wer an die Postfachadresse schreiben darf
Nicht jeder. Die Adresse ist schwer zu erraten, aber das allein wäre kein Schutz - wer sie einmal gesehen hat, kennt sie. Angenommen wird eine Nachricht nur von zwei Gruppen:
- Euren eigenen Leuten. Wer sich mit seiner hinterlegten E-Mail-Adresse meldet und die betreffende App beschreiben darf, darf das auch per Mail. Es ist dasselbe Recht wie in der Oberfläche - der Mailweg ist keine Abkürzung an der Rechtevergabe vorbei.
- Eingetragenen Fremdsystemen. Eine Leitstelle hat bei Euch kein Konto und soll keines bekommen. Tragt ihre Absenderadresse unter Organisation › API › Postfachadressen ein.
Alles andere wird abgewiesen. Wenn eine Mail „nicht ankommt", ist das in aller Regel der Grund - die Adresse des Absenders steht auf keiner der beiden Listen.
Die Absenderadresse ist ein Merkmal, kein Beweis
Wer absendet, steht in der Mail - und was in einer Mail steht, hat der Absender geschrieben. Für den Alltag genügt das vollauf: Es muss jemand eine zugelassene Adresse kennen, und was darüber hereinkommt, steht im Protokollbuch unter genau dieser Adresse. Wo es auf Unverwechselbarkeit ankommt, nehmt die Schnittstelle mit Token - dort ist der Schlüssel der Nachweis, nicht der Briefkopf.
Wie eine Mail ihrem Einsatz zugeordnet wird
Infrage kommen nur Protokolle aus den letzten 24 Stunden. Darin wird in dieser Reihenfolge gesucht - vom Sichersten zum Unschärfsten:
- Das Vorgangskennzeichen. Zwölf Zeichen, die am Ende der Eingangsbestätigung stehen. Wer antwortet, schickt sie im Zitat zurück um die Mail eindeutig zuzuordnen.
- Die Einsatznummer. Eine Angabe des Absenders, aber eine benannte: Wer „0815" schreibt, meint genau diesen Einsatz.
- Die Alarmzeit. Mit unschärfe (+/- 5 Minuten) erkennt das System den richtigen Einsatz.
Eines davon genügt. Erkannt werden unter anderem:
#1234 13:00
# 1234 13:00 Uhr
Nummer: 1234 / Alarm: 13:21
Nummer 1234 / Alarm 1321
Einsatz-Nr. 42, Alarmierung 23.59
Ist der Posteingang nicht zuzuordnen, entsteht ein neues Protokoll mit dem, was in der Mail stand - als "von außen gekommen" gekennzeichnet.
Ein unterschriebenes Protokoll nimmt nichts mehr auf. Wer etwas nachreichen muss, nimmt die Unterschrift zurück.
Die Eingangsbestätigung
Wer als Benutzer erkannt wurde, bekommt eine Antwort: was angekommen ist, an welchem Einsatz es hängt und wie viele Anhänge abgelegt wurden. Sie sieht im Kern so aus:
Einsatznummer: 2026-0815
Alarmzeit: 13:21
Einsatzführung: M. Mustermann
Dateianhänge: 3
-----------------
[Vorgang: k7mq3xp9rtva]
Diese Auflistung dient als Vordruck. Antwortet einfach darauf
um z.B. Einsatznummer: oder Alarmzeit: zu ergänzen.
Das [Vorgang: …] am Ende ist das Kennzeichen von Rang 1.
Es muss in der Antwort-Email unverändert bleiben.
Keine Bestätigung für Fremdsysteme
Eine Leitstelle, die über die Zulassungsliste einliefert, bekommt keine Antwort. Es wird immer ein neuer Einsatz angelegt (Alarmeingang).
Dienstplan abholen
Zwei Abfragen, die sich in der Praxis bewährt haben.
Wer genau jetzt im Dienst ist. Gedacht für Zusatzalarmierung und für Anzeigetafeln.
| Parameter |
format - json (Vorgabe),
csv oder text
|
|---|---|
| Felder |
Benutzer-Nr., Name*, Vorname*, Anmeldename*, taktische Kennung,
E-Mail*, Telefon*, Farbe, Initialen, Dienst seit, Dienst bis
* nur mit der Erlaubnis „personenbezogene Daten“ am Token |
| Antwort |
200 · 403 Zugriff gesperrt ·
404 unbekannte Instanz oder Abfrage
|
curl -H "X-Api-Token: dpo_AbCdEf..." \
https://<eure-adresse>/api/v1/outbound/dienstplan/duty-now
{
"dataset": "duty-now",
"generated_at": "2026-10-23T19:12:44+02:00",
"count": 2,
"rows": [
{ "user_id": 17, "last_name": "Musterfrau", "first_name": "Anna",
"tactical_id": "11/1", "initials": "AM",
"on_duty_from": "2026-10-23T18:00:00+02:00",
"on_duty_until": "2026-10-24T06:00:00+02:00" }
]
}
Der Dienstplan eines Zeitraums - der Weg in Eure Tabellen.
| Parameter |
from - Datum JJJJ-MM-TT, Pflichtto - Datum JJJJ-MM-TT, Pflicht,
einschließlichformat - csv (Vorgabe),
json oder text
|
|---|---|
| Felder | Dienstplan, Position, Beginn, Ende, Name, Initialen, Benutzer-Nr., Stand |
| Antwort |
200 · 400 fehlender oder unlesbarer
Parameter · 413 Zeitraum zu groß
|
curl -H "X-Api-Token: dpo_AbCdEf..." \
-o dienstplan.csv \
"https://<eure-adresse>/api/v1/outbound/dienstplan/roster?from=2026-11-01&to=2026-11-30"
Warum die CSV-Datei in Excel einfach aufgeht
Semikolon als Trennzeichen, UTF-8 mit Byte-Order-Mark und Zeiten im
Format TT.MM.JJJJ HH:MM. Das ist genau das, was Excel
in deutscher Spracheinstellung ohne Importassistent erwartet. Das
international übliche Format mit Komma und ISO-Datum müsstet Ihr
bei jedem Öffnen von Hand einstellen.
Grenzen
Sie stehen nicht da, um Euch zu bremsen, sondern weil ein fremdes System, das in eine Wiederholschleife gerät, sonst in einer Nacht tausende Einsatzprotokolle anlegt - und die bleiben zehn Jahre.
| Größe einer Sendung | 64 KB, darüber 413 |
|---|---|
| Sendungen je Token | 120 je Stunde |
| Alarmeingänge je Tag | 200 je App |
| Größe einer E-Mail | 5 MB mit allem, was daran hängt. Größere Nachrichten werden angenommen und verworfen - sonst blieben sie für immer im Postfach liegen und wären bei jedem Abruf erneut im Weg. |
| E-Mails je Postfach | 60 je Stunde |
| Anhänge je Protokoll | 20, jeder höchstens 5 MB |
| Fehlversuche | 60 je fünf Minuten und Anschluss |
| Zeilen je Abfrage |
je nach Abfrage; wird sie überschritten, kommt 413
statt einer gekürzten Liste
|
Bei 429: Retry-After abwarten
Jede Absage wegen zu vieler Aufrufe trägt die Kopfzeile
Retry-After mit der Zahl der Sekunden. Wartet sie ab.
Enger zu wiederholen hilft nicht - es verlängert die Sperre nur und
ist meist das eigentliche Problem.
Eine gekürzte Liste gibt es nie. Wenn das Ergebnis zu groß ist, sagen wir das - ein unvollständiger Dienstplan, der vollständig aussieht, wäre der teurere Fehler.
Was die Schnittstelle nicht herausgibt
Abfragen entschlüsseln nicht. Was verschlüsselt gespeichert ist - der Text eines Einsatzprotokolls zum Beispiel - kommt hier nicht heraus. Das ist keine Lücke, die wir noch schließen: Der Server besitzt den Schlüssel nicht und kann ihn nicht bekommen. Er liegt allein bei Euch. Mehr dazu unter Für Besitzer.
Und es geht nur heraus, was ausdrücklich vorgesehen ist. Jede Abfrage hat eine feste Feldliste; was dort nicht steht, verlässt das Haus nicht - auch nicht versehentlich.
Wenn etwas nicht geht
401 |
Token fehlt, ist falsch oder wurde über die Adresse übergeben, ohne dass das erlaubt ist. Die Meldung sagt, welcher Fall vorliegt. |
|---|---|
403 |
Der Zugriff ist gesperrt - etwa, weil die App wegen der Paketgrenzen zu ist. |
404 |
Instanz oder Abfrage gibt es nicht - oder das Token darf nicht an sie heran. Beides sieht absichtlich gleich aus. |
409 |
Die App ist gesperrt, oder der Organisation fehlt noch ein Schlüsselpaar. Ein Zustand, kein Fehler: später erneut versuchen. |
202 mit discarded |
Angekommen, aber für diese App ist kein Eingang mit diesem Namen eingerichtet. Die Meldung wurde verworfen und nur vermerkt. |
503 |
Vorübergehend nicht verfügbar. Später erneut versuchen. |
Jeder Zugriff wird protokolliert - mit Zeitpunkt, Token und Umfang, aber ohne Inhalte. Nachzulesen unter Organisation › Protokoll. Was die einzelnen Apps können, steht bei der jeweiligen App; alles Übrige im Handbuch.