Der Endpunkt customerAccounts/ stellt eine REST-Schnittstelle zur Verfügung, über die Kundendaten im Shop-System verwaltet werden können. Die API ermöglicht das Erstellen, Abrufen, Aktualisieren und Löschen von Kundenkonten, Adressen und Bankverbindungen. Zusätzlich lassen sich Daten exportieren oder Passwortrücksetzungen initiieren. Alle Endpunkte sind so gestaltet, dass sie eine systematische Verwaltung und Pflege von Kundendaten über das Admin-Interface hinaus ermöglichen.

Inhaltsverzeichnis

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Kundendaten	customerAccounts/
Adressen	customerAccounts/…/addresses
Bankdaten	customerAccounts/…/bankData

2. Datenfelder

2.1 Datenfelder eines Kundenkontos

Name	Typ	Bedeutung

Name	Typ	Bedeutung
allSubshopsAllowed	Boolean	Gibt an, ob der Kunde für alle Subshops freigeschaltet ist
allowedSubshopIds	String[]	Liste der Subshops, für die der Kunde freigeschaltet ist
createdAt	String	Zeitpunkt der Kontoerstellung (ISO 8601-Format, UTC)
customerNumber	String	Vom System oder extern vergebene Kundennummer
deleted	Boolean	Gibt an, ob das Konto gelöscht wurde
displayName	String	Anzeigename des Kunden (wird z. B. bei Kommentaren oder Bewertungen angezeigt)
email	String	E-Mail-Adresse des Kunden
id	Integer	Interne eindeutige ID des Kunden
loginBlocked	Boolean	Gibt an, ob der Login für dieses Konto gesperrt ist
mainSubshop	String	Haupt-Subshop
meta.currentLogin	String	Zeitpunkt des aktuellen Logins
meta.dataSets.accountBasketId	String	Das zugeordnete Warenkorb-ID des Kundenkontos
meta.dataSets.lastUsedBillAddressId	Integer	ID der zuletzt genutzten Rechnungsadresse
meta.dataSets.lastUsedDeliveryAddressId	Integer	ID der zuletzt genutzten Lieferadresse
meta.dataSets.lastUsedPaymentMethodId	String	ID der zuletzt verwendeten Zahlungsart
meta.dataSets.lastUsedPseudoCCId	String	ID, anhand der Kreditkartendaten zum letzten Mal gefunden wurden
meta.dataSets.lastUsedShippingMethodId	String	ID der zuletzt genutzten Versandart
meta.dataSets.mainAddressId	Integer	ID der Hauptadresse des Kunden
meta.emailVerificationState	Integer	Verifizierungsstatus der E-Mail-Adresse Mögliche Werte: `0` = Unbekannt `1` = Verifiziert durch Double-Opt-In `2` = Nicht verifiziert
meta.lastChangedAt	String	Zeitpunkt der letzten Änderung am Konto
meta.lastChangedBy	String	Quelle der letzten Änderung (z. B. „shop“, "admin")
meta.lastLogin	String	Zeitpunkt des letzten Logins
passwordResetRequired	Boolean	Gibt an, ob der Kunde beim nächsten Login sein Passwort ändern muss
phone	String	Telefonnummer des Kunden

Beispiel:

{
    "addresses": [
        {
			"additionalInfo": "",
			"addressType": "1",
			"businessFax": "",
			"businessPhone": "",
			"city": "asdf",
			"company": "WEBSALE AG",
			...
		}
    ],
    "allSubshopsAllowed": false,
    "allowedSubshopIds": [
        "deutsch"
    ],
    "bankData": [
        {
            "accountNumber": "",
            "bankCode": "",
            "bankName": "myBank",
            "bic": "INGDDEFFXXX",
            "custom": null,
            "iban": "DE746374637463746300",
            ...
        }
    ],
    "createdAt": "2024-09-03T10:09:34.000Z",
    "customerNumber": "",
    "deleted": false,
    "displayName": "",
    "email": "root@root.root",
    "id": 1,
    "loginBlocked": false,
    "mainSubshop": "",
    "meta": {
        "currentLogin": "2025.04.16-12:12:04.899",
        "dataSets": {
            "accountBasketId": "",
            "lastUsedBillAddressId": 108,
            "lastUsedDeliveryAddressId": 108,
            "lastUsedPaymentMethodId": "safepayment",
            "lastUsedPseudoCCId": "",
            "lastUsedShippingMethodId": "hermes",
            "mainAddressId": 108
        },
        "emailVerificationState": 0,
        "lastChangedAt": "1970.01.01-00:00:00.000",
        "lastChangedBy": "shop",
        "lastLogin": "2025.04.16-08:12:31.895"
    },
    "passwordResetRequired": false,
    "phone": ""
}

2.2 Datenfelder einer Adresse

Name	Typ	Bedeutung

Name	Typ	Bedeutung
additionalInfo	String	Zusätzliche Adressinformationen (z. B. Etage, Hausname etc.)
addressType	String	Unbekannt (`"0"`), Rechnungs- und Lieferadresse (`"1"`), Rechnungsadresse (`"2"`), Lieferadresse (`"3"`)
businessFax	String	Geschäftsfax
businessPhone	String	Geschäftstelefon
city	String	Stadt
company	String	Firmenname (sofern vorhanden)
country	String	Ländercode nach ISO 3166-1 alpha-2 (z. B. "DE" für Deutschland)
custom	Objekt	Benutzerdefinierte Felder
dateOfBirth	String	Geburtsdatum
department	String	Abteilung
fax	String	Faxnummer
firstName	String	Vorname
id	Integer	Eindeutige ID der Adresse
lastName	String	Nachname
mobilePhone	String	Mobilnummer
phone	String	Telefonnummer
salutationCode	String	Anrede-Code (z. B. "1" für "Herr", "2" für "Frau")
state	String	Bundesland / Region
street	String	Straßenname
streetNumber	String	Hausnummer
taxId	String	Mehrwertsteuer-ID
titleCode	String	Titel-Code (z. B. "2" für "Dr.")
zip	String	Postleitzahl

Beispiel:

{
	"additionalInfo": "",
	"addressType": "1",
	"businessFax": "",
	"businessPhone": "",
	"city": "asdf",
	"company": "WEBSALE AG",
	"country": "DE",
	"custom": null,
	"dateOfBirth": "14.07.1967",
	"department": "",
	"fax": "",
	"firstName": "asdff",
	"id": 5,
	"lastName": "asdf",
	"mobilePhone": "",
	"phone": "+49123456789",
	"salutationCode": "1",
	"state": "",
	"street": "asdf",
	"streetNumber": "9",
	"taxId": "",
	"titleCode": "2",
	"zip": "99999"
}

2.3 Datenfelder eines Bankkontos

Name	Typ	Bedeutung

Name	Typ	Bedeutung
accountNumber	String	ID des Zahlungskontos (veraltet, meist durch IBAN ersetzt)
bankCode	String	Bankleitzahl (BLZ) des Kreditinstituts
bankName	String	Name der Bank
bic	String	BIC (Business Identifier Code) der Bank für internationale Zahlungen
custom	Objekt	Benutzerdefinierte Felder
iban	String	IBAN (Internationale Bankkontonummer) des Zahlungskontos
id	Integer	Eindeutige ID des Bankdatensatzes
owner	String	Name des Kontoinhabers
sepaDebitType	String	Typ des SEPA-Lastschriftverfahrens (z. B. "CORE", "B2B")
sepaDirectDebitMandate	String	Mandatsreferenznummer für SEPA-Lastschrift
sepaMandateDate	String	Datum der Mandatserteilung (z. B. 2025-01-01)
sepaMandateType	String	Art des SEPA-Mandats (z. B. "Erstmandat", "Folgemandat")

Beispiel:

{
    "accountNumber": "",
    "bankCode": "",
    "bankName": "myBank",
    "bic": "INGDDEFFXXX",
    "custom": null,
    "iban": "DE746374637463746300",
    "id": 1778681,
    "owner": "Max Mustermann",
    "sepaDebitType": "",
    "sepaDirectDebitMandate": "",
    "sepaMandateDate": "",
    "sepaMandateType": ""
}

3. Methoden für Kundendaten

Die hier beschriebenen Methoden ermöglichen das vollständige Verwalten von Kundendaten im System. Dazu zählen das Abrufen, Erstellen, Aktualisieren und Löschen von Kundenkonten sowie das Exportieren von Daten und das Zurücksetzen von Passwörtern. Zusätzlich können Informationen über bereits gelöschte Konten abgerufen werden.

Für jede Operation gelten unterschiedliche Berechtigungen, die sicherstellen, dass nur autorisierte Benutzer auf die jeweiligen Funktionen zugreifen können.

3.1 GET customerAccounts

Mit dieser Methode wird eine paginierte Liste aller Kunden im Shop-System abgerufen. Neben grundlegenden Kundeninformationen wie ID, E-Mail-Adresse und Telefonnummer enthält jede Antwort auch zugehörige Adress- und Bankdaten.

Über optionale Filter- und Sortierparameter lassen sich die Ergebnisse gezielt einschränken und sortieren. Die maximale Anzahl an Ergebnissen pro Anfrage beträgt 300.

Für den Zugriff auf diese Schnittstelle sind Leseberechtigungen für Kundendaten erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/customerAccounts

Antwort:

{
    "endReached": true,
    "items": [
        {
            "addresses": [
                {
                    "city": "asdf",
                    "country": "DE",
                    "firstName": "asdf",
                    "id": 108,
                    "lastName": "asdf",
                    "zip": "99999",
                    ...
                }
            ],
            "allSubshopsAllowed": false,
            "allowedSubshopIds": [
                "deutsch",
                "english"
            ],
            "bankData": [
                {
                    "accountNumber": "",
                    "bankCode": "",
                    "bankName": "foo",
                    "bic": "",
                    "iban": "",
                    "id": 7,
                    "owner": "bar",
                    ...
                }
            ],
            "createdAt": "2024-09-03T10:09:34.000Z",
            "customerNumber": "",
            "deleted": false,
            "email": "root@root.root",
            "id": 1,
            "loginBlocked": false,
            "passwordResetRequired": false,
            "phone": ""
        },
        ...
    ],
    "nextPageToken": "NDA",
    "totalCount": 41
}

Filterfelder:

id, customerNumber, loginBlocked, deleted, createdAt, updatedAt

Sortierfelder:

id, customerNumber, loginBlockedAt, deletedAt, createdAt, updatedAt

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
400 Bad Request	"invalidValue"	`size` ∉ [1;300] `sort` ∉ {"asc", "desc"} `pageToken` ist keine Zahl oder kleiner als 0.
400 Bad Request	"invalidCharacters"	`size` ist keine Ganzzahl. Ein Filterwert ist ungültig.
400 Bad Request	"unknownDataField"	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	"unknownOperation"	Ein Filtertyp ist ungültig.
400 Bad Request	"syntaxError"	`sort` enthält mehr als einen oder keinen ":".

3.2 GET customerAccounts/{accountId}

Diese Methode lädt die vollständigen Daten eines Kundenkontos anhand seiner ID.

Die Antwort enthält neben den Stammdaten wie E-Mail-Adresse, Telefonnummer und Kundennummer auch Zusatzinformationen wie erlaubte Subshops, Bankdaten, Adressen und Metadaten (z. B. letzter Login oder verwendete Zahlungsart).

Zum Zugriff auf diese Methode sind Leseberechtigungen für Kundendaten erforderlich. Wird kein Konto mit der angegebenen ID gefunden, wird ein entsprechender Fehler zurückgegeben.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/customerAccounts/1

Antwort:

{
    "addresses": [
        ...
    "allowedSubshopIds": [
        "deutsch",
        "english"
    ],
    "bankData": [
        ...
    ],
    "createdAt": "2024-09-03T10:09:34.000Z",
    "customerNumber": "",
    "deleted": false,
    "email": "root@root.root",
    "id": 1,
    "loginBlocked": false,
    "meta": {
        "currentLogin": "2024.12.19-10:43:01.435",
        "dataSets": {
            "accountBasketId": "",
            "lastUsedBillAddressId": 108,
            "lastUsedDeliveryAddressId": 108,
            "lastUsedPaymentMethodId": "prepayment",
            "lastUsedPseudoCCId": "",
            "lastUsedShippingMethodId": "dhl",
            "mainAddressId": 108
        },
        "emailVerificationState": 0,
        "lastLogin": "2024.12.18-20:56:30.823"
    },
    "passwordResetRequired": false,
    "phone": ""
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.
404 Not Found		Das Konto mit `id`=`{accountId}` wurde nicht gefunden.

3.3 GET customerDataDeleted

Diese Methode liefert eine Liste von Kundendatensätzen, die als gelöscht markiert wurden. Jeder Eintrag enthält die ID des Kontos, den Zeitpunkt der Löschung (deletedAt) sowie einen Typenwert, der die Art der gelöschten Daten beschreibt.

Filter- und Sortierparameter stehen zur Verfügung, um die Ergebnismenge gezielt einzuschränken. Leseberechtigungen für Kundendaten sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/customerDataDeleted

Antwort:

{
    "endReached": true,
    "items": [
        {
            "deletedAt": "2024-10-02T11:22:41.000Z",
            "id": 4,
            "type": 0
        },
        ...
    ],
    "nextPageToken": "NDA",
    "totalCount": 41
}

Filterfelder:

id, type, deletedAt

Sortierfelder:

id, type, deletedAt

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kundendaten.

API-Referenz Kundendaten

Inhaltsverzeichnis

1. Unterstützte Methoden

2. Datenfelder

2.1 Datenfelder eines Kundenkontos

Beispiel:

2.2 Datenfelder einer Adresse

Beispiel:

2.3 Datenfelder eines Bankkontos

Beispiel:

3. Methoden für Kundendaten

3.1 GET customerAccounts

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET customerAccounts/{accountId}

Beispiel:

Antwort:

Fehlercodes:

3.3 GET customerDataDeleted

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes: