Account-API (DE)

Über die Account-API ist es möglich, Kundenkonten neu anzulegen und zu aktualisieren. Zusätzlich kann der Kunde über diese Schnittstelle im Webshop angemeldet werden. Die Zugriffsrechte auf die einzelnen Bereiche der Kundendaten können individuell konfiguriert werden.

Technische Spezifikation

Die Schnittstelle zu WEBSALE ist als REST-Schnittstelle mit einem einzigen Zugangspunkt implementiert, Daten werden als Payload in einem JSON-WebToken (JWT) per POST übergeben.

Die REST-Schnittstelle ist nur per SSL aufrufbar (Transportsicherheit), auf eine Authentifizierung mittels Berechtigungstoken wird verzichtet. Die Validierung erfolgt durch die Signatur des JSON-WebTokens, dafür wird für jeden Konnektor ein eigenes SharedSecret hinterlegt, sowie die Berechtigungen des Konnektors durch WEBSALE konfiguriert.

Ein Aufruf der REST-Schnittstelle muss immer mit einer zugehörigen Shop-Domain erfolgen.

Verhalten der Schnittstelle

Wenn Adressdaten und/oder Kundenkontodaten übergeben werden, wird geprüft, ob der Konnektor die Berechtigung zur Prüfung bzw. zum Setzen der Daten für das angegebene Kundenkonto besitzt. Existiert für mindestens ein Datenfeld keine Berechtigung, wird keine Aktion durchgeführt und ein entsprechender Fehler zurückgegeben. Es erfolgen keine teilweisen Updates.

Adressierung des Kundenkontos anhand der E-Mail-Adresse:

  • Wenn ein Kundenkonto mit der angegebenen E-Mail-Adresse bereits existiert, werden die gespeicherten Daten aus der Kundendatenbank mit den übergebenen Daten zusammengeführt und Adressdaten gegen die im Webshop konfigurierten Prüfungen validiert. Bei der Zusammenführung der Daten überschreiben die Werte in den übergebenen Feldern die bestehenden Daten. Nur bei positiver Validierung werden die Adressdaten, sowie auch alle anderen übergebenen Daten, in der Kundendatenbank aktualisiert.

  • Wenn kein Kundenkonto mit der angegebenen E-Mail-Adresse existiert, wird, nach positiver Prüfung von ggf. übergebenen Adressdaten, ein neues Kundenkonto angelegt. Dabei können optional bei der Konnektor-Konfiguration angegebene Daten vorbelegt werden, wie z. B. ein eigener Kundenrabattsatz pro Konnektor.

Adressierung des Kundenkontos anhand eines UserIndexes:

  • In diesem Fall ist nur eine Aktualisierung bzw. Prüfung eines bestehenden Kundenkontos analog zur Adressierung anhand der E-Mail-Adresse möglich.

Für die Prüfung der Adressdaten wird die Konfiguration des zugehörigen Subshops anhand der Domains des REST-Aufrufs ermittelt.

Mehrfachkonten (unterschiedliche Accounts für eine E-Mail-Adresse) können über die REST-Schnittstelle nicht angelegt werden. Ein Update bzw. Login ist für Mehrfachkonten nur über Angabe des Userindexes möglich.

Berechtigungen

Pro Konnektor werden bei WEBSALE zugehörige Berechtigungen festgelegt. Dabei gilt: Berechtigungen müssen immer explizit gesetzt werden.

Folgende Berechtigungen können festgelegt werden:

  • Neuanlage oder Update eines Accounts

    • Liste an zulässigen Domains, für welche E-Mail-Adressen eine Neuanlage/Update möglich ist (gilt auch für Updates mit UserIndex)

    • Setzen kundenabhängiger Rabattsätze

    • Setzen von Subshop-Berechtigungen/Hauptsubshop

    • Setzen der Kundennummer

    • Setzen von Zahlungsarten

    • Setzen der SuperUserID

    • Setzen der Nutzung des Bestellgenerators

    • Setzen eines neuen Passworts in Kombination mit automatischem, zwingendem Setzen eines neuen Passworts beim nächsten Login

    • Änderung der E-Mail-Adresse

  • Rechnungsadressdaten (mit Ausnahme von E-Mail-Adresse und Kundennummer):

    • Generelle Berechtigung Rechnungsadressdaten zu übergeben

    • Berechtigung auf Feldebene:

      • explizite Angabe, welche Felder gesetzt werden dürfen (einzeln)

      • generelle Freigabe aller Felder (inkl. einfacher WildCard-Unterstützung)

  • Datenabfrage:

    • Konnektor darf Login-Deeplink zur Weiterleitung eines Kunden inkl. automatischer Anmeldung abfragen

Zusätzlich können noch spezifische Datenfelder gesetzt werden, welche bei Neuanlage und/oder Update eines Kundenkontos automatisch gesetzt werden. Diese werden unabhängig von den gewährten Berechtigungen angewandt:

  • Neuanlage oder Update eines Accounts

    • kundenabhängiger Rabattsatz

    • Subshop-Berechtigungen/Hauptsubshop

    • Zahlungsarten

    • Nutzung des Bestellgenerators

  • Rechnungsadressdaten (mit Ausnahme von E-Mail-Adresse und Kundennummer):

    • beliebige Werte pro Adressdatenfeld

Dabei gilt:
Wenn Adressdaten vorbelegt werden sollen, muss bei einer Neuanlage auch eine, in Kombination mit den vorbelegten Werten, gültige Adresse entstehen. Ist dies nicht der Fall, wird kein neues Kundenkonto angelegt.

Generell gilt:

Sobald Daten übergeben bzw. übernommen (automatisch gesetzt/vorbelegt) werden sollen, muss nach Zusammenführung dieser Daten mit den vorhandenen Daten ein gültiger Datensatz entstehen. Ist dies nicht der Fall, werden keine Daten übernommen bzw. neue Datensätze angelegt und die Schnittstelle gibt einen Fehlercode zurück.

Verfügbarkeit und Leistungsverbrauch:

Die Freischaltung der Account-API erfolgt nach Antrag des Shopbetreibers durch die WEBSALE AG. Dabei wird die Anzahl an verwendbaren Konnektoren definiert, diese kann später durch Antrag erhöht bzw. reduziert werden. Die Konfiguration der einzelnen Konnektoren kann durch den Shopbetreiber selbst erfolgen. Durch die Verwendung der Account-API fällt ein erhöhter Leistungsverbrauch an.

Konfiguration

Die Konfiguration erfolgt in der globalen Konfigurationsdatei account-api-access.config.json.

Die Konfiguration erfolgt im JSON-Format, die Zugänge werden als JSON-Array angelegt.

Pro Zugang wird ein eigenes Zugangsobjekt angegeben.

Zugangsobjekt

Feld

Wert

Pflicht

Beschreibung

Feld

Wert

Pflicht

Beschreibung

connectorid

alpha-num String

x

beliebige, aber eindeutige technische ID des Konnektors

secret

String

x

Passwort, shared secret für JWT

description

String

 

Beschreibung des Konnektors

permissions

Berechtigungsobjekt

x

Berechtigungen/Einschränkungen des Konnektors

data

Datenaktualisierungsobjekt

 

Regelsatz zum automatischen Setzen bzw. Aktualisieren von Kundendaten bei Aufruf über diesen Konnektor

Berechtigungsobjekt

Feld

Wert

Pflicht

Beschreibung

Feld

Wert

Pflicht

Beschreibung

accountrestrictions

Objekt

x

Zugangsbeschränkungen

accountrestrictions/createaccount

Boolean

 

Konnektor darf neue Accounts anlegen

accountrestrictions/updateaccount

Boolean

 

Konnektor darf bestehende Accounts aktualisieren

accountrestrictions/alloweddomains

String-Array

x

Liste an erlaubten Domains der Account-Email-Adresse.
Der Konnektor darf Aktionen zu allen zugehörigen Accounts durchführen, welche in dieser Liste enthalten sind.
Dabei kann als beliebiger Part (= durch Punkt getrennter Teil der Domain) ein Stern angegeben werden:

"domain.de":
Berechtigung für Accounts: @domain.de
keine Berechtigung für Accounts: @sub.domain.de

"*.domain.de":
Berechtigung für Accounts: @domain.de, @sub.domain.de, @sub2.domain.de
keine Berechtigung für Accounts: @sub2.sub.domain.de

"domain.*":
Berechtigung für Accounts: @domain.de, @domain.at, @domain.xyz
keine Berechtigung für Accounts: @domain.domain2.de, @domain.co.uk

"*": Berechtigung für alle Accounts

accountdata

Objekt

 

Berechtigungen, welche Daten des Kundenkontos der Konnektor setzen darf

accountdata/surchargelimit

Boolean

 

kundenindividuelle Bemessungsgrenze für Mindermengenzuschlag setzen

accountdata/surcharge

Boolean

 

kundenindividuellen Betrag des Mindermengenzuschlags setzen

accountdata/userdiscount

Boolean

 

kundenindividuellen Rabattsatz bzw. Liste setzen

accountdata/mainsubshop

Boolean

 

Hauptsubshop setzen

accountdata/subshoplist

Boolean

 

Subshop-Zugangsberechtigungen setzen

accountdata/customernumber

Boolean

 

Kundennummer setzen

accountdata/allowedpayments

Boolean

 

Liste an erlaubten Zahlungsarten setzen

accountdata/superuserid

Boolean

 

SuperUserID setzen

accountdata/superuseridlist

Boolean

 

SuperUserIDList setzen

accountdata/superuserrestricted

Boolean

 

eingeschränkter SuperUser setzen

accountdata/subvention

Boolean

 

Subventionsbetrag setzen

accountdata/usergroup

Boolean

 

Kundengruppen setzen

accountdata/ordergenerator

Boolean

 

Bestellgenerator erlauben

accountdata/setpassword

Boolean

 

neues Passwort mit automatischem Zwangssetzen eines neuen Passworts bei nächstem Login setzen

accountdata/changeemail

Boolean

 

E-Mailadresse ändern

addressdata

Objekt

 

Berechtigungen, welche Rechnungsadressdatenfelder der Konnektor setzen darf

addressdata/transfer

Boolean

 

Konnektor ist (generell) berechtigt Rechnungsadressdaten zu übergeben

addressdata/ignorechecksoncreate

Boolean

 

Ignoriert alle Adresseingabeprüfungen der Rechnungsadresse, wenn ein neuer Account angelegt und Rechnungsadressdaten übergeben wurden.

ACHTUNG: Wenn dieser Schalter gesetzt wurde können inkonsistente Datensätze entstehen!

addressdata/ignorechecksonupdate

Boolean

 

Ignoriert alle Adresseingabeprüfungen der Rechnungsadresse, wenn ein bestehender Account aktualisiert und Rechnungsadressdaten übergeben wurden.

ACHTUNG: Wenn dieser Schalter gesetzt wurde können inkonsistente Datensätze entstehen!

addressdata/fields

Objekt

 

Berechtigung pro Feld (bzw. Feldgruppe)

addressdata/fields/<id>

Boolean

 

Berechtigung auf Feldebene.
Dabei kann am Ende einer ID ein Stern angegeben werden:

"FirstName": Berechtigung für den Vornamen

"Suffix*": Berechtigung für alle Suffixfelder (Suffix1, Suffix2, ..., Suffix 12, ...)

"*": Alle Felder (ACHTUNG! Dies beinhaltet auch kritische Felder)

return

Objekt

 

Berechtigung welche Daten der Konnektor abfragen darf

return/loginlink

Boolean

 

Berechtigung einen DeepLink inkl. automatischen Login des Kunden in den Shop zurückzugeben

return/loginlinkvalidforseconds

Integer

 

Gültigkeit des Login-Links in Sekunden.
Standard: 300
Max: 3600

Datenaktualisierungsobjekt

Feld

Wert

Pflicht

Beschreibung

Feld

Wert

Pflicht

Beschreibung

preset

Objekt

 

Datenvorbelegung bei Neuanlage eines Kundenkontos über den Konnektor

preset/accountdata

Objekt

 

Datenvorbelegung Kundenkonto (es wird nur ein Teil der Daten des accountdata-Objekts, wie unter REST-API beschrieben, unterstützt)

preset/accountdata/surchargelimit

String

 

kundenindividuelle Bemessungsgrenze für Mindermengenzuschlag

preset/accountdata/surcharge

String

 

kundenindividueller Betrag des Mindermengenzuschlags

preset/accountdata/userdiscount

String

 

kundenindividueller Rabatt (in Prozent)

preset/accountdata/userdiscountlist

String

 

Liste an kundenindividuellen und produktabhängigen Rabattsätzen (siehe Importdatenstruktur)

preset/accountdata/mainsubshop

String

 

HauptsubshopID des Kunden

preset/accountdata/subshoplist

String

 

kommaseparierte Liste an Subshop-Berechtigungen

preset/accountdata/allowedpayments

String

 

kommaseparierte Liste an zugewiesenen Zahlungsartencodes

preset/accountdata/ordergenerator

Boolean

 

Berechtigung den Bestellgenerator zu verwenden

preset/accountdata/usergroup

String

 

kommaseparierte Liste an Kundengruppenindizes

preset/addressdata

Objekt

 

Datenvorbelegung Rechnungsadresse (Datenfelder analog zur Beschreibung wie unter REST-API)

preset/addressdata/fields

Objekt

 

Datenfelder

preset/addressdata/fields/<id>

String

 

Wert

overwrite

Objekt

 

Datenaktualisierung bei Update/Abfrage eines Kundenkontos über den Konnektor

overwrite/accountdata

Objekt

 

Datenaktualisierung Kundenkonto (es wird nur ein Teil der Daten des accountdata-Objekts, wie unter REST-API beschrieben, unterstützt)

overwrite/accountdata/surchargelimit

String

 

kundenindividuelle Bemessungsgrenze für Mindermengenzuschlag

overwrite/accountdata/surcharge

String

 

kundenindividueller Betrag des Mindermengenzuschlags

overwrite/accountdata/userdiscount

String

 

kundenindividueller Rabatt (in Prozent)

overwrite/accountdata/userdiscountlist

String

 

Liste an kundenindividuellen und produktabhängigen Rabattsätzen (siehe Importdatenstruktur)

overwrite/accountdata/mainsubshop

String

 

HauptsubshopID des Kunden

overwrite/accountdata/subshoplist

String

 

kommaseparierte Liste an Subshop-Berechtigungen

overwrite/accountdata/allowedpayments

String

 

kommaseparierte Liste an zugewiesenen Zahlungsartencodes

overwrite/accountdata/ordergenerator

Boolean

 

Berechtigung den Bestellgenerator zu verwenden

overwrite/accountdata/usergroup

String

 

kommaseparierte Liste an Kundengruppenindizes

overwrite/addressdata

Objekt

 

Datenaktualisierung Rechnungsadresse (Datenfelder analog zur Beschreibung wie unter REST-API)

overwrite/addressdata/fields

Objekt

 

Datenfelder

overwrite/addressdata/fields/<id>

String

 

Wert

Beispiel

[ {   "connectorid": "connectorA",   "secret": "sharedSecret",   "description": "Beispielconnector A: Volle Berechtigung",   "permissions":   {     "accountrestrictions":     {       "createaccount": true,       "updateaccount": true,       "alloweddomains":       [ "*", "testshop.de", "testshop.*" ]     },     "accountdata":     {       "userdiscount": false,       "mainsubshop": false,       "subshoplist": false,       "customernumber": false,       "allowedpayments": false,       "superuserid": false,       "ordergenerator": false,       "setpassword": false,       "changeemail": false     },     "addressdata":     {       "transfer": true,       "fields":       {         "id": true,         "suffix*": true       }     },     "return":     {       "loginlink": true     }   },   "data":   {     "preset":     {       "accountdata":       {         "userdiscount": "5",         "mainsubshop": "deutsch",         "subshoplist": "deutsch,englisch",         "allowedpayments": "5,6,7",         "ordergenerator": true       },       "addressdata":       {         "fields":         {           "suffix11": "asdf",           "suffix12": "wert"         }       }     },     "overwrite":     {       "accountdata":       {         "userdiscount": "5",         "mainsubshop": "deutsch",         "subshoplist": "deutsch,englisch",         "allowedpayments": "5,6,7",         "ordergenerator": true       },       "addressdata":       {         "fields":         {           "suffix12": "wert"         }       }     }   } }, {   "connectorid": "connectorB",   "secret": "sharedSecret2",   "description": "Beispielconnector B: nur Login bestehender Kunden von xyz.de. Setzen von 3% wenn über Konnektor kam",   "permissions":   {     "accountrestrictions":     {       "alloweddomains":[ "xyz.de"]     },     "return":     {       "loginlink": true     }   },   "data":   {     "overwrite":     {       "accountdata":       {         "userdiscount": "3"       }     }   } } ]

REST-API

JSON-WebToken (JWT)

Endpoint: /_api/shop/Account

Die REST-API wird mit einer POST-Anfrage an den Endpoint aufgerufen. Als POST-Daten wird ein JSON-WebToken mit entsprechender Payload übergeben:

Header:
Verwendeter Signatur-Algorithmus: HS256
Verwendeter Typ: JWT

Payload:
(siehe Beschreibung unten)

Verify-Signature:
HMACSHA256(base64UrlEncode(header) + "." +  base64UrlEncode(payload), <sharedSecret des Konnektors>)

Beispielanfrage:

Payload: 

{   "hello": "world" }

SharedSecret: geheim

Decoded JWT:

{   "alg": "HS256",   "typ": "JWT" }.{   "hello": "world" }.HMACSHA256(   base64UrlEncode(header) + "." +   base64UrlEncode(payload),geheim )

Encoded JWT (POST-Data):

PayLoad

Feld

Wert

Pflicht

Beschreibung

Feld

Wert

Pflicht

Beschreibung

iss

String

X

ID des Konnektors

exp

NumericDate/String

 

Ablaufdatum

email

String

X*

E-Mail-Adresse des Kundenkontos
E-Mailadresse ODER UserIndex muss angegeben werden

userindex

String

X*

UserIndex des Kundenkontos
E-Mailadresse ODER UserIndex muss angegeben werden

return

Objekt

 

Angabe der angefragten Informationen

return/loginlink

Boolean

 

DeepLink für automatischen Login des Kundenkontos in den Shop anfragen

data

Objekt

 

zu aktualisierende bzw. setzende Daten des Kundenkontos

data/accountdata

Objekt

 

Datenaktualisierung Kundenkonto (es wird nur ein Teil der Daten des accountdata-Objekts, wie unter REST-API beschrieben, unterstützt)

data/accountdata/surchargelimit

String

 

kundenindividuelle Bemessungsgrenze für Mindermengenzuschlag

data/accountdata/surcharge

String

 

kundenindividueller Betrag des Mindermengenzuschlags

data/accountdata/userdiscount

String

 

kundenindividueller Rabatt (in Prozent)

data/accountdata/userdiscountlist

String

 

Liste an kundenindividuellen und produktabhängigen Rabattsätzen (siehe Importdatenstruktur)

data/accountdata/mainsubshop

String

 

HauptsubshopID des Kunden

data/accountdata/subshoplist

String

 

kommaseparierte Liste an Subshop-Berechtigungen

data/accountdata/allowedpayments

String

 

kommaseparierte Liste an Zahlungsartencodes

data/accountdata/customernumber

String

 

Kundennummer

data/accountdata/superuserid

String

 

SuperUserID

data/accountdata/superuseridlist

String

 

SuperUserIDList

data/accountdata/superuserrestricted

Boolean

 

eingeschränkter SuperUser

data/accountdata/usergroup

String

 

kommaseparierte Liste an Kundengruppenindizes

data/accountdata/subvention

String

 

Subvention

data/accountdata/ordergenerator

Boolean

 

Berechtigung zur Verwendung des Bestellgenerators setzen

data/accountdata/setpassword

String

 

neues Passwort (automatischen Zwangssetzen eines neuen Passworts bei nächstem Login wird dabei automatisch gesetzt!)

data/accountdata/changeemail

String

 

neue E-Mailadresse

data/addressdata

Objekt

 

Datenaktualisierung/Setzen Rechnungsadresse

data/addressdata/fields

Objekt

 

Datenfelder

data/addressdata/fields/<id>

String

 

Wert

data/addressdata/fields/TitleCode

String

 

Title-Code wie in title.dat definiert.
Technisches Feld Title wird nicht unterstützt.

data/addressdata/fields/SalutationCode

String

 

Salutation-Code wie in salutation.dat definiert.
Technisches Feld Salutation wird nicht unterstützt.

data/addressdata/fields/CountryCode

String

 

Country-Code wie in country.dat definiert.
Technisches Feld Country wird nicht unterstützt.

PayLoad-Beispiel:

Update des Kundenkontos mit der E-Mailadresse “test@domain.de”. 5% Kundenrabatt und Feld Suffix12 der Rechnungsadresse auf "conA" setzen, LoginLink bei Antwort zurückgeben lassen:

Response

Im Fehlerfall antwortet die Schnittstelle, soweit zutreffend, mit den HTTP-Statuscodes 401/403, ansonsten mit HTTP-Statuscode 400. Zusätzlich wird ein JSON-Objekt zurückgegeben mit entsprechendem Fehlercode und ggf. Fehlermeldung.

Beispiel:

Im Erfolgsfall antwortet die Schnittstelle mit HTTP-Statuscode 200. Zusätzlich wird ein JSON-Objekt zurückgegeben mit Code und einem optionalen return-Objekt welches die angefragten Daten enthält.

Beispiel:

Feld

Wert

Pflicht

Beschreibung

Feld

Wert

Pflicht

Beschreibung

code

String

X

Statuscode der Anfrage.

Code-Liste wird während der Implementierung erstellt.

return

Objekt

 

Rückgabe der angefragten Informationen

return/loginlink

String

 

zeitlich begrenzter DeepLink für automatischen Login

return/accountkey

String

 

zeitlich begrenzter Loginparameter für automatischen Login. Kann an jeden beliebigen Shop-Deeplink als Parameter accountkey mitgegeben werden.

return/UserIndex

String

X*

Userindex des betroffenen Kundenkontos.
Wird bei erfolgreichen Anfragen immer zurückgegeben.