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 |
---|---|---|---|
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 |
---|---|---|---|
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. "domain.de": "*.domain.de": "domain.*": "*": 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. "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. |
Datenaktualisierungsobjekt
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 |
---|---|---|---|
iss | String | X | ID des Konnektors |
exp | NumericDate/String |
| Ablaufdatum |
String | X* | E-Mail-Adresse des Kundenkontos | |
userindex | String | X* | UserIndex des Kundenkontos |
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. |
data/addressdata/fields/SalutationCode | String |
| Salutation-Code wie in salutation.dat definiert. |
data/addressdata/fields/CountryCode | String |
| Country-Code wie in country.dat definiert. |
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 |
---|---|---|---|
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. |