Dieselbe Auswertung als On-Prem-Container in Ihrem Netzwerk
Die API ist derselbe Auswertungskern wie im Desktop-Programm, verpackt als Container-Image, das Sie On-Prem betreiben, also auf einem eigenen Server oder in Ihrem Cluster. Ihre Systeme schicken die Kartendateien per HTTP an den Container und bekommen die Auswertung als JSON zurück. Der Container hält die Kartendateien nur im Arbeitsspeicher. Er speichert sie nicht auf der Festplatte und schreibt sie in keine Logdatei. Kartendateien und Ergebnisse schickt er nicht an uns. Damit wir zählen können, wie viele Fahrer Sie mit Ihrer Lizenz auswerten, verbindet er sich mit unserem Lizenzserver unter license.scernetta.com, und zwar nach dem Start, etwa alle 6 Stunden und bei einem neuen Fahrer. Der Lizenzserver bekommt dabei den Text Ihrer Lizenzdatei mit Ihrem Firmennamen, die Versionsnummer des Containers, einige technische Prüfwerte und für jeden neuen Fahrer einen Fahrercode. Den Fahrercode berechnet der Container auf Ihrem Server aus der Fahrerkarte und Ihrem geheimen Schlüssel.
Für wen das gedacht ist
Gedacht ist das für Flotten mit eigenem TMS oder ERP, die die Auswertung dort weiterverarbeiten wollen. Telematikanbieter, die Kartendaten ohnehin schon einsammeln, können sie damit direkt prüfen lassen, und Dienstleister, die Fahrerkarten für viele Kunden auswerten, sparen sich den Umweg über ein Desktop-Programm.
Wie das abläuft
Sie bekommen von uns eine Lizenzdatei. Vor dem ersten Start erzeugen Sie einmal mit einem Befehl aus dem Container-Image einen geheimen Schlüssel, aus dem der Container die Fahrercodes berechnet. Verwenden Sie diesen Schlüssel auf allen Installationen und bewahren Sie eine Kopie auf. Der Container läuft auf einem Server in Ihrem Netzwerk und braucht dort einen eigenen Ordner, in dem er festhält, welche Fahrer schon einen Fahrerplatz haben. Der Server muss license.scernetta.com erreichen können, direkt oder über Ihren HTTP-Proxy. Ihre Systeme melden sich mit einem API-Schlüssel an und übergeben die .ddd-Dateien per HTTP, einzeln oder gebündelt pro Fahrer, und der Container führt sie genauso zusammen, wie es das Desktop-Programm tut. Zurück kommt ein JSON mit den Schichten, den Verstößen in der gewählten Sicht, den Prognosen und den nicht bewertbaren Zeiträumen, das Sie direkt weiterverarbeiten können.
Für eine ganze Flotte auf einmal gibt es einen Batch-Endpunkt. Sie laden alle Dateien in einer Anfrage hoch, der Container ordnet sie selbst den Fahrern zu und rechnet im Hintergrund. Für jeden neuen Fahrer in der Anfrage belegt der Container schon beim Einreichen einen Fahrerplatz. Reichen die freien Fahrerplätze nicht für alle neuen Fahrer, lehnt er die ganze Anfrage ab und belegt keinen Platz. Den Fortschritt und die Ergebnisse je Fahrer fragen Sie über eine Job-ID ab.
Gleicher Kern
Desktop-Programm und API rechnen mit demselben Code. Für dieselbe Datei und dieselbe Sicht liefert die API dieselben Ergebnisse wie das Programm, als Daten.
Zwei Sichten
Jede Antwort enthält eine der beiden Verstoßlisten. Voreingestellt ist die strenge Sicht, die jeden Befund aus dem Verordnungstext ableitet und den Artikel dazu nennt. Nach EU-Recht können Sie stattdessen die Referenz-Sicht abfragen, die am Ergebnis etablierter Software kalibriert ist. Nach den Schweizer Regeln ARV 1 und ARV 2 gibt es nur die strenge Sicht. Ein eigener Endpunkt liefert den Katalog der Regeln mit ihren Fundstellen.
Berichte
Der Bericht aus dem Desktop-Programm kommt auch über die API, als HTML oder als CSV-Tabellen im Zip. Dazu ein Quellenmanifest, das festhält, welche hochgeladene Datei welchen Tag belegt.
Echtheit
Signaturen und Zertifikate einer Fahrerkarte oder eines Fahrzeugeinheiten-Downloads lassen sich über die API prüfen. Die Antwort sagt, was verifiziert wurde. Signaturen der ersten Kartengeneration prüft diese Version noch nicht, das ist kein Hinweis auf eine Manipulation.
Fahrzeugeinheit
Auch die Download-Datei des Fahrzeugs lässt sich einlesen. Sie sehen, welche Karten in einem Zeitraum gesteckt haben und welche Fahrer damit gefahren sind.
Generationen
Gelesen werden Fahrerkarten der Generation 1 sowie der Generation 2 einschließlich Version 2. Dateien von Fahrzeugeinheiten liest die API nur in den Formaten der Generation 2.
OpenAPI
Die Schnittstelle ist als OpenAPI-3.1-Spezifikation beschrieben, die der Container selbst ausliefert. Die Dokumentation unter docs.scernetta.com wird daraus erzeugt.
Wie Fahrer gezählt werden
Jede Fahrerkarte, die Sie während der Laufzeit Ihrer Lizenz auswerten, zählt einmal als Fahrer, egal wie oft Sie sie auswerten. Bekommt ein Fahrer eine erneuerte Karte oder eine Ersatzkarte, bleibt er derselbe Fahrer. Bekommt er eine Karte aus einem anderen Land, zählt er als neuer Fahrer. Seinen Fahrerplatz behält ein Fahrer bis zum Ende der Laufzeit, auch wenn er Ihr Unternehmen vorher verlässt. Gezählt wird über alle Ihre Installationen zusammen, auch eine Testinstallation. Keinen Fahrerplatz belegen die Beispielkarte von unserer Website, die Echtheitsprüfung und Dateien aus Fahrzeugeinheiten.
Lizenz
Die API wird nach der Zahl der Fahrer lizenziert und jährlich abgerechnet. Ob die Lizenzdatei echt ist, prüft der Container selbst an ihrer digitalen Signatur, dafür braucht er keine Verbindung zu uns. Wird ein Fahrer in der Laufzeit zum ersten Mal ausgewertet, fragt der Container bei unserem Lizenzserver einen Fahrerplatz für ihn an. Läuft eine bezahlte Lizenz ab, rechnet der Container noch 14 Tage weiter, damit die Auswertung nicht stehen bleibt, wenn die Verlängerung ein paar Tage später kommt. Den Preis nennen wir auf Anfrage, weil er von der Größe der Flotte abhängt.
Ohne Verbindung zum Lizenzserver
Fahrer, die schon einen Fahrerplatz haben, wertet der Container auch ohne Verbindung zu unserem Lizenzserver weiter aus, 30 Tage lang ab der letzten Verbindung, mit einer Testlizenz 14 Tage. Für neue Fahrer hat eine bezahlte Lizenz eine Reserve, falls unser Lizenzserver länger als eine Minute nicht erreichbar ist. Die Reserve ist ein Zehntel der Fahrerplätze, mindestens aber 2 Plätze je Laufzeit, bei 30 Plätzen also 3. Dafür braucht der Container seinen Ordner auf dem Server. Diese Fahrer meldet er nach, sobald der Lizenzserver wieder erreichbar ist. Eine Testlizenz hat keine Reserve.
Was den Server verlässt
Die Kartendateien werden On-Prem verarbeitet, also in Ihrem Netzwerk, und nie an uns übertragen. Den Fahrercode berechnet der Container auf Ihrem Server aus der Fahrerkarte und Ihrem geheimen Schlüssel, den wir nie bekommen. Wir können aus dem Code nicht ablesen, wer der Fahrer ist. Mit Ihrem Schlüssel lässt sich der Code aber wieder einem Fahrer zuordnen, deshalb gehört er nach der DSGVO zu den personenbezogenen Daten. Die letzten 20 Nachrichten, die der Container seit seinem Start an unseren Lizenzserver geschickt hat, können Sie beim Container abrufen und lesen, so wie sie vor der Verschlüsselung aussahen.
Die Dokumentation der Schnittstelle liegt unter docs.scernetta.com und wird aus der OpenAPI-Datei erzeugt. Sie beginnt mit einem Leitfaden zu Start, Lizenz und Fehlerbehandlung und beschreibt jeden Endpunkt mit seinen Parametern.Zur Dokumentation
Wenn Sie die API einsetzen wollen, schreiben Sie uns, welche Systeme Sie anbinden möchten und um wie viele Fahrer oder Fahrzeuge es geht. Wir melden uns dann mit einem Zugang.