Zu Content springen
Deutsch
Anmelden
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

API Dokumentation

Inhaltsverzeichnis

  1. API-Anbindung

  2. Verfügbare Methoden

  3. Allgemeines zu den Angaben im Request

  4. Validierung

  5. Authentifizierung

  6. Erläuterungen zu den einzelnen Endpunkten

Mit der Smartphone-App DriversCheck kontrollieren die FahrerInnen eines Unternehmens ihre Führerscheine ortsunabhängig und dennoch sicher. Neben der direkten Kontrolle über die DriversCheck App, können Unternehmen die Funktion der elektronischen Führerscheinkontrolle ebenfalls in Ihre eigene Software einbinden.

💡
Unsere aktuelle Swagger-Dokumentation der DriversCheck Web API kannst du hier einsehen: https://api2.drivers-check.de/swagger/#/
 

1. API-Anbindung

Über die Schnittstelle binden Unternehmen die Funktion der elektronischen Führerscheinkontrolle in die eigene Software ein.

 
Die Application Programming Interface (API) ist eine Schnittstelle, welche einem Programmteil die Kommunikation mit anderen Programmteilen erlaubt. Dank vorprogrammierter Standardbefehle können verschiedene Programme und Add-Ons kombiniert werden, ohne dass ein gesamtes Programm umgeschrieben werden muss.
 

Was ist eine REST-API?

Die REST-API (RESTful API) ist eine API, die den Beschränkungen der REST-Architektur unterliegt und Interaktionen mit RESTful Webservices ermöglicht. REST-API´s verwenden eine einheitliche Schnittstelle für die Kommunikation und erleichtert verschiedenen Systemen, miteinander zu kommunizieren.

 

Was ist REST?

REST bedeutet „Representational State Transfer“ und beschreibt eine Sammlung von Architekturbeschränkungen, die flexibel implementiert werden können. REST legt die Bedingungen zur Funktionsweise einer API fest.

 

Unabhängig von der Größe eines Unternehmens bringt die Umstellung auf die elektronische Führerscheinkontrolle keine Einschränkungen eingespielter Arbeitsprozesse mit sich. Dank der Einbindung über eine API wirkt DriversCheck mehr wie ein Add-On, welches das Grundsystem durch eine modernen Führerscheinkontrolle erweitert. Hierfür sind zumeist nur kleine Anpassungen notwendig, damit beide Systeme zuverlässig miteinander kommunizieren können.

 
💡
Besuche unsere Website und klicke auf diesen Link um mehr zur erfahren. Gerne beantworten wir dir auch Fragen zu Anpassungen oder weiteren Ergänzungen. Wende dich hierzu an unseren Kundenservice: kundenservice@drives-check.de

2. Verfügbare Methoden

GET
liefert Daten von Organisationen oder Mitarbeitern aus DriversCheck - Zugriffsberechtigung erfolgt über die Authentifizierung
PUT
aktualisiert bestehende Daten anhand der UUID der Organisation oder des Mitarbeiters
POST
erstellt neue Daten anhand mitgelieferter Angaben - beim Anlegen einer neuen Organisation oder eines neuen Mitarbeiters, wird eine UUID individuell und automatisch durch das System erstellt - die jeweilige UUID ist dem Response zu entnehmen
DELETE
löscht Daten eines Mitarbeiters - die zweifelsfreie Zuordnung erfolgt über die UUID des Mitarbeiters
 

3. Allgemeines zu den Angaben im Request

Unter Schema kann im Detail nachvollzogen werden, in welcher Form die Angaben im Request-Body erfolgen müssen, sofern eine Angabe erforderlich/erwünscht ist.

API_1
 

4. Validierung

Alle Felder, die bei einem Request angegeben werden, werden entsprechend den Vorgaben validiert.

API_2
 

Bei einer fehlgeschlagenen Validierung gegen das JSON-Schema, wird eine Fehlermeldung ausgegeben.

Beispiel:

 
💡
{

"message": "All array items must match schema: https://api2.drivers-check.de/schema/uuid_list.json"

}

 

Die gelieferten Daten können mittels der Schema-Datei unter https://www.jsonschemavalidator.net/ abgeglichen werden.

Anzeige/Auswahl verschiedener Berechtigungen und Module

Berechtigungen:

API_3
 

Wird bei Erstellung eines Mitarbeiters kein Wert hinterlegt, erhalten diese Flags den angegebenen Default-Wert. Die Datenänderung kann über den PUT-Request erfolgen.

 

Module:

API_4
 

Wird bei Erstellung eines Mitarbeiters kein Wert hinterlegt, erhalten diese Flags den angegebenen Default-Wert. Die Datenänderung kann über den PUT-Request erfolgen.

5. Authentifizierung

Die Authentifizierung erfolgt über einen POST-Request mittels Username, Passwort und API-Key. Der API-Key muss im Header angegeben werden und wird über den Kundenservice aktiviert.

Hinterlegung x-api-key, Beispiel Postman:

API_5
 

Nach Ausführung des Requests wird als Antwort der Bearer-Token zurückgegeben.

APi_6
 

Der Bearer-Token aus dem Authentifizierungs-Request muss in allen weiteren Anfragen hinterlegt werden. Dabei ist darauf zu achten, dass dieser identisch und gültig ist.

API_7
 
 

💡

Erfolgt nach einem Request diese Meldung, ist die Gültigkeit abgelaufen oder der Token nicht identisch.

API_8
 

Nach Ablauf der Gültigkeit, muss der Authentifizierungs-Request erneut durchgeführt werden.

6. Erläuterungen zu den einzelnen Endpunkten

Organisationen

GET/organisations

Es wird eine Liste aller aktiven UUIDs angezeigt, zu welchen der aktuell authentifizierte Nutzer zugriffsberechtigt ist. Die Rückgabe besteht aus einem JSON Array, welches die UUIDs beinhalten.

Optional gibt es die Möglichkeit, im Body des Requests die UUID´s der Organisationen / der Organisation anzugeben, um die Detailinformationen der angegebenen Organisationen abzurufen.

API_9
 

POST/organisations

Es können unter einer bestehenden UUID (Hauptorganisation oder Unterorganisation) neue Organisationen angelegt werden. Dem Response wird die erfolgreiche/fehlgeschlagene Erstellung entnommen.

 

PUT/organisations

Es werden die im Request angegebenen Daten der Organisation/ der Organisationen geändert. Dazu muss die entsprechende UUID und die zu ändernden Daten im Request-Body hinterlegt sein. Weiterführende Informationen zu den Angaben im Request befinden sich in den allgemeinen Hinweisen. Das Änderungsergebnis enthält Informationen, ob der Request erfolgreich durchgeführt werden konnte.

 

Mitarbeiter der Organisation

GET/organisation/{uuidOrganisation}/employees

Keine Angabe im Request-Body:

Es wird eine Liste aller aktiven Mitarbeiter angezeigt, die der in der URL angegebenen UUID-Organisation zugehörig sind.

Angabe der UUID im Request-Body:

Sofern eine JSON-Liste von UUID im Request-Body definiert ist, wird eine Liste von Detailinformationen zu Mitarbeitern welche durch Angabe derer UUID im Body des Request definiert wurden, ausgegeben. Es können maximal 100 Mitarbeiter in einem Request abgefragt werden.

Fehlerhaft, unbekannt oder Detailinformationen zu welchen der aktuelle API User nicht berechtigt ist, werden ignoriert und nicht ausgeliefert.

Abrufbare Daten werden dem Response-Body entnommen.

 

POST/organisation/{uuidOrganisation}/employees

Hier können unter einer bestehenden UUID-Organisation (Hauptorganisation oder Unterorganisation) neue Mitarbeiter angelegt werden.

Hierbei wird für jeden Nutzer eine Individuelle UUID generiert, welche dem Mitarbeiter im eigenen System zugeordnet werden muss.

Für die Zuordnung im eigenen System können folgende Wege genutzt werden:

  • Es wird ein eindeutiges Zuordnungsmerkmal (z.B. Personalnummer) übermittelt. Dieses Merkmal wird im Response mit der UUID zurückgegeben.
  • Die Zuordnung kann über eine Reihenfolge der Objekte durchgeführt werden (gleichbleibend gemäß Lieferung)
  • Die Nutzer können einzeln angelegt werden.
 

Die UUID wird ausschließlich durch die Anlage generiert und im Response zurückgegeben. Eine vorherige Vergabe ist nicht möglich.

 

PUT/organisation/{uuidOrganisation}/employees

Es werden die im Request angegebenen Daten des Mitarbeiters geändert. Dazu muss die entsprechende UUID der Organisation in der URL und die zu ändernden Daten im Request-Body hinterlegt sein.

Mitarbeiter

Übertragung der Führerscheinnummer: Die Führerscheinnummer darf aktuell nur übertragen werden, insofern es sich um die Nummer eine deutschen EU-Kartenführerscheins handelt. So ist sichergestellt, dass FahrerInnen mit hinterlegter Nummer eine siegellose Kontrolle durchführen können. Führerscheinnummern die nicht dem Format entsprechen werden bei der Einlieferung abgelehnt, sodass der Datensatz nicht angelegt werden kann.

GET/employees

Keine Angabe im Request-Body:

Es wird eine Liste aller aktiven Mitarbeiter angezeigt, zu welchen der aktuell authentifizierte API-Nutzer zugriffsberechtigt ist.

Angabe der UUID im Request-Body:

Sofern eine JSON-Liste von UUID im Request-Body definiert ist, wird eine Liste von Detailinformationen zu Mitarbeitern welche durch Angabe derer UUID im Body des Request definiert wurden, ausgegeben. Es können maximal 100 Mitarbeiter in einem Request abgefragt werden.

Fehlerhaft, unbekannt oder Detailinformationen zu welchen der aktuelle API User nicht berechtigt ist, werden ignoriert und nicht ausgeliefert.

Abrufbare Daten werden dem Response-Body entnommen.

PUT/employees

Es werden alle in der Liste angegebenen Mitarbeiter aktualisiert . Dazu muss die entsprechende UUID des Mitarbeiters und der Organisation im Request-Body hinterlegt sein.

POST/employees

Es werden alle in der Liste erstellen Mitarbeiter angelegt. Die UUID-Organisation muss dabei im Request angegeben werden, unter die der Mitarbeiter angelegt werden soll. Es wird für jeden Nutzer eine Individuelle UUID generiert, welche dem Mitarbeiter im eigenen System zugeordnet werden muss.

DELETE/employees

Hier können mehre Mitarbeiter gelöscht werden. Maßgebend ist hierfür die Angabe der jeweiligen UUID´s der Mitarbeiter im Request-Body. Dem Response ist zu entnehmen, ob die Löschung erfolgreich durchgeführt wurde oder fehlgeschlagen ist.

successful: Die Daten des Mitarbeiters werden gelöscht. Wird die UUID des Mitarbeiter erneut im Request-Body eingegeben, wird diese unter „failed“ angezeigt.

failed: Die hier angezeigten UUID´s wurden nicht gelöscht. Grund hierfür kann eine Falscheingabe der UUID sein, oder der entsprechende Mitarbeiter wurde bereits gelöscht bzw. ist im System nicht vorhanden.

Einzelne Mitarbeiter

GET/employee/{uuidEmployee}

Es wird der Mitarbeiter angezeigt, dessen UUID in der URL angegeben wurde. Dem Response-Body werden die gespeicherten Daten entnommen.

PUT/employee/{uuidEmployee}

Es wird der Mitarbeiter aktualisiert, dessen UUID in der URL angegeben wurde. Dem Response-Body werden die gespeicherten Änderungen entnommen.

DELETE/employee/{uuidEmployee}

Es wird der Mitarbeiter gelöscht, dessen UUID in der URL angegeben wurde. Es erfolgt keine Werterückgabe

GET/employee/{uuidEmployee}/systemmessages

Es wird die letzte Systemnachricht und das entsprechende Erstellungsdaten der Nachricht angezeigt.

GET/employee/{uuidEmployee}/escalations

Es zeigt den Zeitstempel der letzten Eskalation zu den Modulen Führerscheinkontrolle und Fahrerunterweisung.

GET/employee/{uuidEmployee}/checkups

Hier werden Informationen zu den letzten durchgeführten Kontrollen angezeigt.

Führerscheinkontrolle:

  • Handelt es sich um eine Selbstkontrolle?
  • Wer hat die Kontrolle durchgeführt?
  • Wann war die letzte Kontrolle?
  • Wann ist die nächste Kontrolle?
  • Ist die aktuelle Kontrolle gültig?

Fahrerunterweisung:

  • Wann war die letzte Kontrolle?
  • Wann ist die nächste Kontrolle?
  • Ist die aktuelle Kontrolle gültig?