InnerWeb
Zum Inhalt springen

KD-Integration und Arbeitsschutz: FAQ für Integratoren

Integratoren eines Zutrittskontrollsystems stellen vor dem ersten Webhook-Aufruf immer dieselben Fragen: Wie erfolgt die Authentifizierung, welche Felder sind Pflicht und was passiert bei einer unbekannten Karte. Wir haben die Antworten in der Reihenfolge zusammengestellt, in der sie beim Start auftauchen. InnerWeb tauscht keine Leser aus, daher beschränkt sich die Arbeit auf der KD-Seite auf einen HTTP-POST-Aufruf je Kartenbuchung.

JWT
authentifizierter Webhook, Token wird automatisch erneuert
Quelle: interne Karte
Echtzeit
Versand der Ereignisse aus dem KD laufend
Quelle: interne Karte
2 000+
Buchungen an einem Werktag in Betrieben mit mehreren Agenturen
Quelle: interne Karte

Was der Kartenbuchungs-Webhook ist und wer ihn aufruft

Der Kartenbuchungs-Webhook ist der Integrationspunkt zwischen dem bestehenden KD-System und InnerWeb. Das KD-System sendet bei jeder Kartenbuchung am Leser einen HTTP-POST-Aufruf an InnerWeb. Es müssen keine neuen Leser installiert, keine Leitungen verändert und keine Karten getauscht werden: InnerWeb ist Softwarehersteller und bindet das KD ein, das der Betrieb bereits besitzt.

Aufrufer ist immer das KD-System, nicht InnerWeb. Der Anbieter oder Administrator des KD konfiguriert die Regel, die das Ereignis nach der Buchung versendet. Auf der Seite von InnerWeb wird die Buchung der Person zugeordnet, gegen die Schulung geprüft und im Kontoverlauf gespeichert. So wird die Kartennummer aus dem KD zum Schlüssel für gültige Arbeitsschutzschulungen, Qualifikationen und Erlaubnisse.

Wie der Aufruf authentifiziert wird und wie lange der Token gilt

Der Webhook-Aufruf benötigt ein JWT-Token. Der Integrator holt es vom Anmeldeendpunkt der API und fügt es jeder Anfrage mit einer Buchung hinzu. Das Token hat eine begrenzte Gültigkeitsdauer und wird durch die Integration automatisch erneuert. Der Integrator sollte in seiner Spezifikation festhalten, wie die Sitzung erneuert wird, denn davon hängt die Kontinuität der Buchungsübermittlung ab.

Ein bewährtes Muster: ein technisches Konto, das nur für die Integration dient, Anmeldung beim Start des Dienstes, automatische Erneuerung des Tokens mit Reserve vor Ablauf und erneute Anmeldung nach einer Antwort mit abgelehnter Autorisierung. Passwörter und Token dürfen nicht in die Protokolle des Dienstes auf Seiten des KD gelangen.

Was passiert, wenn der Token während einer Änderung abläuft

Buchungen aus einer Zeit, in der der Token ungültig war, dürfen nicht verloren gehen. Bewährt hat sich eine Warteschlange auf Seiten des KD: Ein fehlgeschlagener Aufruf landet in einem Puffer, der Dienst meldet sich erneut an und sendet die Ereignisse nacheinander nach. Die Warteschlange ist nur sinnvoll, wenn die Ereignisse nahezu in Echtzeit versendet werden, wie weiter unten beschrieben.

Felder einer Kartenbuchungsmeldung

Felder einer KartenbuchungsmeldungBalkendiagramm: 2 Pflichtfelder und 5 optionale Felder in der Kartenbuchungsmeldung012345Anzahl FelderPflicht (Vorname, Nachname,Firma)Pflicht (Vorname, Nachname, Firma): 2 Anzahl Felder2Optional (Kürzel, Karte,Telefon, E-Mail, Sprache)Optional (Kürzel, Karte, Telefon, E-Mail, Sprache): 5 Anzahl Felder5
Quelle: Interne Karte: Kartenbuchungs-Webhook

Welche Felder in einer Buchungsmeldung Pflicht sind

Die Meldung enthält Ereigniszeit, Ort der Buchung und Personendaten. Pflicht sind Vorname und Nachname sowie der Firmenname. Optional übergeben werden Kürzel, die Nummer der aktiven Karte, Telefon, E-Mail und Sprache. Je vollständiger der Satz, desto einfacher die Zuordnung zu einem bestehenden Konto und desto besser die Benachrichtigungen in der Sprache der Person.

Die Nummer der aktiven Karte ist die Kennung, über die InnerWeb die Buchung dem Konto der Person zuordnet. Eine Fremdfirma wird anhand des Firmennamens aus der Meldung zugeordnet. Taucht dieselbe Agentur im KD einmal mit vollem Namen und einmal mit Kürzel auf, entstehen Abweichungen. Der Integrator sollte Firmennamen deshalb einheitlich schreiben.

  • Pflicht: Vorname und Nachname der Person sowie der Firmenname.
  • Empfohlen: Nummer der aktiven Karte als Zuordnungsschlüssel zum Konto.
  • Optional: Kürzel, Telefon, E-Mail, Sprache.
  • Immer: Ereigniszeit und Ort der Buchung.

Was geschieht bei einer unbekannten Karte oder Person

Eine Buchung durch eine dem System unbekannte Person legt ein Konto und eine Firma aus den Daten der Meldung an. Das ist bei hoher Fluktuation in Agenturen praktisch, verlangt aber Disziplin bei den Daten: Ein Fehler in Schreibweise von Nachname oder Firma erzeugt ein Duplikat. Die Frage nach der unbekannten Karte lautet deshalb in der Praxis: Wer ist im KD für die Qualität der Quelldaten verantwortlich?

Hat dieselbe Person zwei aktive Konten, überträgt das System das Schulungsergebnis auf das Konto mit der Eingangskarte, damit das Tor keine fehlende Schulung mehr meldet. Konten werden niemals allein anhand des Nachnamens zusammengeführt, da dies zu Verwechslungen zwischen Personen mit gleichem Nachnamen führen würde.

Ereigniszeit, Richtung und Duplikate: Anforderungen an die Spezifikation

Die Integrationsspezifikation verlangt, dass das KD-System Ereignisse in Echtzeit sendet, mit der vom Leser erfassten Ereigniszeit, ohne Pakete und ohne nächtliche Übertragungen. So entsprechen die Buchungszeiten in InnerWeb den tatsächlichen Durchgängen am Tor, und Verzögerungen im Netz verfälschen die Erfassung nicht.

Jedes Ereignis aus dem KD sollte die Richtung (Eingang oder Ausgang) und eine Ereigniskennung enthalten. InnerWeb nimmt die Ereignisse über den authentifizierten Webhook entgegen. Die Regeln für die Zuordnung von Ein- und Ausgängen sowie für das Verwerfen von Duplikaten werden mit dem KD-Anbieter in der Spezifikation festgelegt. Bei Betrieben mit mehreren Agenturen kann das Aufkommen an einem Werktag 2 000 Buchungen überschreiten, daher muss die Integration Ereignisserien und Wiederholungen verkraften.

Checkliste

Videomaterial

Häufig gestellte Fragen

Müssen Leser ausgetauscht werden, um die Integration in Betrieb zu nehmen?

Nein. InnerWeb produziert und tauscht keine KD-Leser aus. Die Integration besteht aus dem Versand des Buchungsereignisses vom bestehenden KD-System an InnerWeb per HTTP-POST.

Wie funktioniert die Authentifizierung mit dem Token?

Das JWT-Token aus dem API-Anmeldeendpunkt hat eine begrenzte Gültigkeit. Die Integration erneuert es automatisch mit Reserve vor dem Ablauf.

Speichert InnerWeb die Buchungszeit des Lesers?

Die Integrationsspezifikation sieht vor, dass das KD-System Ereignisse in Echtzeit mit der Ereigniszeit des Lesers sendet.

Woher kennt InnerWeb die Richtung Eintritt und Austritt?

Richtung und Ereigniskennung sendet das KD-System. Die Regeln für die Zuordnung von Ein- und Ausgängen sowie für das Verwerfen von Duplikaten legt die Spezifikation mit dem KD-Anbieter fest.

Quellen

Sprechen wir über die Integration mit Ihrem KD

Wir übergeben dem KD-Anbieter die Webhook-Spezifikation und gehen mit ihm Felder, Token und Echtzeitversand durch. Vereinbaren Sie ein Gespräch mit dem Team von InnerWeb.

Sprechen wir