KWP API-Dokumentation

Informationen zu APIs und Lizenzierung

Die Handwerkersoftware kwp-bnWin.net ist als Handwerker-Betriebssystem zu verstehen. Es bildet die zentrale Datenplattform, quasi das Herzstück, des Handwerksbetriebs.

Der Anspruch ist es, alle Kernprozesse so mit einander vernetzt abzubilden, dass keine Information doppelt oder sogar mehrfach eingegeben werden muss. Dafür steht ein umfangreicher Werkzeugkasten an KWP Programm-Modulen, Apps, Report-Services und weiteren Automatisierungstools zur Verfügung.

Allerdings benötigen oft größere Anwenderbetriebe weitere und umfangreichere Werkzeuge (SAP-Schnittstellen, Planungstools, stationäre Zeiterfassungs-Terminals, Plan-Plattformen, übergreifende Auswertungen aus DATEV, SAP und KWP etc.).

Für diese Fälle (Use-Cases) gibt es zwei Lösungsansätze:

  • Lesende Zugriffe:
    Die Datenhaltung erfolgt bei KWP in einer Microsoft SQL Datenbank (BNWINS oder BnWINB). Dort sind alle Bewegungsdaten und Stammdaten gespeichert. Artikelinformationen werden in den BNWINA-Datenbanken vorgehalten. Auf die Datenbank kann lokal per ODBC oder anderen gängigen Methoden lesend zugegriffen werden. Die Tabellen sind im Kartext benannt, so dass ein Abfrage auch ohne tiefes KWP Fachwissen möglich ist.
    Für lesende Zugriffe, vor allem Auswertungen, Echtzeit-Kennzahlen oder Reportings ist diese Form des Zugriffs optimal und uneingeschränkt.
  • Schreibende Zugriffe hingegen sind direkt in der Datenbank nicht erlaubt (Gewährleistungsverlust!), da unerwartete und nicht gewollte Seiteneffekte mit weitreichenden Folgen eintreten können.

Hier könnten die KWP APIs lizenziert und verwendet werden. Eine Übersicht aller aktuell vorhandenen APIs finden Sie unter www.swagger….

Diese Swagger-Dokumentation bezieht sich auf userbezogene Aktionen. Bitte lassen Sie diese im Vorfeld detailliert von der Gegenstelle (Programmierer) prüfen!

Die verfügbaren APIs werden ständig und mit jeder neuen KWP-Anwendung erweitert und ausgebaut. Allerdings erstellen wir keine „Auftrags-APIs“ sondern nur KWP-APIs, die auch von unseren eigenen Produkten benötigt und verwendet werden.

Je nach Use-Case und Einsatzgebiet gibt es zwei Arten der Lizenzierung:

  • Konsumentenbasierte Lizenzierung: Hier stellen wir für genau einen Anwenderbetrieb (Endkunde = Konsument) ein API-Bundle im gewünschten Funktionsumfang zusammen. Diese APIs können dann von der IT-Abteilung oder einem Dienstleister des Konsumenten anprogrammiert werden. Für so ein API-Bundle sind die einmaligen Kosten je nach API-Umfang etwas höher, aber die laufenden, monatlichen Nutzungsgebühren der KWP Backend fallen dafür geringer aus.
  • Die dienstleisterbasierte Lizenzierung hingegen richtet sich an Softwarehäuser mit einem eigenen Produkt oder einer eigenen App (z. B. Zeiterfassung oder Baustellen-Checklisten, etc.). Diese Softwarehäuser können zur Vernetzung Ihrer APP mit kwp-bnWin.net entsprechend des Use-Cases ebenfalls ein API-Bundle schnüren lassen (Einmal-Kosten eher geringer) und diese Vernetzung dann mehreren Betrieben (die beide Software-Produkte im Einsatz haben) anbieten. Jeder Konsumentenbetrieb muss dann nur das API-Bundle für die Nutzung lizenzieren, die Kosten werden monatlich über den Online-Modul-Account (aktiver Softwarepflegevertrag ist obligatorisch) abgerechnet.

Je nach Use-Case und Lizenzierungskonzept erstellen wir gerne ein unverbindliches Angebot.

Nutzung der APIs:
Ist ein API-Bundle zusammengestellt und lizenziert, so erfolgt der Zugriff über den zentralen KWP Relay, der wiederum mit dem lokalen Backend-Dienst beim Endkunden (Handwerksbetrieb) verbunden ist.

Allgemeines

Der Endkunde erhält durch KWP ein Kundenkürzel. Dies ist i.d.R. dem Kunden bekannt.

Aufruf der API via Loadbalancer

Durch Eingabe von [Kundenkuerzel] durch den Anwender kann mittels Abfrage an https://loadbalancer.kwp-online.de/Relay/GetAppUrl?linkId=[KUNDENKUERZEL] ein Hostname ermittelt werden.
Dieser kann dann https://pwaidentity.kwp-online.de oder https://kwpdev.app02.kwp-online.de (oder ein
ähnlich lautender Host) sein.
In beiden Fällen muss dann zum Aufruf der Webseite das Appendix /relay/[KUNDENKUERZEL]/pwa/
angehängt werden.

Authentifizierung

Aktuell gibt es zwei gängige Verfahren, die seitens KWP angeboten werden. Basierend auf dem Einsatzzweck kann der Password-Flow (OAuth 2.0 Password Grant) oder der Authorization Code-Flow with PKCE
(OAuth 2.0 Authorization Code Grant bzw. RFC 7636: Proof Key for Code Exchange) zum Einsatz kommen. Dies wird wird durch die KWP vorgegeben.

Der Lizenznehmer erhält folgende Infos von KWP:

  • ClientId: Diese ist nur für den Lizenznehmer gültig und sollte geheim gehalten werden.
  • ClientId (optional): passend zur ClientId für den Password-Flow.
  • Scope(s): Erlaubte Bereiche zur Nutzung der API

Für die Authentifizierung mittels Authorization Code-Flow with PKCE benötigt KWP im Vorfeld die Rücksprungadresse.

Bei beiden Abläufen benötigt der Anwender die Zugangsdaten eines BNWIN-Benutzers, in dessen Namen sich die Applikation an der API anmelden. Alle Berechtigungen innerhalb der API basieren auf diesem User.

Anschließend kann der Lizenznehmer sich mittels dem vorgegebenen Flow einen Token ermitteln.

Achtung!
Der Test innerhalb von Swagger ist KWP vorbehalten und steht nicht zur Verfügung.

Beispiel für den Ablauf mittels Password-Flow:

Anmerkung zu Authorization Code-Flow with PKCE
In der Regel wird in diesem Verfahren auch die Option des Refresh-Tokens geschaffen. Dieser sollte bevorzugt
verwendet werden, anstelle immer einen neuen Token zu erzeugen.

Token

Wird über die Authentifizierung ein Token erstellt, so enthält dieser alle wesentlichen Informationen.

Wie in untem stehenden Beispiel zu erkennen ist:

In der Startphase kann es hinsichtlich der Lizenz zu Aktualisierungs-/Timing-Problemen kommen. Sollte wider Erwarten der Zugriff auf einen Endpunkt nicht möglich sein. Sollte der Token auf jwt.io geprüft werden, ob die erwartenden Scopes enthalten sind.

Default-Parameter

Arbeitet der Endkunde mit Mandanten ist es zwingend notwendig, dass bei jedem Request das Mandanten-Kürzel mit übergeben wird. So kann die API den korrekten Datenbankzugriff sicherstellen.
Dafür ist der Queryparameter mandant zu nutzen (Beispiel: http://localhost:5000/api/Abteilung/LoadAbteilungen?mandant=02)

Archiv-Dokumenten-Austausch

Der Up-/Download von Dateien läuft nicht über den direkten Http-Request an die API. Dokumente werden über den Azure-Blob-Storage ausgetauscht.
Dateien im Azure-Blob-Storage werden nach 24 h automatisch gelöscht.

Upload von Dateien

Der ConnectionString des Azure-Blob-Storage kann über den Endpunkt api/archiv-extern/GetSetup -> Property azureConnectionUri abgerufen werden. Diese Url sollte für 6 h gecached werden.
Um eine Datei in den Azure-Blob-Storage hochzuladen, kann die offizielle Microsoft Library (z. B. @azure/storage-blob für nodejs) verwendet werden.

Über den Endpunkt api/archiv-extern/ImportDatei kann nun die Datei aus dem Azure Blob Storage in das KWP Archiv archiviert werden. Die GUIDv4 (containerId) und der Dateiname (dateiname) ist im Body zu übergeben.

Download von Dateien

Über den Endpunkt api/archiv-extern/ExportDatei kann eine Datei aus dem KWP Archiv heruntergeladen werden. Hierfür ist die eindeutige ID (revisionId) des Archiveintrags, als auch eine GUIDv4 (guid) zu übergeben.
In der Response befindet sich unter dem Property exchangeFileUri eine Url zu einer Json-Datei, in welcher wiederum sich der eigentliche Downloadlink befindet.