RESTful Webservice

Die elementaren Schnittstellen sind gemäß der OpenAPI-Spezifikation dokumentiert und mit Hilfe von Swagger testbar. Die einzelnen Schnittstellen für Alarmierungen, Mitteilungen, Termine sowie die Authentifizierung und den Abgleich der Stammdaten finden Sie unter https://api.divera247.com/.

Alarmierung/Mitteilung auslösen

Neben den Schnittstellen wie dem Alarmserver zur E-Mail-Auswertung oder dem SMS-Inbound, gibt es auch die Möglichkeit eine Alarmierung über unsere Web-Schnittstelle (API) auszulösen.

Die URL für die Alarm-Schnittstelle lautet: https://www.divera247.com/api/alarm?accesskey=ALARM_ACCESSKEY

Den Access-Key finden Sie als Administrator im Menü unter Verwaltung > Einstellungen > Schnittstellen > API.


Hinweis für Nutzer der kostenlosen Version: In DIVERA 24/7 FREE wird ausschließlich das Einsatzstichwort ausgewertet und gespeichert. Ab der ALARM-Version können alle Einsatz-Daten übernommen werden. Sie kann kostenlos und unverbindlich für 30 Tage getestet werden (Verwaltung > Konto > Kontakt- & Vertragsdaten).


Folgende optionale Parameter können via GET oder POST verwendet werden:

Parameter (häufig genutzt)BedeutungDatentypBemerkung
numberEinsatznummerIntegerEigene Nummer des Einsatzes, z.B. laufende Einsatznummer der Leitstelle.
titleEinsatzstichwortStringAuf 50 Zeichen begrenzt (bei FREE 30 Zeichen). Wird in der Push Nachricht angezeigt.
priorityPriorität/SonderrechteBoolean/Integertrue oder 1, um Feld zu aktivieren
textMeldungstextStringLängerer Text mit Detailinformationen. Länge max. 1000 Zeichen
addressAdresseString

Maximal 200 Zeichen ab ALARM Version

lngBreitengradFloatKomma durch Punkt ersetzen
latLängengradFloatKomma durch Punkt ersetzen
ricAlarmierte Gruppe(n) oder Untereinheit(en) StringAlarmierungs-RIC, mehrere Werte kommasepariert angeben
vehicleAlarmierte Fahrzeug(e) StringAlarmierungs-RIC, mehrere Werte kommasepariert angeben
personAlarmierte Person(en)StringFremdschlüssel, mehrere Werte kommasepariert angeben

Parameter (sonstiges)BedeutungDatentypBemerkung
delaySekunden die seit dem Alarm vergangen sindIntegerKorrigiert die Uhr im Alarmmonitor
coordinatesAktiviert ein abweichendes KoordinatensystemStringErlaubte Werte: gk
coordinates-xX-Wert einer Koordinate im Gauß-Krüger FormatFloatNur erlaubt, wenn coordinates den Wert gk hat
coordinates-yY-Wert einer Koordinate im Gauß-Krüger FormatFloatNur erlaubt, wenn coordinates den Wert gk hat
newsMitteilung statt einer Alarmierung erstellenBoolean/Integer

true oder 1 senden, um eine normale Mitteilung mit leiser Benachrichtigung zu erzeugen.

Alternativ die URL https://www.divera247.com/api/news?accesskey=API_KEY mit selben Parametern nutzen, es entfallen jedoch Priorität, Koordinaten und Fahrzeuge.


Parameter (fortgeschritten)BedeutungDatentypBemerkung
idPrimärschlüssel einer bestehenden AlarmierungIntegerDient dem dem Aktualisieren einer bestehenden Meldung, kann über /last-alarm ausgelesen werden
cluster_idsPrimärschlüssel von UntereinheitenInteger-Array
group_idsPrimärschlüssel von GruppenInteger-Array
user_cluster_relation_idsPrimärschlüssel von BenutzernInteger-Array
vehicle_idsPrimärschlüssel von EinsatzfahrzeugenInteger-Array
alarmcode_idPrimärschlüssel einer AlarmvorlageInteger

Hinweise zur Übertragung der Adresse

 Hier klicken zum Ausklappen

Die Adresse wird zur Darstellung des Einsatzortes auf der Karte verwendet, sie kann maximal 200 Zeichen enthalten und steht erst ab der ALARM Version zur Verfügung. Wenn Sie der Schnittstelle nur die Adresse übergeben und die Koordinaten nicht im Aufruf enthalten sind, versucht die Schnittstelle diese mittels Geocoding zu ermitteln

Längen- und Breitengrad (lat, lng)

Float-Wert, z.B. 47.4210651 und 10.9766104 für die Zugspitze. Punkt statt Komma verwenden! 
Wenn Sie der Schnittstelle nur die Koordinaten übergeben und die Adresse nicht im Aufruf enthalten ist, versucht die Schnittstelle mittels Reverse Geocoding die postalische Adresse zu ermitteln.

Koordinaten im Gauß-Krüger-Format

In Süddeutschland wird in Alarmdepeschen häufig das Koordinatensystem Gauß Krüger/Deutsches Hauptdreiecksnetz (DHDN) verwendet. Zur Kompatibilität mit den verwendeten Karten-Tools (Google Maps, Esri Argis) kann die Web-API Rechts- und Hochwert automatisch in Längen- und Breitengrad (WGS84) umrechnen.

Nutzen Sie folgende Parameter:

coordinates = gk
coordinates-x = Rechtswert
coordinates-y = Hochwert

Die Gauß-Krüger-Zone wird automatisch anhand der hinterlegten Adresse der Einheit ermittelt.

Angabe von Empfängern/gezielte Alarmierung

Alarmierte Untereinheiten (ric, cluster_ids)

 Hier klicken zum Ausklappen

In der PRO-Version mit einheitsübergreifender Funktionalität, können über die zentrale Alarm-Schnittstelle mehrere Untereinheiten mit einem einzigen Aufruf der API alarmiert werden. 
Sie können den Parameter ric analog zu Gruppen und Fahrzeugen verwenden. Die Datenpflege der "Alarmierungs-RIC" erfolgt jedoch über den zentralen Administrator in den Vorgaben der Untereinheiten. Der Parameter cluster_ids erwartet ein Array mit den Primärschlüsseln der Einheit(en). Zur schnelleren Verarbeitung wird empfohlen, die IDs der Einheiten als Array zu übergeben.

Alarmierte Untereinheiten und Gruppen (ric, group_ids)

 Hier klicken zum Ausklappen

Die Gruppen, die alarmiert werden sollen. Verwenden Sie die Schreibweise aus dem Feld "Alarmierungs-RIC" oder die IDs der gewünschten Gruppen. Der Parameter ric erwartet einen String mit einer oder mehrerer RICs. Mehrere mit Komma getrennt. Der Parameter group_ids erwartet ein Array mit den Primärschlüsseln der Gruppe(n). In DIVERA 24/7 PRO können über den API-Key der zentralen Schnittstelle auch einheitsübergreifende Gruppen (z.B. alle Führungskräfte im Stadtgebiet) alarmiert werden.

Alarmierte Personen (person, user_cluster_relation_ids)

 Hier klicken zum Ausklappen
Die Benutzer, die alarmiert werden sollen. Verwenden Sie die Schreibweise aus dem Feld "Fremdschlüssel" oder die IDs der gewünschten Einsatzkräfte. Der Parameter "person" erwartet einen String mit einem oder mehreren Fremdschlüsseln. Mehrere mit Komma getrennt. Der Parameter user_cluster_relation_ids erwartet ein Array mit den Primärschlüsseln der Einsatzkräfte.

Alarmierte Fahrzeuge (vehicle, vehicle_ids)

 Hier klicken zum Ausklappen
Die Einsatzmittel, die alarmiert werden sollen. Mehrere mit Komma getrennt. Verwenden Sie die Schreibweise aus dem Feld "Alarmierungs-RIC". Der Parameter "vehicle" erwartet einen String mit einer oder mehrerer RICs. Mehrere mit Komma getrennt. Der Parameter vehicle_ids erwartet ein Array mit den Primärschlüsseln der Einsatzfahrzeuge.

Weitere wichtige Hinweise

Auswertung von Alarmvorlagen

 Hier klicken zum Ausklappen

Wenn bei Aufruf der API der Parameter "alarmcode_id" gesetzt ist und einer gültigen Alarmvorlage entspricht, wird diese automatisch angewendet.

Im Regelfall muss jedoch der überlieferte Inhalt auf eine inhaltliche Übereinstimmung untersucht werden. Dafür kann in jeder Alarmvorlage im Reiter "API-Einstellungen" definiert werden, ob und unter welchen Umständen die Vorlage über Texterkennung erkannt wird. Wahlweise gar nicht, nur bei exakter Übereinstimmung mit dem Einsatzstichwort oder wenn bestimmte Suchwörter im überlieferten Einsatzstichwort enthalten sind.

Wenn einzelne Felder, z.B. Text/Meldungen oder die alarmierten Fahrzeuge, explizit im Schnittstellen-Aufruf enthalten sind, werden dies nicht vom Alarmvorschlag überschrieben. Mit der Einstellung "Daten des API-Requests überschreiben" können die Daten aus der Vorlage jedoch auch erzwungen werden.

Die Texterkennung muss zudem in den Einstellungen Verwaltung > Einstellungen > Schnittstellen > Alarmierung > Alarmvorlage anhand des Stichworts erkennen manuell aktiviert werden.

Standardeinstellungen und gezielte Alarmierung

 Hier klicken zum Ausklappen

Die API nutzt zur Alarmierung und Benachrichtigung immer die Einstellungen gemäß Verwaltung > Einstellungen > Meldungen > Alarmierungen.

Dort ist einzustellen, über welche Kommunikationswege (App/Push-Nachricht, SMS, Sprachanruf, Pager, E-Mail) der Alarm verschickt wird.

Mittels Filter (aktuelle Fahrzeug-Einteilung und/oder aktueller persönlicher Status) wird eingeschränkt, welche Personen die Alarmierung tatsächlich erhalten.

Weitere Einstellungen sind die Intelligente Alarmierung (SMS/Anruf nur für Personen ohne App-Login) und die Rückfallebene (Überprüfung von Empfangsbestätigung oder Einsatz-Rückmeldung, bei fehlender Bestätigung erfolgt automatisch die Benachrichtigung über einen zweiten Weg, z.B. SMS).

Alarmierung/Mitteilung zusammenfassen

 Hier klicken zum Ausklappen

Häufig werden für einen einzigen Einsatz mehrere Requests ausgelöst, die regulär zu neuen Alarmierung führen.

Um das ständige Auslösen der App zu unterbinden, kann die API angewiesen werden, mehrfache Aufrufe zu einem Datensatz zusammen zu führen.

In den Einstellungen der API muss "Einsätze bei mehrfachem Aufruf der API zusammenführen" aktiviert werden. Zudem wird eingestellt, innerhalb welcher Zeit das Zusammenführen stattfindet, wie mit den Informationen aus den weiteren Requests umgangenen wird (ignorieren/überschreiben/ergänzen) und ob beim Zusammenführen die eigene Einsatznummer geprüft wird.

Alternativ ist es auch möglich, über den Parameter "id" als Primärschlüssel von DIVERA 24/7 gezielt einen bestehenden Datensatz anzusprechen und zu überschreiben.

Beschränkungen in der kostenlosen Version (FREE)

 Hier klicken zum Erweitern

Innerhalb des Zeitraums von fünf Minuten kann über die API nur eine Alarmierung ausgelöst werden. Über den API-Request lässt sich nur das Einsatz-Stichwort mit max. 30 Zeichen übertragen.

Ein Upgrade auf die Version ALARM oder PRO bietet viele Vorteile. Die API unterstützt alle Details und verzichtet auf eine zeitliche Limitierung. Über Zusatzmodule wie E-Mail-Auswertung, SMS- und FAX-Inbound können vorhandene Informationskanäle integriert werden. Zur Abbildung vordefinierter Szenarien oder einer Alarm- und Ausrückeordnung (AAO) kann die Schnittstelle außerdem auf Übereinstimmung mit bekannten Alarmvorlagen prüfen und den Einsatz automatisch mit den vordefinierten Eckdaten auslösen.

Einsatz-Rückmeldung

URL: https://www.divera247.com/api/confirm-alarm?accesskey=PERSÖNLICHER_ACCESSKEY

Folgende Parameter können via GET oder POST verwendet werden:

ParameterBedeutung
Confirmation[alarm_id]Primärschlüssel des Einsatzes
Confirmation[status_id]Primärschlüssel des Status
Confirmation[note]Freitext-Rückmeldung


Verwandte Artikel