Ö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.

Die API Dokumentation ist auf Swagger:
https://connectapi.feuersoftware.com/swagger/ui/index

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"
      }
    ]
  }

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"
    }
  }
]

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"
}

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"
        }
    }

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"
    }

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
    }

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"
    }

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"
 }

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

Python Libary von @clfromhell


Python Libary von @Bouni


C# Bibliothek von @MrzJkl