accounts - Benutzerkonten

Der Konfigurationsknoten accounts umfasst alle Einstellungen rund um die Verwaltung von Benutzerkonten im Onlineshop.

Er definiert, wie sich Kundinnen und Kunden registrieren, anmelden, eingeloggt bleiben und welche Daten sie im Kundenkonto einsehen oder bearbeiten können. Darüber hinaus enthält er sicherheitsrelevante Parameter wie Passwortprüfungen, Login-Sperren, Auto-Login-Regeln sowie die Verwaltung von Zahlungs- und Adressdaten.

Über diese Konfiguration lässt sich das Verhalten des Kundenkontos individuell an die Anforderungen des Shops anpassen – von der einfachen Anmeldung bis zur detaillierten Steuerung von Berechtigungen und Datenfeldern.

---

accounts* - Grundstruktur

Nachfolgend der Grundaufbau des Knotens accounts:

{
    "accounts": {
      "account": {...},
      "accountRestrictions": {...},
      "addressFieldsSettings":{...},
      "addressField":{...},
      "autoLogin": {...},
      "bankInfoField": {...},
      "creditCardField": {...},
      "customAddressField": {...},
      "watchListField": {...}
    }
}

Parameterbeschreibungen

Parameter	Beschreibung
account
accountRestrictions
addressFieldsSettings
addressField
autoLogin
bankInfoField
creditCardField
customerAddressField
watchListField	Definiert Felder der Merk- bzw. Beobachtungsliste mit eindeutiger ID und Namen. Diese Felder sind ausschließlich über die API ansprechbar und besitzen keine Konfigurationsmöglichkeit im Admin Interface.

---

accounts.account - Benutzerkonto

Steuert die zentralen Kontoeinstellungen für Kundinnen und Kunden. Hier werden Sicherheitsprüfungen, Passwortregeln, Login-Schutzmechanismen und weitere Kontofunktionen festgelegt.

Die Konfiguration beeinflusst das Verhalten beim Anlegen, Anmelden und Verwalten von Kundenkonten im Shop.

Die Einstellungen zu diesem Abschnitt befinden sich im Admin Interface unter .

Beispielkonfiguration für alle Subshops (accounts.account)

{
  "accountActivation": {
    "enabled": true,
    "requireOptIn": true
  },
  "additionalPasswordCheckLevels": [
    {
      "checks": [
        {
          "options": { "len": 8 },
          "service": "dataChecker.minLength"
        }
      ]
    },
    {
      "checks": [
        {
          "options": { "minChars": 1 },
          "service": "dataChecker.digitClass"
        },
        {
          "options": { "minChars": 1 },
          "service": "dataChecker.specialClass"
        }
      ]
    }
  ],
  "errorCodes": {
    "passwordResetRequired": ""
  },
  "login": {
    "ipBlockCount": 3,
    "ipBlockCountDuration": 1,
    "ipBlockDuration": 10,
    "ipBlockEnabled": true,
    "loginBlockCount": 5,
    "loginBlockDuration": 180,
    "loginBlockEmail": {
      "fromAddress": "[e-mail]",
      "fromName": "Mein Onlineshop",
      "subject": "Mein Onlineshop | Ihr Login wurde gesperrt",
      "template": "loginBlocked.htm"
    },
    "loginCountDuration": 60
  },
  "newCustomerRules": null,
  "passwordChecks": [
    {
      "options": { "len": 64 },
      "service": "dataChecker.maxLength"
    }
  ],
  "saveCreditCardData": false,
  "subAccountsEnabled": false
}

Parameterbeschreibungen

Parameter	Typ	Beschreibung
accountActivation	object	Konfiguration für die Bestandskundenregistrierung. Ermöglicht die Aktivierung eines bereits im Shop angelegten Kundendatensatzes (z.B. per Import) über die Aktion AccountActivate. Das Konto gilt als noch nicht aktiviert, wenn: noch kein Passwort gesetzt ist, dem Account keine Mitarbeiterkonten zugeordnet sind oder bisher kein Einladungslink versendet wurde. Aus Sicherheitsgründen kann die Aktivierung nur einmal durchgeführt werden. Welche Felder bei der Bestandskundenregistrierung abgefragt werden, wird hierüber gesteuert.
enabled	bool	Aktiviert (true) bzw. deaktiviert (false) die Bestandskundenregistrierung.
requireOptIn	bool	Steuert, ob nach der Aktivierung eine Opt-In E-Mail an die hinterlegte Adresse versendet wird, die die Registrierung bestätigen muss. Default: true
additionalPasswordCheckLevels	list	Zusätzliche Prüfungen für Passwörter. Ermöglicht gestaffelte Sicherheitsanforderungen, etwa Mindestlänge oder bestimmte Zeichengruppen (Zahlen, Sonderzeichen).
checks	multiService	Liste von Prüfregeln innerhalb eines Levels; alle enthaltenen Checks müssen erfüllt sein.
service	string	Prüftyp (z. B. dataChecker.minLength, dataChecker.maxLength, dataChecker.digitClass, dataChecker.specialClass).
options	array	Optionsobjekt für den jeweiligen Prüftyp. Hier gibt es mehr Informationen zu den Validierungs- und Prüfservices.
passwordChecks	array	Basis-Passwortprüfungen (werden immer angewendet). Aufbau identisch zu additionalPasswordCheckLevels.
service	string	Prüftyp (z. B. addressCheck.minLength, dataChecker.minLength für Prüfung einer Mindestangabe, addressCheck.maxLength, dataChecker.maxLength für Prüfung maximaler Zeichenangabe etc.). Übersicht der verfügbaren Validierungs- und Prüfregeln für Adressdatenfelder finden Sie hier.
options	array	Optionsobjekt für den jeweiligen Prüftyp.
len	int	Länge in Zeichen für minLength/maxLength.
minChars	int	Minimale Anzahl geforderter Zeichen einer Klasse (z. B. Ziffern/Sonderzeichen).
errorCodes	array	Sammelobjekt für besondere Fehlerzustände.
passwordResetRequired	string	Schlüssel/Code, der ausgegeben wird, wenn für das Benutzerkonto eine Passwortzurücksetzung erforderlich ist (z. B. nach einem administrativen Reset oder aus Sicherheitsgründen). Optional kann eine Meldung hinterlegt werden – entweder als Klartext oder als Verweis auf einen Textbaustein/Key.
login	array	Einstellungen für Anmelde-Schutzmechanismen.
ipBlockEnabled	bool	Aktiviert (true) / deaktiviert (false) die IP-basierte Sperre.
ipBlockCount	int	Anzahl fehlgeschlagener Versuche pro IP, bevor die IP gesperrt wird. Default: 10
ipBlockCountDuration	int	Zeitfenster in Minuten, in dem IP-Versuche gezählt werden. Default: 1
ipBlockDuration	int	Sperrdauer der IP in Minuten.
loginBlockCount	int	Anzahl fehlgeschlagener Logins pro Konto, bevor das Konto gesperrt wird. Default: 5
loginCountDuration	int	Zeitfenster in Minuten, in dem Konto-Versuche gezählt werden. Default: 60
loginBlockDuration	int	Kontosperrdauer in Minuten. Default: 180
loginBlockEmail	array	E-Mail-Benachrichtigung bei Kontosperre.
fromAddress	string	Absenderadresse (E-Mail).
fromName	string	Anzeigename des Absenders.
subject	string	Betreff der E-Mail.
template	string	Vorlagenname/Datei (z. B. loginBlocked.htm).
newCustomerRules	array	Regeln für Neuregistrierungen (derzeit null; vorbereitet für Erweiterungen).
saveCreditCardData	bool	Speicherung von Kreditkartendaten im Konto erlauben (true/false).
subAccountsEnabled	bool	Aktiviert oder deaktiviert (true/false) die Mitarbeiterkontenfunktion. Ist die Funktion aktiv, können für jedes übergeordnete Konto individuelle Mitarbeiterkonten angelegt werden. Sobald diese Funktion aktiviert ist, ist eine direkte Anmeldung am übergeordneten Konto nicht mehr möglich. Daher sollte die Aktivierung ausschließlich in einem neu eingerichteten Shop erfolgen – eine nachträgliche Aktivierung führt dazu, dass sich bestehende Nutzer nicht mehr anmelden können.

---

accounts.accountRestrictions - Subshopbeschränkungen für Benutzerkonten

Begrenzt die Verfügbarkeit von Kundenkonten auf definierte Subshops, z.B. B2B-Konten nur für einen Länder-Shop freigeben, exklusive Bereiche je Mandant oder Region.

Die Einstellungen zu diesem Abschnitt befinden sich im Admin Interface unter .

Beispielkonfiguration für alle Subshops (accounts.accountRestrictions)

{
  "subshopRestrictionList": [],
  "subshopRestrictionsEnabled": false,
  "subshopRestrictionsFallback": "onlySelf"
}

Parameterbeschreibungen

Parameter	Typ	Beschreibung
subshopRestrictionsEnabled	bool	Aktiviert (true) oder deaktiviert (false) die Subshop-Beschränkungen für Kundenkonten.
subshopRestrictionsFallback	enum	Fallback-Verhalten, wenn keine explizite Zuordnung greift (z. B. leere Liste oder fehlende Kennung). Standard: onlySelf – Konto ist nur im „eigenen/aktuell adressierten” Subshop nutzbar.
subshopRestrictionList	list	Liste der zulässigen Subshops (Allowlist) für das Konto. Einträge müssen den in Ihrer Umgebung verwendeten Subshop-Kennungen entsprechen (z. B. den Schlüsseln in der Subshop-Konfiguration). Ist die Liste leer, greift das Verhalten gemäß subshopRestrictionsFallback.

---

accounts.addressFieldsSettings - Individuelle Adressfelder-Einstellungen

Steuert die zentralen Konfigurationen für Adressfelder im Shop. Hier werden individuelle Beschriftungen, Standardwerte, Sichtbarkeiten und Schreibschutzregeln für Rechnungs- und Lieferadressen festgelegt.

Die Einstellungen zu diesem Abschnitt befinden sich im Admin Interface unter .

Beispielkonfiguration für alle Subshops (accounts.addressFieldsSettings)

{
  "customLabelsDefinition": [],
  "defaultValuesDefinition": [],
  "inputVisibilityDefinition": null,
  "readOnlyFields": null
}

Parameterübersicht

Parameter	Typ	Beschreibung
customLabelsDefinition	list	Definition bedingungsabhängiger Feldbeschriftungen für Adressfelder.
defaultValuesDefinition	list	Definiert bedingungsabhängige Standardwerte / Vorbelegungen für Adressfelder.
inputVisibilityDefinition	list	Definiert die Sichtbarkeit einzelner Adressfelder.
readOnlyFields	list	Definiert, welche Adressfelder nur sichtbar und nicht bearbeitbar sind.

Bedingungsabhängige Definitionen (customLabelsDefinition & defaultValuesDefinition)

Die Definitionen defaultValuesDefinition und customLabelsDefinition ermöglichen es, Standardwerte und benutzerdefinierte Feldbezeichnungen für Adressfelder abhängig von bestimmten Bedingungen zu definieren.

Beide Definitionen folgen derselben Struktur und unterstützen ein conditions-Array, mit dem die Anwendung der jeweiligen Regel an Feldbedingungen geknüpft werden kann.

Aufbau eines Eintrags

Eigenschaft	Typ	Beschreibung
fields	list	Liste der betroffenen Adressfelder (z.B. accounts.addressField.firstName).
addressType	string	Adresstyp, für den die Regel gilt. "bill" = Rechnungsadresse, "delivery" = Lieferadresse.
label / value	string	Hier wird zwischen beiden Definitionen unterschieden. customLabelsDefinition (label): die anzuzeigende Beschriftung. defaultValuesDefinition (value): der vorzubelegende Standardwert.
conditions	list	Liste von Bedingungen, die alle erfüllt sein müssen, damit die Regel greift.

Aufbau einer Condition

Eigenschaft	Typ	Beschreibung
field	string	Das Adressfeld, auf das sich die Bedingung bezieht (z.B. accounts.addressField.country).
type	string	Art der Prüfung. value: exakter Vergleichswert oder filled: Feld ist befüllt.
value	string	Abhängig davon, was bei type definiert wurde. Bei "value": der erwartete Wert (z.B. "DE"). Bei "filled": ein leerer String ("").

Beispiel für customLabelsDefinition

Benutzerdefinierte Feldbeschriftungen, die abhängig von Bedingungen angezeigt werden.

{
  "customLabelsDefinition": [
    {
      "fields": ["accounts.addressField.firstName"],
      "addressType": "bill",
      "label": "Vorname (Rechnung)",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "value",
          "value": "DE"
        }
      ]
    },
    {
      "fields": ["accounts.addressField.firma"],
      "addressType": "delivery",
      "label": "Firma (Lieferung)",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "filled",
          "value": ""
        }
      ]
    }
  ]
}

Erklärung

Im ersten Eintrag wird das Feld accounts.addressField.firstName in der Rechnungsadresse mit dem Label „Vorname (Rechnung)” beschriftet – jedoch nur, wenn das Land auf DE gesetzt ist. Im zweiten Eintrag erhält das Feld accounts.addressField.firma in der Lieferadresse das Label „Firma (Lieferung)”, sobald das Feld accounts.addressField.country einen beliebigen Wert enthält (type: "filled").

Beispiel für defaultValuesDefinition

Standardwerte für Adressfelder, die ebenfalls bedingungsabhängig vorbefüllt werden.

{
  "defaultValuesDefinition": [
    {
      "fields": ["accounts.addressField.country"],
      "addressType": "bill",
      "value": "DE",
      "conditions": []
    },
    {
      "fields": ["accounts.addressField.salutation"],
      "addressType": "delivery",
      "value": "Herr",
      "conditions": [
        {
          "field": "accounts.addressField.country",
          "type": "value",
          "value": "DE"
        }
      ]
    }
  ]
}

Erklärung

Im ersten Eintrag wird das Feld accounts.addressField.country in der Rechnungsadresse bedingungslos mit "DE" vorbelegt. Im zweiten Eintrag wird die Anrede der Lieferadresse (accounts.addressField.salutation) nur dann auf "Herr" gesetzt, wenn das Land DE ist.

---

accounts.addressField - Einzelne Adressfelder definieren

Steuert die Struktur und Eigenschaften einzelner Adressfelder im Shop. Über Validierungen können Eingaben überprüft und formale Anforderungen (z. B. Pflichtfelder, Formatprüfungen) festgelegt werden.

Die Einstellungen zu diesem Abschnitt befinden sich im Admin Interface unter .

Beispielkonfiguration für alle Subshops (accounts.addressField.firstName)

{
  "label": "",
  "name": "firstName",
  "validations": [
    {
      "options": {
        "len": 255
      },
      "service": "addressCheck.maxLength"
    }
  ]
}

Parameterübersicht

Parameter	Typ	Beschreibung
label	string	Definition der Feldbeschriftung.
name	string	Anzeigename (in diesem Beispiel des Kunden, in anderen Fällen z.B. der Name der Stadt, in der der Kunde wohnt).
validations	array	Definiert die Liste der Validierungsregeln, die auf das jeweilige Adressfeld angewendet werden.
options	array	Definiert die Parameter oder Einstellungen, die eine Validierungsregel benötigt – z. B. Grenzwerte, erlaubte Zeichen oder Bedingungen.
len	int	Gibt im Beispiel die maximal zulässige Zeichenlänge für die Validierung an.
service	string	Bezeichnet den verwendeten Validierungsdienst, der die eigentliche Prüfung durchführt – hier z. B. addressCheck.maxLength zur Kontrolle der maximalen Feldlänge.

---

accounts.autoLogin - Angemeldet bleiben

Steuert das „Angemeldet bleiben”-Verhalten (Auto-Login) für Kundenkonten: Aktivierung, Ablaufzeiten und Reaktionen auf Sonderfälle.

Die Einstellungen zu diesem Abschnitt befinden sich im Admin Interface unter .

Beispielkonfiguration für alle Subshops (accounts.autoLogin)

{
  "actions": null,
  "active": true,
  "errorCodes": {
    "actionRequiresLogin": ""
  },
  "expireTimesInDays": {
    "cookie": 30,
    "noAutoLogin": 10,
    "noPasswordLogin": 20
  },
  "restriction": "notAllowed"
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
active	bool	Aktiviert (true) oder deaktiviert (false) die Auto-Login-Funktion insgesamt.
restriction	enum	Richtlinie für Auto-Login. Wert notAllowed: Auto-Login ist untersagt (keine dauerhafte Sitzung). Weitere Werte sind systemspezifisch vorbelegt.
expireTimesInDays	object	Sammelobjekt mit Ablaufzeiten (in Tagen) für unterschiedliche Szenarien.
cookie	uint	Gültigkeitsdauer des Auto-Login-Cookies in Tagen. Nach Ablauf ist ein regulärer Login erforderlich. Default: 30
noAutoLogin	uint	Maximale Inaktivitätsdauer in Tagen ohne Auto-Login; nach Ablauf wird keine automatische Anmeldung mehr versucht. Default: 10
noPasswordLogin	uint	Zeitraum in Tagen, nach dem trotz bestehendem Auto-Login eine Passwort-Eingabe erzwungen wird (z. B. als Re-Auth). Default: 20
errorCodes	object	Objekt für spezielle Fehlerzustände.
actionRequiresLogin	string	Schlüssel/Code für den Fall, dass eine Aktion eine erneute Anmeldung erfordert.
actions	list	Liste der Aktionen, die während eines automatischen Logins ohne erneute Passwortabfrage erlaubt sind. Damit lässt sich gezielt festlegen, was Kunden im angemeldeten Zustand nutzen dürfen, ohne sich erneut anzumelden. Beispielsweise kann so der Zugriff auf unkritische Funktionen wie die Merkliste erlaubt werden, während sicherheitsrelevante Aktionen (z. B. Warenkorb- oder Bestellvorgänge) weiterhin eine erneute Anmeldung erfordern. Beispiele für erlaubte Aktionen: WatchListAdd → neue Merkliste anlegen, WatchListDelete → Merkliste löschen, WatchListItemAdd → Produkte auf eine Merkliste legen, WatchListItemDelete → Produkte von einer Merkliste löschen. Wenn keine Aktionen erlaubt werden sollen, muss der Wert auf null gesetzt werden. In diesem Fall sind alle Aktionen automatisch gesperrt, und für jede Interaktion ist eine erneute Anmeldung erforderlich.

---

accounts.bankInfoField - Bankdaten

Ermöglicht die Erfassung und Verwaltung von Bankdaten im Kundenkonto. Im Gegensatz zu Kreditkartendaten können diese Informationen direkt im Shop eingegeben, geändert und gespeichert werden.

Die gespeicherten Bankverbindungen stehen anschließend im Bestellprozess – insbesondere bei der Zahlart SEPA-Lastschrift – zur Auswahl.

Beispielkonfiguration für alle Subshops (accounts.bankInfoField.owner)

{
  "dataId": "owner",
  "label": "Kontoinhaber",
  "name": "owner"
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
dataId	string	Interne Kennung des Datenfeldes (z. B. „owner”).
label	string	Anzeigename im Kundenkonto, z. B. „Kontoinhaber”.
name	string	Technischer Feldname. Wird vom System vorgegeben und sollte nicht verändert werden. Folgende name stehen zur Verfügung: accountNumber - Kontonummer der Kundin bzw. des Kunden (in der Regel nur bei älteren Konten ohne IBAN relevant), bankCode - Bankleitzahl (nur relevant, wenn keine IBAN verwendet wird), bankName - Name der Bank, bic - BIC (Business Identifier Code) der Bank, iban - IBAN (International Bank Account Number) der Kontoinhaberin bzw. des Kontoinhabers, owner - Name der Kontoinhaberin bzw. des Kontoinhabers, sepaDebitType - Art der SEPA-Lastschrift (z. B. CORE oder B2B), sepaDirectDebitMandate - Mandatsreferenznummer der SEPA-Lastschrift, sepaMandateDate - Datum der Mandatserteilung (ISO-Format empfohlen: YYYY-MM-DD), sepaMandateType - Typ des SEPA-Mandats (z. B. Erstmandat oder Folgemandat).

---

accounts.creditCardField - Kreditkarten

Die Bezahlung mit Kreditkarte wird aus Sicherheitsgründen ausschließlich über externe Payment-Service-Provider (PSP) abgewickelt.

Die Eingabe der Kreditkartendaten, die Erkennung des Kartentyps sowie die Durchführung des 3D Secure 2.0-Verfahrens erfolgen vollständig beim Payment-Provider. Reale Kreditkartendaten werden niemals im Onlineshop gespeichert oder verarbeitet.

Im Kundenkonto können – sofern vom PSP unterstützt und vertraglich freigeschaltet – pseudonymisierte Kreditkarteninformationen angezeigt werden. Dadurch können Kunden beim nächsten Einkauf bequem eine gespeicherte Karte auswählen, ohne die Daten erneut eingeben zu müssen. Eine direkte Eingabe oder Änderung von Kreditkartendaten im Shop ist dabei nicht möglich.

Beispielkonfiguration für alle Subshops (accounts.creditCardField.holder)

{
  "dataId": "holder",
  "label": "Kreditkarten-Inhaber",
  "name": "holder"
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
dataId	string	Interne Kennung des Datenfeldes (z. B. „holder”).
label	string	Anzeigename im Kundenkonto, z. B. „Kreditkarten-Inhaber”.
name	string	Technischer Feldname. Wird vom System vorgegeben und sollte nicht verändert werden. Folgende name stehen zur Verfügung: cvCode - Sicherheitscode (3 oder 4 Stellen, je nach Kartentyp), expireMonth - Ablaufmonat der Karte, expireYear - Ablaufjahr der Karte, holder - Karteninhaberin bzw. Karteninhaber, number - Kartennummer (pseudonymisiert), type - Kartentyp (z. B. Visa, MasterCard, American Express).

---

accounts.customAddressField - Weitere Adressdatenfelder

Ermöglicht die Definition zusätzlicher Adressfelder für Rechnungs- und/oder Lieferadressen.

Diese Felder ergänzen die Standardangaben (z. B. Name, Straße, PLZ, Ort, Land, Telefon) um individuelle Eingabefelder, die im Kundenkonto oder im Checkout angezeigt und gespeichert werden. Beispiele für typische Zusatzfelder sind: Adresszusatz, Etage, Postfach, Packstationnummer oder Abteilung.

Beispielkonfiguration für alle Subshops (accounts.customAddressField.postOfficeBox)

{
  "dataId": "customField.postfach",
  "label": "Postfach",
  "name": "postfach",
  "validations": [
    {
      "options": {
        "len": 3
      },
      "service": "addressCheck.minLength"
    },
    {
      "options": {
        "len": 20
      },
      "service": "addressCheck.maxLength"
    },
    { 
      "options": {
        "signs": "^[0-9A-Za-z\\s-]+$"
      },
      "service": "addressCheck.legalSigns" 
    }   
  ]
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
dataId	string	Interne Kennung oder Referenz-ID des Feldes (z. B. zur Verknüpfung mit externen Systemen oder Datenquellen).
label	string	Anzeigename des Feldes im Frontend (z. B. „Etage” oder „Packstationnummer”).
name	string	Technischer Feldname, der intern für Speicherung und Zuordnung verwendet wird.
validations	array	Optionales Validierungsobjekt zur Prüfung der Eingabe (z. B. Pflichtfeld, maximale Länge, bestimmte Zeichenformate). Kann null sein, wenn keine Validierung erforderlich ist. Übersicht der verfügbaren Validierungs- und Prüfregeln für Adressdatenfelder finden Sie hier.

---

accounts.watchListField - Merkliste

Definiert Felder der Merk- bzw. Beobachtungsliste mit eindeutiger ID und Namen.

Diese Felder sind ausschließlich über die API ansprechbar und besitzen keine Konfigurationsmöglichkeit im Admin Interface.

Beispielkonfiguration für alle Subshops (accounts.watchListField)

{
  "name": "watchListIds"
}

Parameterbeschreibung

Parameter	Typ	Beschreibung
name	string	Technischer Name des Watchlist-Feldes. Dient zur eindeutigen Identifizierung des Feldes innerhalb der API und interner Prozesse.