Ü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	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.