Öffentliche Connect Schnittstelle

Allgemeines

Diese Schnittstelle ist angedacht, um anderen die Möglichkeit zu geben unsere Connect Plattform zu nutzen und um von Synergieeffekten zu profitieren.

Die Schnittstelle kann auf Organisations- und auf Standortebene aktiviert werden. Im Gegensatz zum auf Standortebene erstellten Token, können auf Organisationsebene die Entitäten aller Standorte verwaltet werden. Unter “Schnittstellen” => „Öffentliche Connect-Schnittstelle“ kann ein Zugriffs-Token erstellt werden, welches später zur Authentifizierung und Autorisierung der API-Aufrufe benötigt wird. Bitte achtet darauf, dass das Token nicht in „fremde“ Hände gerät, da jeder, der dieses Token kennt, Alarme erzeugen kann. Über die Schnittstelle habt ihr die gleichen Möglichkeiten wie der EinsatzMonitor, d. h. Connect unterscheidet nicht zwischen einem EinsatzMonitor- oder einem API-Einsatz. Es werden die gleichen Routinen im Hintergrund ausgeführt. Einsätze die älter als 120 Minuten sind, werden von der Zusatzalarmierung ausgenommen und somit nicht an die Handys und EinsatzMonitore gepusht. Da wir auf Datensicherheit sehr großen Wert legen, ist die Schnittstelle nur unter dem HTTPS-Protokoll (mindestens TLS 1.1, besser TLS1.2) erreichbar und überträgt die Daten somit auch nur verschlüsselt.

Wir behalten uns vor, den API Key für weitere Einsätze zu sperren, sollte unser System den Versuch eines (D)DOS Angriffes erkennen (Überlast des Servers erzeugen). Die maximale Anzahl an Einsätzen ist auf 5 Einsätze pro Minute und 25 Einsätze pro Stunde begrenzt. Wird eine größere Anzahl benötigt, könnt ihr uns über die gewohnten Kanäle kontaktieren.

Aktivieren der Schnittstelle

Zum Aktivieren der Öffentlichen Connect Schnittstelle wechseln Sie zum Punkt “Schnittstellen” und “Öffentliche Connect Schnittstelle”. Nach einem Klick auf Aktivieren wird ihr Authentifizierungsschlüssel angezeigt.

Achtung: Mit diesen Schlüssel haben sie vollen Zugriff auf Ihren Standort der Organisation. Behandeln Sie den Schlüssel vertraulich.

Der Authentifizierungsschlüssel kann sowohl auf Organisationsebene als auch auf Standortebene für jeden Standort separat erzeugt werden. In der Regel wird hier aber der Schlüssel des Standortes benötigt.

Allgemeines

Die Schnittstelle akzeptiert ausschließlich Daten im JSON-Format (siehe Wikipedia https://de.wikipedia.org/wiki/JavaScript_Object_Notation). 
Die vollständige Beschreibung der API ist unter Swagger zu finden. Auf dieser Seite werden lediglich einige Beispiele genauer erklärt.

Authentifizierung

Die Authentifizierung an der API Schnittstelle erfolgt mit dem im Connect Portal erstellten API Key. Dieser muss im Authorization Header des GET / POST Request als Bearer Token angegeben werden.

Headers 
Authorization: bearer {token} 
Accept: application/json 
Content-Type: application/json 

Request Limiter

Unsere Öffentliche Connect Schnittstelle verwendet einen Request Limiter welcher die Nutzung der Schnittstelle reguliert. Bitte achten Sie bei der Nutzung der Schnittstelle darauf, die Anfragen an die Schnittstelle möglichst gering zu halten. Sollten Sie zu viele Anfragen in einer bestimmten Zeit an die Schnittstelle gestellt haben, wird die Verbindung mit dem HTTP Responsecode 429 (TOO_MANY_REQUESTS) geschlossen. Hierbei sind folgende Regeln zu beachten.

Generell werden Request pro Token, IP und Endpunkt gezählt.
Es gilt ein globales Limit von 2 Requests pro Sekunde.

Das IP Limit wird immer auf eine Kombination von IP + Token angewendet. So kann man von einer IP zum Beispiel Einsätze in 20 verschiedenen Standorten anlegen (da jeder Standort einen eigenen Key hat) aber nicht 20 Einsätze im gleichen Standort. Somit laufen Zentrale Verteilsysteme wie Leitstellenintegrationen die nicht von Feuer Software gehostet werden in keine IP Sperre.

Der Endpunkt zum Erstellen von Einsätzen (/interfaces/public/operation) hat folgende (strengere) Limitierungen:
2 Request / Sekunde
10 Requests / Minute
50 Requests / Stunde

Welches der Limits überschritten wurde, steht im Response, Beispiel:
„API calls quota exceeded! maximum admitted 2 per Second.“

Ergänzend gibt es einen HTTP-Header der angibt nach wie vielen Sekunden ein Retry möglich ist, Beispiel:
Retry-After=1

Übersicht der Operatoren

Die Stamm URL der Public API lautet:

https://connectapi.feuersoftware.com/interfaces/public/

Controller Operation

https://connectapi.feuersoftware.com/interfaces/public/operation

Beispiel

POST /interfaces/public/operation

{
    "Start": "2023-09-26T08:58:52.687Z",
    "End": "2023-09-26T08:58:52.687Z",
    "Status": "new",
    "AlarmEnabled": true,
    "Keyword": "string",
    "Address": {
      "Street": "string",
      "HouseNumber": "string",
      "ZipCode": "string",
      "City": "string",
      "District": "string"
    },
    "Reporter": {
      "Name": "string",
      "PhoneNumber": "string"
    },
    "Position": {
      "Latitude": 0,
      "Longitude": 0
    },
    "Facts": "string",
    "Ric": "string",
    "Number": "string",
    "Source": "string",
    "Properties": [
      {
        "Key": "string",
        "Value": "string"
      }
    ],
    "AlarmedVehicles": [
      {
        "Id": 0,
        "RadioIdentifier": "string"
      }
    ],
    "AssignedVehicles": [
      {
        "Name": "string",
        "VehicleId": 0,
        "RadioId": "string",
        "Assigned": "2023-09-26T08:58:52.687Z",
        "Alerted": "2023-09-26T08:58:52.687Z",
        "Finished": "2023-09-26T08:58:52.687Z",
        "Status1": "2023-09-26T08:58:52.687Z",
        "Status2": "2023-09-26T08:58:52.687Z",
        "Status3": "2023-09-26T08:58:52.687Z",
        "Status4": "2023-09-26T08:58:52.687Z",
        "Status7": "2023-09-26T08:58:52.687Z",
        "Status8": "2023-09-26T08:58:52.687Z"
      }
    ]
  }

Property	Value
Start	Datum (ISO 8601), Pflicht (Einsatzzeitstempel)
End	Datum (ISO 8601)
Status	’new‘, ‚update‘, ‚cancel‘, ‚close‘
AlarmEnabled	boolean, (optional)
Keyword	String, Pflicht, max. 255 Zeichen (Stichwort)
Adress	String, optional, max. 255 Zeichen (Adresse). Sie können sowohl strukturierte Daten übergeben (Bevorzugte Variante), als auch einen String mit allen Daten übergeben.
Position	Latitude: Number, (Breitenangabe), Longitude: Number, (Längenangabe)
Facts	String, max. 255 Zeichen (Sachverhalt)
Ric	String, max. 255 Zeichen (RIC). Mehrere RICs sind möglich.
Number	String, (Einsatznummer)
Properties	Array von Objekten (Zusatzinfos)
AlarmedVehicles	Array von Objekten (Alarmierte Fahrzeuge)
AssignedVehicles	Array von Objekten (Zugeordnete Fahrzeuge)

Messages

https://connectapi.feuersoftware.com/interfaces/public/operation/{operationIdOrNumber}/message

[   
{[
  {
    "Id": 0,
    "MessageText": "string",
    "TimeStamp": "2021-05-25T13:54:52.725Z",
    "Source": "string",
    "SenderName": "string",
    "ReceiverName": "string",
    "CreatedAt": "2021-05-25T13:54:52.725Z",
    "CreatedBy": {
      "Id": "string",
      "Name": "string"
    }
  }
]

Property	Value
Id	Eindeutige ID der Meldung
MessageText	Text der Nachricht/Lagemeldung.
TimeStamp	Zeitstempel
Source	Quelle der Nachricht z.B. WDX3
SenderName	Name des Senders
ReceiverName	Name des Empfängers
CreatedAt	Uhrzeit der Erstellung der Nachricht in Connect
CreatedBy	Erstellung der Nachricht durch User

Assignment

https://connectapi.feuersoftware.com/interfaces/public/operation/{operationIdOrNumber}/message

{
  "Name": "string",
  "Vehicle": {
    "Id": 0,
    "RadioId": "string",
    "PlaceName": "string",
    "OrganizationCallSign": "string",
    "LocationIdentificationNumber": 0,
    "VehicleIdentifier": "string",
    "Subdivision": 0,
    "Description": "string",
    "Crew": 0,
    "Phone": "string",
    "Site": {
      "Id": 0,
      "Name": "string"
    },
    "CallSign": "string"
  },
  "RadioId": "string",
  "Status1": "2021-05-25T13:54:52.741Z",
  "Status2": "2021-05-25T13:54:52.741Z",
  "Status3": "2021-05-25T13:54:52.741Z",
  "Status4": "2021-05-25T13:54:52.741Z",
  "Status7": "2021-05-25T13:54:52.741Z",
  "Status8": "2021-05-25T13:54:52.741Z"
}

Property	Value
Name	Name des Fahrzeuges
Vehicle	Fahrzeugkennung/Funkrufname
RadioId	Eindeutige Funkgerätekennung (ISSI(
Status	Zeitstempel Status 1 – 8

Controller Geocoding

https://connectapi.feuersoftware.com/interfaces/public/geoconding

Controller Alarmgroup

https://connectapi.feuersoftware.com/interfaces/public/alarmgroup

{
        "Id": 12345,
        "Name": "1. Löschzug",
        "Users": [
            {
                "Id": "5896481b-8270-47e1-a365-abcde12345",
                "FirstName": "Max",
                "LastName": "Mustermann",
                "Email": "max.mustermann@gmail.de",
                "UserName": "max.mustermann@gmail.de",
                "PagerIssi": null
            }
        ],
        "Site": {
            "Id": 9439,
            "Name": "Feuerwehr Flammenhausen"
        }
    }

Property	Value
Id	Eindeutige ID der Alarmgroup, integer
Name	Name der Alarmgroup, string
Site	Array, zugeordneter Standort mit ID und Name
Id	BenutzerID, string, optional
FirstName	Vorname, string, optional
LastName	Nachname, string, optional
E-Mail	E-Mail, string, optional
Username	Benutzername, String, optional
PagerISSI	ISSI Pager, String, optional

Controller Billing

Hinweis: Funktioniert nur auf Organisationsebene. Bitte den API Key Ihrer Organisation verwenden.

https://connectapi.feuersoftware.com/interfaces/public/billing/account

Controller News

https://connectapi.feuersoftware.com/interfaces/public/news

{
        "Id": 12345,
        "Title": "Dienstplan Online",
        "Content": "Der Dienstplan für das nächste Halbjahr ist nun online!",
        "CreatedBy": "Max Mustermann",
        "Start": "2021-03-06T00:00:00+01:00",
        "End": "2021-03-20T00:00:00+01:00",
        "Groups": [],
        "MailingLists": [],
        "Site": "Feuerwehr Flammenhausen"
    }

Property	Value
Id	Eindeutige ID der News, integer, optional
Title	Titel der News, string, optional
Content	Inhalt der News, string, optional
CreatedBy	News angelegt von, string, optional
Start	Startdatum
End	Enddatum
Groups	Sichtbarkeit auf bestimmte Gruppen eingeschränkt, Array
MailingList	News zusätzlich an MailingList, Array
Site	Site in der die News veröffentlicht wurde, String

Controller User

https://connectapi.feuersoftware.com/interfaces/public/user

[
    {
        "AccountStatus": "Activated",
        "Address": {
            "Address": "Flammenstraße 9, 12345 Flammenhausen",
            "Street": "Flammenstraße",
            "HouseNumber": "9",
            "ZipCode": "12345",
            "City": "Flammenhausen",
            "District": null,
            "CityWithDistrict": "Flammenhausen",
            "CityWithDistrictAndZipCode": "12345 Flammenhausen",
            "StreetWithHouseNumber": "Flammenstraße 9",
            "Lng": 0.0,
            "Lat": 0.0
        },
        "PhoneNumber": null,
        "LandlineNumber": null,
        "BluetoothBeacons": [],
        "Sites": [
            {
                "Id": 5,
                "Name": "Feuerwehr Flammendorf Nord"
            },
            {
                "Id": 9439,
                "Name": "Feuerwehr Flammenhausen"
            }
        ],
        "Id": "5896481b-0000-0000-a365-abcde1234567",
        "FirstName": "Max",
        "LastName": "Mustermann",
        "Email": "max.mustermann@gmail.com",
        "UserName": "max.mustermann@gmail.com",
        "PagerIssi": null
    }

Property	Value
AccountStatus	String, ‚activated‘, ‚deactivated‘, ‚invited‘
Address	Array der Adresse
PhoneNumber	Telefonnummer, String, optional
LandLineNumber	Telefonnummer, String, optional
BluetoothBeacons	Bluetooth Beacon ID, String, optional
Id	UserID, String, optional
FirstName	Vorname, String, optional
LastName	Nachname, String, optional
E-Mail	E-Mail, String, optional
UserName	Benutzername, String, optional
PagerISSI	ISSI des Pagers, String, optional

Controller Vehicle

https://connectapi.feuersoftware.com/interfaces/public/vehicle

Beispiel
Get /interfaces/public/vehicle

{
        "Id": 12345,
        "RadioId": "1234567",
        "PlaceName": "Flammenhausen",
        "OrganizationCallSign": "Florian",
        "LocationIdentificationNumber": 1,
        "VehicleIdentifier": "46",
        "Subdivision": 1,
        "Description": "HLF 20",
        "Crew": 9,
        "Phone": null,
        "Site": {
            "Id": 9439,
            "Name": "Feuerwehr Flammenhausen"
        },
        "CallSign": "Florian Flammenhausen 1-46-1"
    }

Property	Value
Id	Eindeutige ID, integer, optional
RadioID	Funkgerätekennung(ISSI), string, optional
PlaceName	Standort, string
OrganizationCallSign	Organisationskennwort, string
LocationIdentificationNumber	Standortkennzahl, integer, optional
VehicleIdentifier	Fahrzeug, string
Subdivision	Unterteilung, integer, optional
Description	Beschreibung, string
Crew	Besatzung, integer
Phone	Telefonnummer, string, optional
Site	zugeordnete Standorte, optional
Call Sign	Funkrufname, string, optional, readonly

Beispiel
POST /interfaces/public/vehicle/{radioId}/status

Die Variable {radioId} gibt die Funkgerätekennung (ISSI) des entsprechenden Fahrzeuges an.

{
   "Status": 0,
   "Position": {
     "Latitude": 0,
     "Longitude": 0
   },
   "StatusTimestamp": "2021-02-07T20:55:49.723Z",
   "PositionTimestamp": "2021-02-07T20:55:49.723Z"
 }

Property	Value
Status	Number [0-9], optional (Funkstatus)
Position	Latitude: Number, (Breitenangabe), Longitude: Number, (Längenangabe)
StatusTimestamp	Datum (ISO 8601), TimeStamp
PositionTimestamp	Datum (ISO 8601), TimeStamp

Beispiel: Status Upload mit PowerShell

Ein Beispiel für ein POST Request mit Microsoft Powershell.

# Variablen 
 $bearer_token = "Hier Token einfügen"
 $Status = "Hier Status (1-9) einfügen"
 $Lat = "Hier Latitude Wert einfügen"
 $Long = "Hier Longitude Wert einfügen"
 $RadioID = "Funkgerätekennung (ISSI) hier einfügen"

 # Body
 $body = @{
     status = "$Status"
     position = @{
         Latitude  = "$Lat"
         Longitude = "$Long"
     }
 }
 $Body = ($Body | ConvertTo-Json) 

 # Header
 $Header = @{
         "authorization" = "Bearer $bearer_token"
     }
     $Parameters = @{
         Method      = "POST"
         Uri         = "https://connectapi.feuersoftware.com/interfaces/public/vehicle/$RadioID/status"
         Headers     = $Header
         ContentType = "application/json"
         Body        = $Body
     }
 # Aufruf
 Invoke-RestMethod @Parameters

Beispiel: User Verfügbarkeit als Admin setzen

Microsoft Powershell Funktion zum setzen von Verfügbarkeiten eines Users.

Function ConnectAvailability([string]$ID,[string]$Status,[string]$days)
{
#Aktuelle Zeit + X Tage
$Temp = (Get-date).AddDays($days)
$time = Get-Date $Temp -Format o

#Authentication
$bearer_token = "Connect AUTH CODE hier einfügen"

#Body
$body = @{
    status = "$Status"
    Until = "$time"
    Source = "none"
    }


$Body = ($Body | ConvertTo-Json) 

#Header
 $Header = @{
        "authorization" = "Bearer $bearer_token"
    }
    $Parameters = @{
        Method      = "PUT"
        Uri         = "https://connectapi.feuersoftware.com/interfaces/public/user/$ID/availability/current"
        Headers     = $Header
        ContentType = "application/json"
        Body        = $Body
    }

# Aufruf
Invoke-RestMethod @Parameters

}

#################################################Aufruf##################################################
# ID: Eindeutige User ID. Aus der URL im Connect Portal zu entnehmen.
# Status: available, limitedAvailable, notAvailable
# Days: Anzahl der Tage welche auf das aktuelle Datum addiert werden.
#
ConnectAvailability -ID "USER ID" -Status "notAvailable" -Days "1"

Einsatz Upload Tool

Das Tool EinsatzUpload richtet sich an alle, die nicht selbst Programmieren möchten aber dennoch von einem anderen Programm einen Einsatz in Connect erstellen möchten.

Parameter die ein Leerzeichen enthalten müssen mit " beginnen und mit " abgeschlossen werden. Zum Beispiel: "Ich bin ein Test, den ich gerne übergeben möchte"
Parameter:
-S, –Stichwort Required.
-A, –Adresse Required.
-K, –ApiKey Required.
-R, –Ric
-E, –EinsatzNummer
-F, –Sachverhalt
-a, –Lat
-n, –Lng
-U, –UpdateStrategy None/ByNumber/ByAddress/ByPosition
-s, –EinsatzStatus New/Update/Cancel/Close
–help Display this help screen.
–version Display version information.

Status Upload Tool

Hiermit kann ganz einfach ein Fahrzeugstatus zu unserer Connectplattform gesendet werden.

Einsatzupload.exe “ConnectKey” “FahrzeugKennung” “Status”
Einsatzupload.exe "f34f3hrewrwed4dc34t4vt3zurewb2b6543c52c525q345wqe5vwev5a5a3" "225643" "1"

Beiträge aus der Community

Folgende Beiträge stammen aus der Feuersoftware Community