API-Referenz Konfiguration - WEBSALE Dokumentation

Die Schnittstelle für den Endpunkt config/ ermöglicht den umfassenden Zugriff auf die Shopkonfiguration. Über die REST API lassen sich Konfigurationsdaten abrufen, ändern, löschen oder neu anlegen. Dies umfasst sowohl globale Einstellungen als auch subshopspezifische Überschreibungen. Die Konfiguration basiert auf vordefinierten Schemas, die bestimmen, welche Daten zulässig sind. Änderungen an Konfigurationsknoten werden serverseitig auf Gültigkeit geprüft. Die REST API erlaubt damit die vollständige Verwaltung der Shopkonfiguration – wie sie auch über das Admin-Interface vorgenommen wird.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Einstellungen	config/
Knoten im Shop
	Knoten in Subshops

Struktur & Anwendung der Konfiguration über die API

Die Shopkonfiguration ist als gerichteter Graph organisiert. Jeder Knoten in diesem Graphen repräsentiert einen eigenständigen Konfigurationsbereich und kann andere Knoten referenzieren – beispielsweise um eine Sprache oder ein Land anzugeben. Jeder Konfigurationsknoten hat einen klar definierten Typ, für den ein Schema festlegt, welche Datenfelder erlaubt sind, welche Datentypen sie haben und, ob ein Knoten pro Subshop überschrieben werden darf oder nur einmalig existieren kann. Die Schemata beschreiben damit die Struktur der Konfigurationsdaten, nicht jedoch deren Inhalt. Die Konfiguration kann vollständig über die REST-API gepflegt werden. Das Admin Interface (AI) ist zusätzlich eine visuelle Darstellung dieser Schnittstelle. Alle Funktionen, die im Interface ausgeführt werden können, stehen auch über die API zur Verfügung – etwa das Erstellen, Anpassen, Löschen oder Überschreiben von Konfigurationsknoten. Damit eignet sich die API besonders für eine automatisierte Verwaltung der Konfiguration, etwa im Rahmen von:

CI/CD-Prozessen mit klar definierten Konfigurationszuständen,
dem Abgleich von Einstellungen zwischen Test- und Produktivsystemen,
oder der Verwaltung mandantenfähiger Umgebungen mit subshop-spezifischen Varianten.

Die REST-API bietet somit vollständigen Zugriff auf die Konfiguration ihres Shops. Um die Felder eines Knotens zu ermitteln, muss das zugehörige Schema über den Endpunkt GET config/schemas/{type} geladen werden. Die Struktur dieser Schemata wird im Feld properties beschrieben. Dort sind unter anderem die Felder id, type und optional subtype (z. B. bei type: list) enthalten. id legt fest, wie das Feld heißt, während type und subtype angeben, welche Inhalte erwartet werden. type: object kennzeichnet eine verschachtelte Struktur. Welche Konfigurationstypen im System verfügbar sind, lässt sich auf zwei Wegen abfragen:

über GET config/nodeTypes, das eine kompakte Liste aller Typen liefert,
oder alternativ über GET config/schemas, wo zusätzlich das Feld id enthalten ist.

Gültige `{type}`- und `{selector}`-Werte

Die folgenden Tabellen listen die gültigen Werte auf, die bei

GET /api/config/schemas/{type} als {type} und
GET /api/config/nodes/{selector} als Top-Level-{selector}

verwendet werden können. Die Unterknoten, Parameter und Beispiele der einzelnen Bereiche sind nicht Teil dieser API-Referenz. Sie sind vollständig im Dokument Konfiguration beschrieben. Dieser Abschnitt dient ausschließlich als Orientierungs für die gültigen Bezeichner.

Typ / Selector	Kurzbeschreibung
`accounts`	→ accounts - Benutzerkonten
`actions`	→ actions - Fehlertexte & E-Mails
`app`	→ app - WEBSALE APP
`authentication`	→ authentication - Authentifizierungs- & Zugriffsdaten
`b2b`	→ b2b - Business-to-Business (B2B)
`basket`	→ basket - Warenkorb
`checkout`	→ checkout - Bestellablauf
`content`	→ content - Katalog (Kategorien & Produkte)
`creditCheck`	→ creditCheck - Bonitätsprüfung(old)
`customer`	→ customer - Kundendaten
`finance`	→ finance - Währungen & Steuern
`general`	→ general - Allgemeine Shopeinstellungen
`inquiry`	→ inquiry - Formulare
`maintenance`	→ maintenance - Wartungsmodus
`messages`	→ messages - Ereignisgesteuerte E-Mails
`newsletter`	→ newsletter - Newsletter
`payment`	→ payment - Zahlungsarten
`search`	→ search - Suche (Core)
`security`	→ security - Sicherheit
`seoMetaData`	→ seoMetaData - Meta-Daten & Seo-Texte
`shopSystemServices`	→ shopSystemServices - Zusatzmodule
`urls`	→ urls - URL (Webadressen)

Methoden für Einstellungen

Dieser Abschnitt beschreibt die verfügbaren REST-Endpunkte zur Verwaltung der Shop-Konfiguration im Admin-Bereich. Über die Schnittstelle können Schemas abgerufen, Konfigurationsknoten analysiert, geprüft, gelöscht oder vollständig zurückgesetzt werden. Die Konfiguration ist dabei in sogenannte Schemas und Knoten unterteilt, die verschiedenen Bereichen wie Accounts, Aktionen oder Systemfunktionen zugeordnet sind. Alle Einstellungen gelten entweder global oder subshopspezifisch und können je nach Schema typabhängig angepasst werden. Die Nutzung der Methoden setzt entsprechende Lese-, Schreib- oder Löschrechte voraus.

GET config/setup

Mit diesem Endpunkt wird die Setup-Konfiguration pro Subshop und Stage (z. B. work, active) abgerufen. Die Rückgabe enthält technische Informationen wie die host-, staticDomain- und contentDomain-Werte, die zur Laufzeitkonfiguration und Auslieferung der Inhalte im jeweiligen Subshop benötigt werden. Dieser Endpunkt dient primär der systeminternen oder administrativen Analyse des aktuellen Shop-Setups.

Beispiel

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

Antwort

[
    {
        "contentDomain": "content.myshop.localhost",
        "host": "myshop.localhost",
        "id": "deutsch",
        "stage": "work",
        "staticDomain": "static.myshop.localhost",
        "staticUrl": "/static"
    },
    {
        "contentDomain": "content.myshop.localhost",
        "host": "myshop.localhost",
        "id": "deutsch",
        "stage": "active",
        "staticDomain": "static.myshop.localhost",
        "staticUrl": "/static"
    },
    {
        "contentDomain": "content.myshop.localhost",
        "host": "english.localhost",
        "id": "english",
        "stage": "work",
        "staticDomain": "static.myshop.localhost",
        "staticUrl": "/static"
    },
    {
        "contentDomain": "content.myshop.localhost",
        "host": "english.localhost",
        "id": "english",
        "stage": "active",
        "staticDomain": "static.myshop.localhost",
        "staticUrl": "/static"
    }
]

Fehlercodes

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

GET config/status

Dieser Endpunkt prüft die Konfigurationsdaten auf Unvollständigkeit und Redundanz. Er meldet, ob Pflichtfelder fehlen oder Knoten mit identischen Daten mehrfach vorhanden sind.
Wird kein Problem erkannt, wird "status": "ok" zurückgegeben. Die Nutzung erfordert Leseberechtigung für Konfigurationen.

Beispiel

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

Antwort

{
    "status": "ok"
}

Antwort bei Fehlern

Wenn Fehler erkannt werden, enthält die Antwort zusätzlich Details zu den gefundenen Problemen:

{
    "status": "errors",
    "nonUniqueFields": [
        {
            "id": "general.salutation.1",
            "type": "general.salutation",
            "field": "code"
        }
    ],
    "missingRequiredFields": {
        "general.salutation.1": [
            "codeList"
        ]
    }
}

Die Felder nonUniqueFields und missingRequiredFields erscheinen nur, wenn entsprechende Probleme erkannt werden.

Fehlercodes

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

GET config/schemas

Dieser Endpunkt liefert eine vollständige Liste aller verfügbaren Konfigurationsschemata im System. Ein Schema beschreibt die Struktur und Eigenschaften eines bestimmten Konfigurationstyps, darunter z. B. Pflichtfelder, Datentypen, Schreibschutz, Überschreibbarkeit pro Subshop oder Singleton-Status. Die Schemata dienen als technische Grundlage für die Validierung und Bearbeitung von Konfigurationsdaten im Admin Interface oder in automatisierten Prozessen. Die Nutzung erfordert Leseberechtigungen für Konfigurationsdaten.

Beispiel

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

Antwort

{
    "items": [
        {
            "id": "accounts.account",
            "schema": {
                "group": "accounts",
                "isCreatable": false,
                "isDeletable": false,
                "isMainNode": true,
                "isSingleton": true,
                "isSubshopOverwriteable": true,
                "properties": [
                    {
                        "id": "login",
                        "isOptional": false,
                        "isReadOnly": false,
                        "isUnique": false,
                        "properties": [
                            {
                                "default": 5,
                                "id": "loginBlockCount",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "uint"
                            },
                            {
                                "default": 180,
                                "id": "loginBlockDuration",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "uint"
                            },
                            {
                                "id": "loginBlockEmail",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "properties": [
                                    {
                                        "id": "template",
                                        "isOptional": false,
                                        "isReadOnly": false,
                                        "isUnique": false,
                                        "type": "string"
                                    },
                                    {
                                        "id": "subject",
                                        "isOptional": false,
                                        "isReadOnly": false,
                                        "isUnique": false,
                                        "type": "string"
                                    },
                                    ...
                                ],
                                "type": "object"
                            },
                            {
                                "default": false,
                                "id": "ipBlockEnabled",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "bool"
                            },
                            {
                                "default": 10,
                                "id": "ipBlockCount",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "uint"
                            },
                            {
                                "default": 1,
                                "id": "ipBlockCountDuration",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "uint"
                            },
                            {
                                "default": 10,
                                "id": "ipBlockDuration",
                                "isOptional": false,
                                "isReadOnly": false,
                                "isUnique": false,
                                "type": "uint"
                            }
                        ],
                        "type": "object"
                    },
                    {
                        "id": "passwordChecks",
                        "isOptional": false,
                        "isReadOnly": false,
                        "isUnique": false,
                        "type": "multiService"
                    },
                    ...
                ],
                "type": "account"
            },
            "type": "account",
            "updatedAt": "2025-04-28T10:24:13.000Z"
        },
        ...
    ]
}

Fehlercodes

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

GET config/schemas/

Mit diesem Endpunkt kann das Schema eines bestimmten Konfigurationstyps abgerufen werden. Das Schema definiert die zulässigen Felder, deren Datentypen, optionale und Pflichtangaben sowie administrative Eigenschaften wie Schreibschutz, Löschbarkeit oder Subshop-Überschreibbarkeit. Die Informationen dienen dem Admin Interface und anderen Tools zur strukturellen Validierung und Darstellung von Konfigurationseinträgen im System. Leserechte für Konfigurationsdaten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/schemas/general.salutation

Antwort

{
    "group": "general",
    "isCreatable": false,
    "isDeletable": false,
    "isMainNode": true,
    "isSingleton": true,
    "isSubshopOverwriteable": true,
    "properties": [
        {
            "id": "codeList",
            "isOptional": false,
            "isReadOnly": false,
            "isUnique": false,
            "properties": [
                {
                    "id": "code",
                    "isOptional": false,
                    "isReadOnly": false,
                    "isUnique": false,
                    "type": "string"
                },
                {
                    "id": "text",
                    "isOptional": false,
                    "isReadOnly": false,
                    "isUnique": false,
                    "type": "string"
                }
            ],
            "subtype": "object",
            "type": "list"
        }
    ],
    "type": "salutation"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen.
404 Not Found	”schema not found”	Das Schema wurde nicht gefunden.

GET config/schemas//defaults

Mit diesem Endpunkt können Standardparameter einer Konfiguration abgerufen werden. Die Antwort enthält eine vollständige Vorlage für den angegebenen Konfigurationstyp. Leserechte für Konfigurationsdaten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/schemas/content.imageFormat/defaults

Antwort

{
    "data": {
        "autoConvert": {
            "active": false,
            "allowExternalTrigger": false,
            "hour": [

            ],
            "sourceDirectory": "",
            "weekday": [

            ]
        },
        "check": {
            "dpi": {
                "active": false,
                "max": 0,
                "min": 0
            },
            "fileSize": {
                "active": false,
                "max": 0.0,
                "maxUnit": "byte",
                "min": 0.0,
                "minUnit": "byte"
            },
            "inputTypeRestriction": {
                "active": false,
                "allowedTypes": [

                ]
            }
        },
        "convert": {
            "additionalArguments": "",
            "changeType": {
                "active": false,
                "type": "jpg"
            },
            "quality": {
                "active": false,
                "value": 100
            },
            "removeMetadata": false,
            "resize": {
                "active": false,
                "background": "#FFFFFF",
                "height": 0,
                "orientation": "center",
                "type": "scale",
                "width": 0
            },
            "sharpen": {
                "active": false,
                "sigma": 1.0
            }
        },
        "description": "",
        "name": "",
        "output": {
            "handleIfExists": "overwrite",
            "nameSuffix": "",
            "targetDirectory": ""
        },
        "type": "product"
    },
    "id": "content.imageFormat",
    "label": "imageFormat",
    "type": "imageFormat"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen.
404 Not Found	”schema not found”	Das Schema wurde nicht gefunden.

GET config/nodeTypes

Dieser Endpunkt liefert eine Übersicht über alle im System vorhandenen Konfigurationsknotentypen, gruppiert nach Schema. Für jeden Typ wird die Anzahl der erfassten Knoten zurückgegeben – also wie viele Konfigurationseinträge zu einem bestimmten Typ aktuell existieren. Die Information eignet sich beispielsweise zur Bestandsaufnahme, zur Validierung der Konfigurationsstruktur oder als Grundlage für die dynamische Darstellung im Admin Interface. Zum Abruf sind Leseberechtigungen für Konfigurationen erforderlich.

Beispiel

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

Antwort

[
    {
        "count": 1,
        "type": "accounts.account"
    },
    {
        "count": 1,
        "type": "accounts.accountRestrictions"
    },
    {
        "count": 1,
        "type": "accounts.addressField"
    },
    {
        "count": 0,
        "type": "accounts.addressFieldsSettings"
    },
    {
        "count": 0,
        "type": "accounts.bankInfoField"
    },
    {
        "count": 0,
        "type": "accounts.creditCardField"
    },
    {
        "count": 0,
        "type": "accounts.customAddressField"
    },
    {
        "count": 1,
        "type": "actions.accountDelete"
    },
    {
        "count": 1,
        "type": "actions.accountRegister"
    },
    {
        "count": 1,
        "type": "actions.addressCreate"
    },
    {
        "count": 1,
        "type": "actions.addressDelete"
    },
    {
        "count": 1,
        "type": "actions.addressUpdate"
    },
    {
        "count": 1,
        "type": "actions.basketItemAdd"
    },
    {
        "count": 1,
        "type": "actions.basketItemDelete"
    },
    ...
]

Fehlercodes

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

Methoden für die Verwaltung von Knoten im Shop

Über diese Methoden können Konfigurationsknoten im Shop ausgelesen, erstellt, aktualisiert oder gelöscht werden. Dabei handelt es sich um konkrete Instanzen von Einstellungen, die im Admin-Bereich des Shops gepflegt werden – z. B. für das Verhalten beim Account-Login oder für Einwilligungsdienste wie Cookie-Services. Je nach Typ des zugrunde liegenden Schemas kann ein Konfigurationsknoten entweder:

als Singleton definiert sein – d. h. es darf nur ein einziger Knoten dieses Typs im Shop existieren (z. B. ein globaler Login-Knoten),
oder als Multiknoten – bei dem mehrere Knoten desselben Typs erlaubt sind (z. B. mehrere Cookie-Services unter general.consentCookieService).

Die Gültigkeit der Daten wird beim Anlegen oder Aktualisieren anhand des zugehörigen Schemas geprüft. Die Zugriffe setzen entsprechende Berechtigungen zum Lesen, Schreiben oder Löschen von Konfigurationen voraus.

GET config/nodes/

Mit dieser Methode wird die Konfiguration eines oder mehrerer Knoten basierend auf dem angegebenen selector geladen. Der selector setzt sich in der Regel aus dem Schema und dem Knotentyp zusammen (z. B. actions.guestRegister oder general.consentCookieService). Abhängig vom Knoten liefert der Endpunkt entweder ein einzelnes Konfigurationselement oder eine Liste von Elementen. Die Antwort enthält jeweils die Konfigurationsdaten sowie Metainformationen wie id, type, label und updatedAt. Die Lese-Berechtigung für Konfigurationsdaten ist erforderlich.

Beispiel 1

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/actions.guestRegister

Antwort 1

{
    "items": [
        {
            "data": {
                "errorCodes": {
                    "createError": "Fehler beim Anlegen des Accounts",
                    "duplicateEmail": "Für die E-Mail existiert bereits ein Account",
                    "missingEmail": "E-Mail fehlt",
                    "missingPassword": "Passwort fehlt",
                    "nonGuestAccount": "Kein Gast-Account",
                    "passwordCheckFailed": "Passwort ungenügend",
                    "passwordMismatch": "Passwörter stimmen nicht überein"
                },
                "restrictions": {
                    "autoLoginAllowed": true
                },
                "verifyEmail": {
                    "fromAddress": "noreply@websale.de",
                    "fromName": "Mein Onlineshop",
                    "subject": "Mein Onlineshop | Registrierung",
                    "template": "accountRegister.htm"
                }
            },
            "id": "actions.guestRegister",
            "label": "guestRegister",
            "type": "guestRegister",
            "updatedAt": "2025-02-17T14:24:08.000Z"
        }
    ]
}

Beispiel 2

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService

Antwort 2

{
    "endReached": true,
    "items": [
        {
            "data": {
                "description": "",
                "label": "Google Analytics",
                "name": "google",
                "service": {
                    "externalService": {},
                    "shopService": null
                }
            },
            "id": "general.consentCookieService.googleAnalytics",
            "label": "consentCookieService",
            "type": "consentCookieService",
            "updatedAt": "2025-02-17T14:24:18.000Z"
        },
        ...
    ],
    "nextPageToken": "MA",
    "totalCount": 21
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen.
400 Bad Request	”invalidSelector”	`{selector}` hat mehr als 3 Teile, die durch einen `.` getrennt sind. Die Konfiguration wurde nicht gefunden.
400 Bad Request	”invalidParams”	Der Query-Parameter `sort` ist ungültig. Die Antwort enthält ein `errorContext`-Objekt mit Details (z. B. `{"sort": {"type": "invalidValue"}}`). Gültiges Format: `{feld}:{richtung}` mit `feld` = `id` oder `updatedAt` und `richtung` = `asc` oder `desc`.

PUT config/nodes/

Diese Methode dient zum Aktualisieren eines Konfigurationsknotens anhand seines Selectors. Der übergebene Dateninhalt wird dabei automatisch gegen das hinterlegte Schema geprüft. Wird das Schema verletzt, erfolgt eine detaillierte Fehlermeldung. Der Selector besteht aus zwei oder drei durch Punkte getrennten Teilen (z. B. actions.guestRegister oder general.consentCookieService.googleAnalytics). Das Format muss korrekt sein, damit die Konfiguration eindeutig zugeordnet werden kann. Wenn die Validierung fehlgeschlagen ist, enthält die Antwort Hinweise in Textform im Feld detail. Zum Beispiel: “The value of the field ‘name’ has the wrong type. Expected: string.”. Fehler sind auch im Feld errorContext aufgelistet. Mögliche Fehlertypen (errorContext.{field}.type): WrongType
WrongEnumValue
KeyNotAllowed
IsReadOnly
NotUnique
InvalidSelfAssociation
ServiceNotFound
AssociationWrongType
ServiceMissing
AssociationNotFound
ServiceWrongType
TextMissing Schreibberechtigungen für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/actions.guestRegister

Request Body

{
    "data": {
        "errorCodes": {
            "createError": "Fehler beim Anlegen des Accounts",
            "duplicateEmail": "Für die E-Mail existiert bereits ein Account",
            "missingEmail": "E-Mail fehlt",
            "missingPassword": "Passwort fehlt",
            "nonGuestAccount": "Kein Gast-Account",
            "passwordCheckFailed": "Passwort ungenügend",
            "passwordMismatch": "Passwörter stimmen nicht überein"
        },
        "restrictions": {
            "autoLoginAllowed": true
        },
        "verifyEmail": {
            "fromAddress": "noreply@websale.de",
            "fromName": "Mein Onlineshop",
            "subject": "Mein Onlineshop | Registrierung",
            "template": "accountRegister.htm"
        }
    }
}

Antwort

{
    "data": {
          <data from the request body>
    },
    "id": "actions.guestRegister",
    "label": "guestRegister",
    "type": "guestRegister",
    "updatedAt": "2025-02-17T14:24:08.000Z"
}

Antwort wenn die Validierung Fehlgeschlagen ist

{
    "detail": "The value of the field 'name' has the wrong type. Expected: string. The value of the field 'service.externalService' has the wrong type. Expected: object.",
    "error": "dataNotCorrect",
    "errorContext": {
        "name": {
            "type": "WrongType",
            "expectedType": "string"
        },
        "service.externalService": {
            "type": "WrongType",
            "expectedType": "object"
        }
    }
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Konfigurationen. Es wird versucht, eine Konfiguration zu aktualisieren, die Websale AG gehört.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 und nicht 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”invalidParams”	Pflichtfelder fehlen oder haben den falschen Typ. Die Antwort enthält ein `errorContext`-Objekt mit Details zu den betroffenen Feldern (z. B. `{"data": {"type": "missing", "expectedType": "object"}}`).
400 Bad Request	”dataNotCorrect”	Daten entsprechen dem Schema nicht. Es wird ein Kommentar geliefert, wo steht, was genau nicht stimmt.
409 Conflict	”alreadyExists”	Der Knoten existiert bereits (z. B. bei gleichzeitiger Erstellung eines Singleton-Knotens).
400 Bad Request	”updateFailed”	Das Aktualisieren ist fehlgeschlagen.
404 Not Found	”NodeNotFound”	Die Konfiguration wurde nicht gefunden.
503 Service Unavailable	”internalError”	Sonstiger Fehler. Details sind in Logs zu finden.

POST config/nodes/

Ein Konfigurationsknoten wird erstellt, dabei wird die Schema-Gültigkeit geprüft. Diese Methode legt einen neuen Konfigurationsknoten innerhalb des angegebenen Schemas an. Dabei wird geprüft, ob der Knoten gemäß Schema erstellt werden darf (z. B. nicht bei Singleton-Schemata) und ob die übergebenen Daten gültig sind. Die Struktur muss dem Schema entsprechen, sonst wird der Vorgang mit einer präzisen Fehlermeldung abgelehnt. Der selector besteht immer aus zwei durch Punkt getrennten Teilen (z. B. general.consentCookieService), die den Schema-Typ beschreiben. Zusätzlich muss im Request-Body ein eindeutiges id-Feld angegeben werden, das an den Selector angehängt wird (z. B. test → ergibt general.consentCookieService.test). Wenn die Validierung fehlgeschlagen ist, enthält die Antwort Hinweise in Textform im Feld detail. Zum Beispiel: “The value of the field ‘name’ has the wrong type. Expected: string.”. Fehler sind auch im Feld errorContext aufgelistet. Mögliche Fehlertypen (errorContext.{field}.type): WrongType
WrongEnumValue
KeyNotAllowed
IsReadOnly
NotUnique
InvalidSelfAssociation
ServiceNotFound
AssociationWrongType
ServiceMissing
AssociationNotFound
ServiceWrongType
TextMissing Erstellrechte für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService

Request Body

{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "id": "test"
}

Antwort

{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "id": "general.consentCookieService.test",
    "label": "consentCookieService",
    "type": "consentCookieService"
}

Antwort wenn die Validierung Fehlgeschlagen ist

{
    "detail": "The value of the field 'name' has the wrong type. Expected: string. The value of the field 'service.externalService' has the wrong type. Expected: object.",
    "error": "dataNotCorrect",
    "errorContext": {
        "name": {
            "type": "WrongType",
            "expectedType": "string"
        },
        "service.externalService": {
            "type": "WrongType",
            "expectedType": "object"
        }
    }
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Konfigurationen.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ des Konfigurationsknotens.
400 Bad Request	”creationDenied”	Das Schema ist ein `singleton`. Das Schema hat die Eigenschaft `creatable: false`.
400 Bad Request	”invalidParams”	Pflichtfelder (`id`, `data`) fehlen, haben den falschen Typ oder sind leer. Die Antwort enthält ein `errorContext`-Objekt mit Details zu den betroffenen Feldern (z. B. `{"id": {"type": "missing", "expectedType": "string"}}` oder `{"id": {"type": "invalidValue"}}`).
400 Bad Request	”dataNotCorrect”	Daten entsprechen dem Schema nicht. Es wird ein Kommentar geliefert, wo steht, was genau nicht stimmt.
409 Conflict	”alreadyExists”	`id` wurde schon verwendet.
503 Service Unavailable	”internalError”	Sonstiger Fehler. Details sind in Logs zu finden.

DELETE config/nodes/

Diese Methode löscht einen bestehenden Konfigurationsknoten. Der angegebene selector muss genau drei durch Punkt getrennte Teile enthalten (z. B. general.consentCookieService.google). Vor dem Löschen wird geprüft, ob das zugehörige Schema dies erlaubt – etwa ob es sich nicht um ein Singleton handelt oder das Löschen explizit untersagt ist. Löschrechte für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService.google

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Konfigurationen. Es wird versucht, eine Konfiguration zu löschen, die Websale AG gehört.
400 Bad Request	”invalidSelector”	`{selector}` hat mehr bzw. weniger als 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”idInvalid”	Die Konfiguration wurde nicht gefunden.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ des Konfigurationsknotens.
400 Bad Request	”deletionDenied”	Das Schema ist ein `singleton`. Das Schema hat die Eigenschaft `deletable: false`.
400 Bad Request	”node not deleted”	Das Löschen ist fehlgeschlagen.

Methoden für die Verwaltung von Knoten in Subshops

Die hier dokumentierten Endpunkte ermöglichen es, Konfigurationsknoten für einzelne Subshops gezielt zu überschreiben. Damit lassen sich abweichende Einstellungen je Subshop realisieren – etwa verschiedene Datenschutzdienste oder abweichende E-Mail-Konfigurationen. Die Methoden orientieren sich am allgemeinen Schema der Knotenverwaltung, erweitern es jedoch um die zusätzliche Angabe einer subshopId.

GET config/nodes//overwrites

Mit dieser Methode wird eine Liste aller Überschreibungen für einen bestimmten Konfigurationsknoten zurückgegeben. Dabei handelt es sich um Konfigurationen, die gezielt für einzelne Subshops angepasst wurden. Ist der Knoten nicht überschreibbar, wird ein leeres JSON-Array ([]) zurückgegeben. Liegen keine Überschreibungen vor, enthält das Ergebnis ein items-Objekt mit leerem Array. Leseberechtigungen für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService.econda/overwrites/

Antwort

{
    "items": [
        {
            "data": {
                "description": "",
                "label": "",
                "name": "",
                "service": {
                    "externalService": null,
                    "shopService": null
                }
            },
            "nodeId": "general.consentCookieService.econda",
            "subshopId": "deutsch"
        }
    ]
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 und nicht 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ aus dem `{selector}`.
404 Not found	”nodeNotFound”	Die Konfiguration wurde nicht gefunden.

GET config/nodes//overwrites/

Diese Methode lädt die Subshop-spezifische Überschreibung eines bestimmten Konfigurationsknotens. Existiert keine Überschreibung für den angegebenen Subshop, wird ein entsprechender Fehler zurückgegeben. Ist der Knoten nicht überschreibbar, wird ein Fehler zurückgegeben (inappropriateScheme). Leseberechtigungen für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/security.recaptchav3/overwrites/deutsch/

Antwort

{
    "data": {
        "minimumScore": 0.0,
        "name": "",
        "secretKey": "",
        "verifyUrl": ""
    },
    "nodeId": "security.recaptchav3",
    "subshopId": "deutsch"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Konfigurationen.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 und nicht 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ aus dem `{selector}`.
400 Bad Request	”inappropriateScheme”	Der Knoten ist nicht überschreibbar.
404 Not found	”nodeNotFound”	Die Konfiguration wurde nicht gefunden.
404 Not found	”nodeOverwriteNotFound”	Die Überschreibung wurde nicht gefunden.

PUT config/nodes//overwrites/

Mit dieser Methode kann ein Konfigurationsknoten für einen bestimmten Subshop überschrieben werden. Die Daten im Request Body müssen dem Schema des ursprünglichen Knotens entsprechen. Nur Knoten mit entsprechender Eigenschaft können überschrieben werden. Wenn die Validierung fehlgeschlagen ist, enthält die Antwort Hinweise in Textform. Zum Beispiel: “The value of the field ‘name’ has the wrong type. Expected: string.”. Fehler sind auch im Feld errorContext aufgelistet. Mögliche Fehlertypen (errorContext.<field>.type): WrongType
WrongEnumValue
KeyNotAllowed
IsReadOnly
NotUnique
InvalidSelfAssociation
ServiceNotFound
AssociationWrongType
ServiceMissing
AssociationNotFound
ServiceWrongType
TextMissing Erstellberechtigungen für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService/overwrites/english

Request Body

{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    }
}

Antwort

{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "nodeId": "general.consentCookieService",
    "subshopId": "english"
}

Antwort wenn die Validierung Fehlgeschlagen ist

{
    "detail": "The value of the field 'name' has the wrong type. Expected: string. The value of the field 'service.externalService' has the wrong type. Expected: object.",
    "error": "dataNotCorrect",
    "errorContext": {
        "name": {
            "type": "WrongType",
            "expectedType": "string"
        },
        "service.externalService": {
            "type": "WrongType",
            "expectedType": "object"
        }
    }
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Konfigurationen. Es wird versucht, eine Konfiguration zu aktualisieren, die Websale AG gehört.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”invalidSubshopId”	Subshop wurde nicht gefunden.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 und nicht 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ aus dem `{selector}`.
400 Bad Request	”overwriteDenied”	Der Knoten darf nicht überschrieben werden.
400 Bad Request	”invalidParams”	`data` fehlt oder hat einen falschen Typ. Die Antwort enthält ein `errorContext`-Objekt mit Details.
400 Bad Request	”dataNotCorrect”	Daten entsprechen dem Schema nicht. Es wird ein Kommentar geliefert, wo steht, was genau nicht stimmt.
409 Conflict	”alreadyExists”	Konflikt: Die Überschreibung existiert bereits.
404 Not Found	”NodeNotFound”	Der Knoten, der überschrieben werden soll, wurde nicht gefunden.
503 Service Unavailable	”internalError”	Sonstiger Fehler. Details sind in Logs zu finden.

DELETE config/nodes//overwrites/

Diese Methode entfernt die vorhandene Überschreibung eines Konfigurationsknotens für einen bestimmten Subshop. Wird keine gültige Überschreibung gefunden oder ist das Löschen nicht erlaubt, erfolgt eine entsprechende Fehlermeldung. Löschberechtigungen für Konfigurationen sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/config/nodes/general.consentCookieService/overwrites/english

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von Konfigurationen. Es wird versucht, eine Konfiguration zu löschen, die Websale AG gehört.
400 Bad Request	”invalidSelector”	`{selector}` hat nicht 2 und nicht 3 Teile, die durch einen `.` getrennt sind.
400 Bad Request	”typeInvalid”	Es gibt kein Schema mit dem Typ aus dem `{selector}`.
400 Bad Request	”subshopIdMissing”	`subshopId` wurde nicht übergeben.
400 Bad Request	”unknownOverwriting”	Das Löschen ist fehlgeschlagen.

Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Documentation Index

​Unterstützte Methoden

​Struktur & Anwendung der Konfiguration über die API

​Gültige {type}- und {selector}-Werte

​Methoden für Einstellungen

​GET config/setup

​Beispiel

​Antwort

​Fehlercodes

​GET config/status

​Beispiel

​Antwort

​Antwort bei Fehlern

​Fehlercodes

​GET config/schemas

​Beispiel

​Antwort

​Fehlercodes

​GET config/schemas/

​Beispiel

​Antwort

​Fehlercodes

​GET config/schemas//defaults

​Beispiel

​Antwort

​Fehlercodes

​GET config/nodeTypes

​Beispiel

​Antwort

​Fehlercodes

​Methoden für die Verwaltung von Knoten im Shop

​GET config/nodes/

​Beispiel 1

​Antwort 1

​Beispiel 2

​Antwort 2

​Fehlercodes

​PUT config/nodes/

​Beispiel

​Request Body

​Antwort

​Antwort wenn die Validierung Fehlgeschlagen ist

​Fehlercodes

​POST config/nodes/

​Beispiel

​Request Body

​Antwort

​Antwort wenn die Validierung Fehlgeschlagen ist

​Fehlercodes

​DELETE config/nodes/

​Beispiel

​Antwort

​Fehlercodes

​Methoden für die Verwaltung von Knoten in Subshops

​GET config/nodes//overwrites

​Beispiel

​Antwort

​Fehlercodes

​GET config/nodes//overwrites/

​Beispiel

​Antwort

​Fehlercodes

​PUT config/nodes//overwrites/

​Beispiel

​Request Body

​Antwort

​Antwort wenn die Validierung Fehlgeschlagen ist

​Fehlercodes

​DELETE config/nodes//overwrites/

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Struktur & Anwendung der Konfiguration über die API

Gültige `{type}`- und `{selector}`-Werte

Methoden für Einstellungen

GET config/setup

Beispiel

Antwort

Fehlercodes

GET config/status

Beispiel

Antwort

Antwort bei Fehlern

Fehlercodes

GET config/schemas

Beispiel

Antwort

Fehlercodes

GET config/schemas/

Beispiel

Antwort

Fehlercodes

GET config/schemas//defaults

Beispiel

Antwort

Fehlercodes

GET config/nodeTypes

Beispiel

Antwort

Fehlercodes

Methoden für die Verwaltung von Knoten im Shop

GET config/nodes/

Beispiel 1

Antwort 1

Beispiel 2

Antwort 2

Fehlercodes

PUT config/nodes/

Beispiel

Request Body

Antwort

Antwort wenn die Validierung Fehlgeschlagen ist

Fehlercodes

POST config/nodes/

Beispiel

Request Body

Antwort

Antwort wenn die Validierung Fehlgeschlagen ist

Fehlercodes

DELETE config/nodes/

Beispiel

Antwort

Fehlercodes

Methoden für die Verwaltung von Knoten in Subshops

GET config/nodes//overwrites

Beispiel

Antwort

Fehlercodes

GET config/nodes//overwrites/

Beispiel

Antwort

Fehlercodes

PUT config/nodes//overwrites/

Beispiel

Request Body

Antwort

Antwort wenn die Validierung Fehlgeschlagen ist

Fehlercodes

DELETE config/nodes//overwrites/

Beispiel

Antwort

Fehlercodes

Support