Jeder Datensatz, der über die Account-API eingeht, wird vom Shop so behandelt, als hätte der Kunde die Änderung selbst vorgenommen. Der Datensatz wird deshalb als geändert markiert und taucht beim Abruf der Adressdatenänderungen per SOAP auf.
Technische Grundlagen
Die Schnittstelle hat einen einzigen Zugangspunkt. Die Daten werden als Payload in einem JSON-WebToken per POST übergeben. Der Aufruf ist nur per SSL möglich. Eine Authentifizierung über ein Berechtigungstoken gibt es nicht, stattdessen validiert der Shop die Signatur des JSON-WebTokens. Dafür ist pro Konnektor ein eigenes SharedSecret hinterlegt. Die Berechtigungen des Konnektors konfiguriert WEBSALE. Jeder Aufruf muss mit der zugehörigen Shop-Domain erfolgen, denn über die Domain ermittelt der Shop den Subshop, dessen Konfiguration für die Prüfung der Adressdaten gilt. Die Freischaltung der Account-API erfolgt auf Antrag des Shopbetreibers durch die WEBSALE AG. Dabei wird festgelegt, wie viele Konnektoren verwendet werden dürfen. Diese Anzahl lässt sich später per Antrag erhöhen oder senken. Die Konfiguration der einzelnen Konnektoren nehmen Sie selbst vor. Die Nutzung der Account-API erhöht den Leistungsverbrauch des Shops.Verhalten der Schnittstelle
Werden Adressdaten oder Kundenkontodaten übergeben, prüft der Shop zuerst, ob der Konnektor für jedes einzelne Feld die nötige Berechtigung hat. Fehlt sie auch nur für ein Feld, führt der Shop keine Aktion aus und gibt einen Fehler zurück. Teilweise Updates gibt es nicht. Ein Kundenkonto lässt sich auf zwei Arten adressieren. Über die E-Mail-Adresse. Existiert bereits ein Konto mit dieser Adresse, führt der Shop die gespeicherten Daten mit den übergebenen zusammen, wobei die übergebenen Werte die bestehenden überschreiben. Anschließend validiert er die Adressdaten gegen die im Shop konfigurierten Prüfungen. Nur wenn diese Prüfung bestanden ist, werden die Daten in der Kundendatenbank aktualisiert. Existiert noch kein Konto, legt der Shop nach erfolgreicher Prüfung ein neues an und kann dabei die in der Konnektor-Konfiguration hinterlegten Werte vorbelegen, beispielsweise einen eigenen Rabattsatz pro Konnektor. Über den UserIndex. Hier ist nur die Aktualisierung oder Prüfung eines bestehenden Kontos möglich, ansonsten gilt dasselbe wie bei der Adressierung über die E-Mail-Adresse. Mehrfachkonten, also mehrere Konten zu einer E-Mail-Adresse, lassen sich über die Account-API nicht anlegen. Update und Login sind für Mehrfachkonten nur über den UserIndex möglich. Grundsätzlich gilt: Nach dem Zusammenführen der übergebenen und der vorbelegten Daten mit den vorhandenen Daten muss ein gültiger Datensatz entstehen. Ist das nicht der Fall, übernimmt der Shop keine Daten, legt keinen neuen Datensatz an und gibt einen Fehlercode zurück. Das betrifft auch die Vorbelegung: Soll bei einer Neuanlage eine Adresse vorbelegt werden, muss aus der Kombination von übergebenen und vorbelegten Werten eine gültige Adresse entstehen.Berechtigungen
Die Berechtigungen werden pro Konnektor festgelegt und müssen immer explizit gesetzt werden. Sie decken drei Bereiche ab. Neuanlage und Update eines Accounts. Dazu gehören die Liste der zulässigen Domains für die E-Mail-Adresse des Kontos (die auch für Updates per UserIndex gilt), kundenabhängige Rabattsätze, Subshop-Berechtigungen und Hauptsubshop, die Kundennummer, Zahlungsarten, die SuperUserID, die Nutzung des Bestellgenerators, das Setzen eines neuen Passworts und die Änderung der E-Mail-Adresse. Rechnungsadressdaten, mit Ausnahme von E-Mail-Adresse und Kundennummer. Hier gibt es eine generelle Berechtigung, Adressdaten überhaupt zu übergeben, und darunter eine Berechtigung auf Feldebene, entweder für einzeln benannte Felder oder für alle Felder über eine Wildcard. Datenabfrage. Der Konnektor darf einen Login-Deeplink abfragen, über den ein Kunde mit automatischer Anmeldung in den Shop weitergeleitet wird. Unabhängig von diesen Berechtigungen lassen sich Datenfelder festlegen, die bei Neuanlage oder Update automatisch gesetzt werden: der kundenabhängige Rabattsatz, Subshop-Berechtigungen und Hauptsubshop, Zahlungsarten, die Nutzung des Bestellgenerators sowie beliebige Werte pro Adressdatenfeld.Konfiguration
Die Konnektoren werden in der globalen Konfigurationsdateiaccount-api-access.config.json angelegt. Die Datei enthält ein JSON-Array, in dem jeder Zugang durch ein Zugangsobjekt beschrieben wird.
Zugangsobjekt
Berechtigungsobjekt
Wildcards in
alloweddomains. Jeder durch einen Punkt getrennte Teil der Domain kann durch einen Stern ersetzt werden.
Wildcards in
fields. Am Ende einer Feld-ID kann ein Stern stehen. FirstName berechtigt für den Vornamen, Suffix* für alle Suffixfelder und * für alle Felder. Der letzte Fall schließt auch kritische Felder mit ein.
Datenaktualisierungsobjekt
Das Objektdata hat zwei gleich aufgebaute Zweige. preset belegt Daten bei der Neuanlage eines Kundenkontos vor, overwrite aktualisiert Daten bei Update oder Abfrage eines bestehenden Kontos. Beide enthalten jeweils ein accountdata- und ein addressdata-Objekt.
Im
accountdata-Objekt wird hier nur ein Teil der Felder unterstützt, die der Payload kennt. Die Adressdatenfelder entsprechen denen der Payload.
Beispiel
Der Aufruf
Endpunkt und JSON-WebToken
Die REST-API wird mit einer POST-Anfrage an den Endpunkt/_api/shop/Account aufgerufen. Als POST-Daten wird ein JSON-WebToken mit der Payload übergeben.
Der Header verwendet den Signaturalgorithmus HS256 und den Typ JWT. Die Signatur entsteht aus
{ "hello": "world" } und dem SharedSecret geheim ergibt dieses dekodierte Token:
Payload
Das folgende Beispiel aktualisiert das Kundenkonto mit der E-Mail-Adresse
test@domain.de, setzt 5 Prozent Kundenrabatt und das Feld Suffix12 der Rechnungsadresse auf conA und fordert den Login-Link an:
Antwort
Im Erfolgsfall antwortet die Schnittstelle mit dem HTTP-Statuscode 200 und einem JSON-Objekt, das einen Code und optional einreturn-Objekt mit den angefragten Daten enthält.
Im Fehlerfall antwortet die Schnittstelle, soweit zutreffend, mit den HTTP-Statuscodes 401 oder 403, ansonsten mit 400. Zusätzlich kommt ein JSON-Objekt mit Fehlercode und gegebenenfalls einer Fehlermeldung zurück.