Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt

Use this file to discover all available pages before exploring further.

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

ParameterBeschreibung
account
accountRestrictions
addressFieldsSettings
addressField
autoLogin
bankInfoField
creditCardField
customerAddressField
watchListFieldDefiniert 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": "noreply@websale.de",
      "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

ParameterTypBeschreibung
accountActivationobjectKonfiguration 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.
enabledboolAktiviert (true) bzw. deaktiviert (false) die Bestandskundenregistrierung.
requireOptInboolSteuert, ob nach der Aktivierung eine Opt-In E-Mail an die hinterlegte Adresse versendet wird, die die Registrierung bestätigen muss. Default: true
additionalPasswordCheckLevelslistZusätzliche Prüfungen für Passwörter. Ermöglicht gestaffelte Sicherheitsanforderungen, etwa Mindestlänge oder bestimmte Zeichengruppen (Zahlen, Sonderzeichen).
checksmultiServiceListe von Prüfregeln innerhalb eines Levels; alle enthaltenen Checks müssen erfüllt sein.
servicestringPrüftyp (z. B. dataChecker.minLength, dataChecker.maxLength, dataChecker.digitClass, dataChecker.specialClass).
optionsarrayOptionsobjekt für den jeweiligen Prüftyp. Hier gibt es mehr Informationen zu den Validierungs- und Prüfservices.
passwordChecksarrayBasis-Passwortprüfungen (werden immer angewendet). Aufbau identisch zu additionalPasswordCheckLevels.
servicestringPrü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.
optionsarrayOptionsobjekt für den jeweiligen Prüftyp.
lenintLänge in Zeichen für minLength/maxLength.
minCharsintMinimale Anzahl geforderter Zeichen einer Klasse (z. B. Ziffern/Sonderzeichen).
errorCodesarraySammelobjekt für besondere Fehlerzustände.
passwordResetRequiredstringSchlü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.
loginarrayEinstellungen für Anmelde-Schutzmechanismen.
ipBlockEnabledboolAktiviert (true) / deaktiviert (false) die IP-basierte Sperre.
ipBlockCountintAnzahl fehlgeschlagener Versuche pro IP, bevor die IP gesperrt wird. Default: 10
ipBlockCountDurationintZeitfenster in Minuten, in dem IP-Versuche gezählt werden. Default: 1
ipBlockDurationintSperrdauer der IP in Minuten.
loginBlockCountintAnzahl fehlgeschlagener Logins pro Konto, bevor das Konto gesperrt wird. Default: 5
loginCountDurationintZeitfenster in Minuten, in dem Konto-Versuche gezählt werden. Default: 60
loginBlockDurationintKontosperrdauer in Minuten. Default: 180
loginBlockEmailarrayE-Mail-Benachrichtigung bei Kontosperre.
fromAddressstringAbsenderadresse (E-Mail).
fromNamestringAnzeigename des Absenders.
subjectstringBetreff der E-Mail.
templatestringVorlagenname/Datei (z. B. loginBlocked.htm).
newCustomerRulesarrayRegeln für Neuregistrierungen (derzeit null; vorbereitet für Erweiterungen).
saveCreditCardDataboolSpeicherung von Kreditkartendaten im Konto erlauben (true/false).
subAccountsEnabledboolAktiviert 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

ParameterTypBeschreibung
subshopRestrictionsEnabledboolAktiviert (true) oder deaktiviert (false) die Subshop-Beschränkungen für Kundenkonten.
subshopRestrictionsFallbackenumFallback-Verhalten, wenn keine explizite Zuordnung greift (z. B. leere Liste oder fehlende Kennung). Standard: onlySelf – Konto ist nur im „eigenen/aktuell adressierten” Subshop nutzbar.
subshopRestrictionListlistListe 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

ParameterTypBeschreibung
customLabelsDefinitionlistDefinition bedingungsabhängiger Feldbeschriftungen für Adressfelder.
defaultValuesDefinitionlistDefiniert bedingungsabhängige Standardwerte / Vorbelegungen für Adressfelder.
inputVisibilityDefinitionlistDefiniert die Sichtbarkeit einzelner Adressfelder.
readOnlyFieldslistDefiniert, 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
EigenschaftTypBeschreibung
fieldslistListe der betroffenen Adressfelder (z.B. accounts.addressField.firstName).
addressTypestringAdresstyp, für den die Regel gilt. "bill" = Rechnungsadresse, "delivery" = Lieferadresse.
label / valuestringHier wird zwischen beiden Definitionen unterschieden. customLabelsDefinition (label): die anzuzeigende Beschriftung. defaultValuesDefinition (value): der vorzubelegende Standardwert.
conditionslistListe von Bedingungen, die alle erfüllt sein müssen, damit die Regel greift.
Aufbau einer Condition
EigenschaftTypBeschreibung
fieldstringDas Adressfeld, auf das sich die Bedingung bezieht (z.B. accounts.addressField.country).
typestringArt der Prüfung. value: exakter Vergleichswert oder filled: Feld ist befüllt.
valuestringAbhä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

ParameterTypBeschreibung
labelstringDefinition der Feldbeschriftung.
namestringAnzeigename (in diesem Beispiel des Kunden, in anderen Fällen z.B. der Name der Stadt, in der der Kunde wohnt).
validationsarrayDefiniert die Liste der Validierungsregeln, die auf das jeweilige Adressfeld angewendet werden.
optionsarrayDefiniert die Parameter oder Einstellungen, die eine Validierungsregel benötigt – z. B. Grenzwerte, erlaubte Zeichen oder Bedingungen.
lenintGibt im Beispiel die maximal zulässige Zeichenlänge für die Validierung an.
servicestringBezeichnet 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

ParameterTypBeschreibung
activeboolAktiviert (true) oder deaktiviert (false) die Auto-Login-Funktion insgesamt.
restrictionenumRichtlinie für Auto-Login. Wert notAllowed: Auto-Login ist untersagt (keine dauerhafte Sitzung). Weitere Werte sind systemspezifisch vorbelegt.
expireTimesInDaysobjectSammelobjekt mit Ablaufzeiten (in Tagen) für unterschiedliche Szenarien.
cookieuintGültigkeitsdauer des Auto-Login-Cookies in Tagen. Nach Ablauf ist ein regulärer Login erforderlich. Default: 30
noAutoLoginuintMaximale Inaktivitätsdauer in Tagen ohne Auto-Login; nach Ablauf wird keine automatische Anmeldung mehr versucht. Default: 10
noPasswordLoginuintZeitraum in Tagen, nach dem trotz bestehendem Auto-Login eine Passwort-Eingabe erzwungen wird (z. B. als Re-Auth). Default: 20
errorCodesobjectObjekt für spezielle Fehlerzustände.
actionRequiresLoginstringSchlüssel/Code für den Fall, dass eine Aktion eine erneute Anmeldung erfordert.
actionslistListe 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

ParameterTypBeschreibung
dataIdstringInterne Kennung des Datenfeldes (z. B. „owner”).
labelstringAnzeigename im Kundenkonto, z. B. „Kontoinhaber”.
namestringTechnischer 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

ParameterTypBeschreibung
dataIdstringInterne Kennung des Datenfeldes (z. B. „holder”).
labelstringAnzeigename im Kundenkonto, z. B. „Kreditkarten-Inhaber”.
namestringTechnischer 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

ParameterTypBeschreibung
dataIdstringInterne Kennung oder Referenz-ID des Feldes (z. B. zur Verknüpfung mit externen Systemen oder Datenquellen).
labelstringAnzeigename des Feldes im Frontend (z. B. „Etage” oder „Packstationnummer”).
namestringTechnischer Feldname, der intern für Speicherung und Zuordnung verwendet wird.
validationsarrayOptionales 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

ParameterTypBeschreibung
namestringTechnischer Name des Watchlist-Feldes. Dient zur eindeutigen Identifizierung des Feldes innerhalb der API und interner Prozesse.