dienstplan.org Zur Startseite

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:

  1. 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.
  2. 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.
  3. Zusatzalarmierung. Ein fremdes System fragt ab, wer gerade im Dienst ist, und alarmiert daraufhin selbst - über Melder, Messenger oder Telefonanlage.
  4. 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:

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.

POST /api/v1/inbound/<instanz>/alarm
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:

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:

  1. 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.
  2. Die Einsatznummer. Eine Angabe des Absenders, aber eine benannte: Wer „0815" schreibt, meint genau diesen Einsatz.
  3. 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.

GET /api/v1/outbound/<instanz>/duty-now

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" }
  ]
}
GET /api/v1/outbound/<instanz>/roster

Der Dienstplan eines Zeitraums - der Weg in Eure Tabellen.

Parameter from - Datum JJJJ-MM-TT, Pflicht
to - Datum JJJJ-MM-TT, Pflicht, einschließlich
format - 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.

dienstplan.org - Drittsystem-Anbindung Übersicht Für Besitzer Die einzelnen Apps Handbuch