Mittels dieser Schnittstelle können Sie als Drittsystemanbieter Alarmdaten, Fahrzeugstatus sowie Fahrzeugpositionen an FE2 übermitteln. Die Übertragung erfolgt über unseren RabbitMQ-HA-Cluster, daher müssen die empfangenden Systeme über keine https:// Freigabe über das Internet verfügen (im Gegensatz zur externen Schnittstelle). Dadurch ist für die Zielsysteme eine sehr komfortable Anbindung möglich. Die Übermittlung der Nutzdaten erfolgt vollständig Ende-zu-Ende verschlüsselt.

Inhalt

1 API-Schlüssel
2 Zugriffspunkte / REST Endpoints
3 Datenformat
- 3.1 Anmerkungen zum Datenformat
- 3.2 Topic, Felder und Kunden-Identifikation
  - 3.2.1 Beispiel
- 3.3 Verschlüsselung
- 3.4 Base64 Encoding
- 3.5 Austausch der Werte von Drittanbieter mit Kunde

API-Schlüssel

Für die Anbindung benötigen Sie einen API-Schlüssel.

API-Schlüssel können nur von Unternehmen, nicht von Privatpersonen angefordert werden.

Ein API-Schlüssel kann per E-Mail an kontakt (at) alamos-gmbh.com unter Angabe der folgenden Daten angefordert werden:

Name des Drittanbieters	Gewünschter, für die Erstellung genutzter Name, z.B. abcgmbh Zeichensatz [a-zA-Z0-9]
Ansprechpartner E-Mail, Telefonnummer & Firmen-Website	Für Rückfragen und spätere Kommunikation.
Beabsichtigter Einsatzzweck	Eine kurze Beschreibung, wie die Schnittstelle genutzt werden soll.
Geschätzte Nutzung pro 24 Stunden	Ungefähres Aufkommen an Meldungen (Alarme, inkl. Status und Positionen) pro Tag. Grobe Schätzung.
Nutzungsbedingungen unterschrieben

Zugriffspunkte / REST Endpoints

Die Übermittlung der Daten findet über REST-Schnittstellen statt.

Die konkreten Pfade sowie Beispieldaten können über Swagger UI eingesehen und getestet werden.

OpenAPI Dokumentation

Für den Zugriff auf Swagger UI verwenden Sie folgende Benutzerdaten:

Benutzername:

user

Passwort:

user@alamosopenapi

Datenformat

Das unverschlüsselte Datenformat der Nutzdaten finden Sie unter:

Datenformat Externe Schnittstelle

Anmerkungen zum Datenformat

Das Feld authorization im Datenformat muss nicht gefüllt werden.
Das Array units enthält eine Liste von allen Einheiten, welche alarmiert werden. address entspricht hierbei dem Code bzw. der Kennung der Einheit.
- Sie müssen sich immer mit dem Kunden austauschen, damit die richtige Einheit im System des Kunden existiert und auch alarmiert werden kann. Wenn Sie versuchen, Einheiten zu alarmieren, deren Kennung nicht im Zielsystem existiert, erhalten Sie in der Response selbst keine Fehlermeldung, sondern ausschließlich im Log des FE2-Kunden-Systems.

Im Topic dürfen nur Kleinbuchstaben, Zahlen sowie die Zeichen - und _ enthalten sein. Für das untere Beispiel wurde das Passwort 12345 zur Verschlüsselung verwendet. Final werden die verschlüsselten Daten im folgenden Format übermittelt. Auf die Verschlüsselungsverfahren wird in den darauf folgenden Punkten näher eingegangen.

{
    "iv": "gyAU1msOltlawCecaIX70Q==",
	"salt": "hmWDwA7W2ezmM58NNM41QBfh4VF3qbxWE7go7gtG2cZp4QPaQ5W2EtPtM45HS5dNjeB0BubvLMMjS/q2iPzkMQ==",
	"encryptedMessage": "16VjtTTqURB4ene5GL9OUZ16oDZ9NBVGrshLRNSkwy5JTsw7FEdY00B51Pt85rJMt9nY18ld2TaYNKbZlu8uYRSTnCfxggujChU0GSEgpnEKK6tK/ubkfQ6EcK0ZJ70e4NN1y0W0Dnu5/3iovUpQ2aQ1nc/nIZXHVFncTu7dY4X+E+eLYiEXBt5iSFavMN8D82seDWFGpsCmZ7ZTbh8HImbUzqSykQGX3U7wfoV78GxYFv89nE+GShvEWu5R9Ivkv+hZ5LSg4JIdnNPxlz6qNJAtbbGQciXeIWkwfqSUCL8GC+YNcFAjG3THxQc4V2UUOsKIzLIurovm4R2AGORKebzsM0/f99StDEfmIYIwox2x+Hpy/QWcnuXfl3Yr5iwCCt9J/j8cmCi1KlnPy8vL+MKpgdxZXuQEeFr1PWn+rzx3iabAUUqnXeVAvMeWf2GpQRq9IrtWMPN7pXGjqLHCbCf6r3gY0/LvhiB0lDwXzSVcf06cWZr4az4twBCUUHj/LYvy9YgeSzoCuqfEoVCLKoocl8ZIf2g74y6d5w3sVZSLnoAWG98z3GHIFAjzhdN0VJjL1giA4u/it1Ku3ND/ullSCvtVXn6y39A92I+k7bSftgUk6klYH5sE99aL5w3UK+gK5l0Swi8CedCDyRnUVTSZ4D8EWhrygC0AI8MUwgQ5XYx+y2SsBcDTib7VlLaEUCR0kqydUcFKvqmj1T5Et3EAzhtkb6GpsQgjzF2tU/9BfL+o97ADQaGVfeyOnx1gzNp4PvSNtYCZUnzTq3ygxMFt2PQt6z+s0KrDZFkNpgUxaQROOqhRrpr0H4BYIU4gMU1w22dd52k2FcNY5j1YGjqxrfhDzEZ6sYWAVT3P2zP2yFlXmQNLL++RhNzc9lmm9Q08dj2OZYfdtSAuCRMhzSb5A0DVKne0er5HxwyTRU1gv5p0KvwBZnRnxKmESNuBnqaDqcqiGzvKoH+qS2w7ICC3xXIjr22ew+UG3tfLjysNpPEcIQ7l8xd6Zv4deHofHRsjIp/urixkpJ8QV7/xtZ7PJStdSqPATS5iBa3cfJovtFoENvgBD4EI3+GSTzYC5+fxEaxlf5M2K0jamUwexUSAz6SxIETLAOHYftp7fKweuBL7t5yh9ruwzq6iQyPu3FLHZHWmHE9nlYB56c5gQmRmFzIZ82EZRSaBJoFlB2fMOm+XbDRB51cpZgD76V4AUBjX6MPXsrM+6Alo7+/U7vEo/+CMPbt22OyAFn846L5gWFMbcY/fhU1TqBQC7rx42uPyJgpJcAPcTRYv+lQ/icHhSXG1+hf1fJq6GAZMHfwmoiZ6wEKy9QRy4Q44khulDSTatWrzbVqu57bgGSA8cx/Y/+JvIlANaqMFnGG8KT558OqUzXN8X0HTcgZeZ2nTWEuZQgUXO3iKs/aWEdimSJQuE/vDtxRb4Cewx8nN5GBc3HbNHf7CGYIr3Z1cTCta",
    "nameOfPartner" : "partner name",
    "apiKey" : "api-key",
    "topic" : "topic_addition", 
    "messageIdentifier" : "unique message id"
}

Der Wert in "encryptedMessage" entspricht dem Datenformat der externen Schnittstelle (siehe oben) in JSON nach erfolgter Verschlüsselung und anschließendem Base64 Encoding.

Topic, Felder und Kunden-Identifikation

Das Feld topic setzt sich wie folgt zusammen:

FE2-Identifikation	Dieser Wert wird im Alarmeingang durch FE2 automatisch generiert.
Kunden-Identifikation	Dieser Wert muss der Kunden in seinem FE2-Alarmeingang hinterlegen. Diese Kunden-Identifikation wird durch den Drittanbieter definiert und muss dem Kunden übermittelt werden.
Beschreibung weiterer Felder
messageIdentifier	Ein eindeutiger Wert (UUID), mit welchem Sie später den Zustand der Übermittlung abrufen können.

Beispiel

Wenn die FE2-Identifikation abc und die Kunden-Identifikation efg lautet, so muss das Topic wie folgt gesetzt werden:

Verschlüsselung

Die Nutzdaten in JSON sollen via AES verschlüsselt und als Base64 Payload übermittelt werden. In der Tabelle können die zu verwendenden Parameter für die Verschlüsselung entnommen werden.

ALGORITHM	AES/CBC/PKCS5Padding
KEYLENGTH	256
KEYSPEC	PBKDF2withHmacSHA1
ITERATIONS	5000

Die nachfolgenden Codebeispiele sind erstellt mithilfe von javax.crypto (Java JDK 17) und kann verwendet werden, um die oben definierten Spezifikationen umzusetzen. So können beispielsweise das Kryptografie-Verfahren, sowie das Verfahren zum Generieren der Schlüssel, wie folgt implementiert werden:

Wie die Parameter iv und salt generiert werden, können dem unteren Java Beispielcode entnommen werden. Dabei wird das salt über einen für Kryptografie geeigneten Zufallsgenerator erstellt. In Java kann das mit SecureRandom wie folgt aussehen.

Exemplarisch kann die iv mit einer Länge von 16 Bytes ohne Offset definiert werden.

Schlussendlich können die Daten im Beispielcode mit den unteren Aufrufen die Cipher initialisiert und die Verschlüsselung durchgeführt werden.

Base64 Encoding

Vor der Übertragung muss die verschlüsselte Nutzlast, iv und salt Base64 encodiert werden. Das Encoding basiert auf den RFC 4648 Standard. Hier beispielhaft das Encoding der Parameter mit der Encoder-Klasse aus java.util, welches auf Line Feeds oder das sichere Alphabet für URL/Dateinamen verzichtet.

Austausch der Werte von Drittanbieter mit Kunde

Nachfolgend finden Sie eine Übersicht über Werte und Daten, welche Sie mit Ihrem Kunden gemeinsam austauschen müssen:

Datensatz	Quelle	Hinweis

Datensatz	Quelle	Hinweis
FE2-Identifikation	Kunde
Kunden-Identifikation	Drittanbieter	Nur Buchstaben, keine Sonderzeichen
Verschlüsselungspasswort	Drittanbieter	Mindestens 16 Zeichen

Handbuch

API - Drittsystemanbindung