Um auf die API zugreifen zu können muss man sich zuerst authentifizieren. Ein technischer Zugang erfolgt über Zugangsdaten, die im AMPAREX eingerichtet werden. Dazu wird der technische Login immer dann benutzt, wenn technische Daten abgerufen oder gespeichert werden sollen. Typischerweise z. B. allgemeine Exporte oder Kalendersynchronisationen. Dabei ist man auf eine Filiale und einen Benutzer beschränkt.
Im Gegensatz zum technischen Login gibt es noch einen fachlichen Login. Dieser wird immer dann benötigt, wenn sich verschiedene Mitarbeiter über die API anmelden möchten. Mögliche Anwendungsfälle sind z. B. Mobile APPs mit Login von Mitarbeiten. Vor einem fachlichen Login muss immer ein technischer Login erfolgen.
Technischer Login
DEr technische Login erfolgt über sogenannte Zugangsdaten.
Der Ablauf ist folgender:
- Um die API zu verwenden wird ein Alias benötigt, über den ermittelt werden kann, wer auf die API zugreift. Den Alias erhält man im AMPAREX Client über die Filialverwaltung → Servicezugangsdaten → Ressource spezifische URL - siehe Nachfolgend Schritte 1-3.
- Über Schritt 4 wird die für den Swagger-UI benötigte Ressourcen spezifische URL angezeigt und mit Schritt 5 der Alias kopiert.
- Wechseln Sie in die Swagger-UI. Im Login Bereich in der Swagger-UI aufklappen und auf 'Try-it-Out' klicken:
- Tragen Sie alle erforderlichen Parameter ein. Benutzername und Passwort entsprechen den Servicezugangsdaten des Alias:
- Klicken Sie auf Execute → die Anfrage wird an den Server geschickt.
- Als Antwort erscheint im Feld 'Server Response' nun das für den Login benötigte Token (Bearer Token).
- Markierten und kopieren Sie alles zwischen den Anführungszeichen.
- Klicken Sie im Kopf von Swagger-UI auf Authorize.
In dem erscheinenden Dialog muss in dem Feld 'Value' das Login Token (Bearer Token) eingetragen werden. Dazu "Bearer" eintippen gefolgt von einem Leerschritt. Danach das zuvor erhaltene Login-Token einfügen und auf 'Autorize' klicken.
- Das Login Token ist nun gesetzt und wird für alle HTTP Aufrufe im Header mitgeschickt.
Fachlicher Login
Vor einem fachlichen Login muss immer ein technischer Login erfolgen, siehe oben. Der fachliche Login muss immer erfolgen, wenn sich mehrere Mitarbeiter in unterschiedlichen Filialen über die API anmelden möchten.
Für einen fachlichen Login können die bestehenden Benutzer Logindaten in AMPAREX verwendet werden.
Achtung
Für einen fachlichen Login muss ein sicheres Passwort in AMPAREX verwendet werden (Groß-/Kleinbuchstaben mit Zahlen und Sonderzeichen). Ist das Passwort unsicher wird der Login über die API abgelehnt. Dabei erhalten sie aus Sicherheitsgründen aber keine Hinweise in der Fehlermeldung. Die Fehlermeldung ist ein HTTP Status Code 401 (Unauthorized) ohne weiteren Hinweis.
Für einen fachlichen Login müssen erst die möglichen Filialen ermittelt werden. Dies geschieht über einen API Zugriff:
Das Alias ist dasselbe, dass schon im technischen Login verwendet wurde. Um alle Filialen zu erhalten, sollten alle Suchparameter zuerst gelöscht und evtl. ein Limit angeben werden.
Die entsprechende BranchID aus dem Response kopieren:
Über den Response könnte auch ein Dialog erstellt werden, indem alle verfügbaren Filialen angezeigt werden.
Nun erfolgt der fachliche Login:
Im Response erhalten Sie nun ein neues Login Token, dass wie im technischen Login verwendet werden muss. Siehe Punkt 6-9 im technischen Login.