Authentifizierungsmethoden
Um die API nutzen zu können gibt es drei Authentifizierungsmethoden
- Einfache Browser Authentifizierung – für Exporte, Datenblätter, Bildlinks, schnelle Anzeige im Browser, usw…
- ITscope Authentication – setzt eine aktive Browsersession auf https:/www.itscope.com vorraus und sollte nicht programmatisch benutzt werden. Diese Methode kann z.B. bei Deeplinks von autorisierten Teilnehmern auf die Plattform genutzt werden.
- Programmatische Authentifizierung via HTTP Basic Authentication – dies ist die Standard Authentifizierung mit Username:Passwort für die Nutzung der ITscope API.
Hier gibt es 2 unterschiedliche Varianten:- Persönlicher API Zugang zur individuellen Nutzung der API. Diese Variante wird im folgenden Abschnitt beschrieben.
- Schnittstelle von Partnersystemen an ITscope, die eine Anbindung für gemeinsame Kunden implementieren. Unsere Schnittstellenpartner erhalten die entsprechenden Anweisungen im Rahmen der Implementierung auf Anfrage.
Persönlicher ITscope API Zugang
Im eigenen Mitarbeiterprofil können die persönlichen ITscope API Zugangsdaten eingesehen werden. Diese werden zur Username:Passwort HTTP Basic Authentication für die ITscope API benötigt.
Folgende Daten werden benötigt:
- Account-ID – als Username
- API Key – als Passwort
Damit sind Zugriffe auf die ITscope API erst möglich.
Falls man einen neuen API Key benötigt, kann man diesen mit dem Button Neuer API Key generieren. Dadurch wird der alte Key ungültig!
Programmatische Authentifizierung via HTTP Basic Authentication
Zur programmatischen Authentifizierung im Entwicklungs Code muss in den Header der Api Benutzer (Account-ID) und das API Passwort (API-Key) als Base64 codiert angegeben werden. Dafür nutzt man zum Beispiel einen Dienst wie https://www.base64encode.org und kodiert damit die Username:Password ‚<Accound-ID>:<API Key>‘ Zeichenkette. Das Ergebnis der Kodierung muss dann im HTTP-Header Authorization:Basic eingefügt werden. Wird die API-URL interaktiv im Browser eingegeben, erfolgt die Authentifizierung über die Standardmechanismen des Browsers für „Basic Auth“.
Beispiel PseudoCode für einen API Request:
Beispiel Pseudocode für einen Abruf über die ITscope API inklusive Pflicht HTTP Header User-Agent
...
// api url ohne zugangsdaten, z.B.
string apiurl = "https://api.itscope.com/2.1/products/search/ean=0888462025737/standard.xml";
HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiurl);
//username:password Kombination Base64 codiert
string credentials = <Account-ID>+ ":" + <API Key> ;
authorization = Convert.ToBase64String(Encoding.Default.GetBytes(credentials));
// Basic Authorization als http Header
request.Headers["Authorization"] = "Basic " + authorization;
// useragent in der Form <applicationCompany>-<applicationName>-<applicationVersion>
// z.B. MeineFirma-MeineAnwendung-4.0927
request.UserAgent = "MeineFirma-MeineAnwendung-4.0927"
//sonstiges
request.Method = "GET"
request.KeepAlive = True
request.ContentType = "application/xml"
request.AllowAutoRedirect = True
...
Beispiele für die programatische Authentifizierung
Beispiel Pseudocode für die Nutzung eines generierten C# Clients direkt aus dem Swagger Framework der ITscope API inklusive Pflicht HTTP Header User-Agent
...
Configuration config = new Configuration();
//username:password Kombination Base64 codiert
string credentials= ApiClient.Base64Encode("<Account-ID>:<API Key>");
// Basic Authorization als http Header
config.AddDefaultHeader("Authorization", "Basic" + credentials);
// useragent in der Form <applicationCompany>-<applicationName>-<applicationVersion>
// z.B. MeineFirma-MeineAnwendung-4.0927
config.setUserAgent("MeineFirma-MeineAnwendung-4.0927");
// sonstiges
ProductsApi pApi = new ProductsApi(config);
...
Beispiel Pseudocode Header für ein PHP-Skript:
....
//username:password Kombination Base64 codiert
// Basic Authorization als http Header
header('Authorization: Basic '. base64_encode("<Account-ID>:<API Key>"));
// useragent in der Form <applicationCompany>-<applicationName>-<applicationVersion>
// z.B. MeineFirma-MeineAnwendung-4.0927
header('UserAgent:MeineFirma-MeineAnwendung-4.0927');
....
Beispiel Pseudocode Header für ein PHP-Skript mit curl:
....
//username:password Kombination nicht Base64 codiert wenn die curl Option CURLAUTH_BASIC gesetzt ist,
//dann führt curl eine Bas64 codierung selber durch
$UserPWD ="<Account-ID>:<API Key>";
$url = "https://api.itscope.com/2.1/products/search/ean=".$ean."/standard.xml";
$UserAgent = $_SERVER['HTTP_USER_AGENT'];
$options = array(CURLOPT_URL => $url,
CURLOPT_HEADER => true,
CURLOPT_USERAGENT => $UserAgent,
CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
CURLOPT_USERPWD => $UserPWD);
$ch = curl_init();
curl_setopt_array($ch, $options);
$data = curl_exec($ch);
....
Einfache Browser Authentifizierung
Die einfachste Möglichkeit den Export über den Browser, per wget oder in der Windows-Aufgabenplanung u.ä. aufzurufen ist die Authentifizierung direkt in der URL zu übergeben (der Benutzer muss immer den Eintrag im Feld Account-ID haben, siehe oben!)
Hinweis: Diese Methode funktioniert nicht im Internet Explorer.
Ein Beispiel-Abruf im Browser für einen Export
https://<Account-Id>:<API Key>@api.itscope.com/2.1/products/exports/<EXPORT-ID>
Geben Sie beim Abruf der URL weder den Benutzername <accoundId> noch das Passwort <API-Key> an, erfolgt die Authentifizierung über den Standardmechanismus des Browsers für „Basic Auth“ und Sie werden in einem separaten Fenster nach den Zugangsdaten gefragt.
ITscope-Authentication
Diese Art der Authentifizierung ist hauptsächlich für Deeplinks in die Platform gedacht und setzt eine aktive Session in ITscope voraus. Sollte keine solche bestehen, wird auf die Login-Seite verwiesen. Dazu hängt man der API-URL den Query-Parameter ‚auth‘ mit Wert ‚itscope‘ an. Ein Aufruf sieht dann wie folgt aus:
https://api.itscope.com/2.1/products/ean/0886111583935/deeplink.html?auth=itscope
Ihre Systeme an ITscope anbinden
Mithilfe einer individuellen API-Integration können Sie auch über nicht standardmäßig an ITscope angebundene ERP- und Warenwirtschaftssysteme Aktionen wie Importe von Produktdaten, Preisen, etc. mit ITscope durchführen.
Lesen Sie hier mehr über das ITscope Add-on Individuelle API Integration.