> ## 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.

# API reference configuration

> Read and modify global and subshop-specific shop configuration nodes through the Admin Interface API with schema-based server-side validation.

The interface for the `config/` endpoint provides comprehensive access to the shop configuration. Through the REST API, configuration data can be retrieved, changed, deleted, or newly created. This includes both global settings and subshop-specific overrides.

The configuration is based on predefined schemas that determine which data is permitted. Changes to configuration nodes are validated server-side. The REST API thus allows complete management of the shop configuration — as it is also done via the admin interface.

## Supported methods

List of all supported methods.

| **Command/info**                                                                                                                                                       | **Endpoints**                                                                                                                                                              | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| [**Settings**](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532670/API-Referenz+Konfiguration#3-methoden-für-einstellungen)                              | config/                                                                                                                                                                    | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="ban" />   | <Icon icon="ban" />   |
| [**Nodes in the shop**](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532670/API-Referenz+Konfiguration#4-methoden-für-die-verwaltung-von-knoten-im-shop) | <Icon icon="check" />                                                                                                                                                      | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |                       |
|                                                                                                                                                                        | [**Nodes in subshops**](https://websale.atlassian.net/wiki/spaces/WSDOKU/pages/3058532670/API-Referenz+Konfiguration#5-methoden-für-die-verwaltung-von-knoten-in-subshops) | <Icon icon="check" /> | <Icon icon="ban" />   | <Icon icon="check" /> | <Icon icon="check" /> |

## Structure & use of the configuration via the API

The shop configuration is organized as a directed graph. Each node in this graph represents an independent configuration area and can reference other nodes — for example to specify a language or a country.

Each configuration node has a clearly defined type, for which a schema defines which data fields are permitted, what data types they have, and whether a node may be overwritten per subshop or may only exist once. The schemas thus describe the structure of the configuration data, but not its content.

The configuration can be fully maintained via the REST API. The admin interface (AI) is also a visual representation of this interface. All functions that can be performed in the interface are also available via the API — such as creating, adapting, deleting, or overwriting configuration nodes.

The API is thus particularly suitable for automated management of the configuration, for example as part of:

* CI/CD processes with clearly defined configuration states,
* the comparison of settings between test and production systems,
* or the management of multi-tenant environments with subshop-specific variants.

The REST API thus provides complete access to your shop's configuration.

To determine the fields of a node, the corresponding schema must be loaded via the `GET config/schemas/{type}` endpoint. The structure of these schemas is described in the `properties` field. Among other things, it contains the fields `id`, `type`, and optionally `subtype` (e.g. for `type: list`). `id` defines the name of the field, while `type` and `subtype` indicate what content is expected. `type: object` indicates a nested structure.

Which configuration types are available in the system can be queried in two ways:

* via `GET config/nodeTypes`, which provides a compact list of all types,
* or alternatively via `GET config/schemas`, which additionally contains the `id` field.

### Valid `{type}` and `{selector}` values

The following tables list the valid values that can be used for

* `GET /api/config/schemas/{type}` as `{type}` and
* `GET /api/config/nodes/{selector}` as **top-level** `{selector}`.

The subnodes, parameters, and examples of the individual areas are not part of this API reference. They are fully described in the [Configuration](/en/konfiguration) document. This section serves exclusively as orientation for the valid identifiers.

| **Type / selector**  | **Short description**                                                                                                |
| -------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `accounts`           | → [accounts - user accounts](/en/konfiguration/accounts-benutzerkonten)                                              |
| `actions`            | → [actions - error texts & emails](/en/konfiguration/actions-fehlertexte-e-mails)                                    |
| `app`                | → [app - WEBSALE APP](/en/konfiguration/app-websale-app)                                                             |
| `authentication`     | → [authentication - authentication & access data](/en/konfiguration/authentication-authentifizierungs-zugriffsdaten) |
| `b2b`                | → [b2b - business-to-business (B2B)](/en/konfiguration/b2b-business-to-business-b2b)                                 |
| `basket`             | → [basket - shopping basket](/en/konfiguration/basket-warenkorb)                                                     |
| `checkout`           | → [checkout - order process](/en/konfiguration/checkout-bestellablauf)                                               |
| `content`            | → [content - catalog (categories & products)](/en/konfiguration/content-katalog-kategorien-produkte)                 |
| `creditCheck`        | → [creditCheck - credit check (old)](/en/konfiguration/creditcheck-bonitatsprufung)                                  |
| `customer`           | → [customer - customer data](/en/konfiguration/customer-kundendaten)                                                 |
| `finance`            | → [finance - currencies & taxes](/en/konfiguration/finance-wahrungen-steuern)                                        |
| `general`            | → [general - general shop settings](/en/konfiguration/general-allgemeine-shopeinstellungen)                          |
| `inquiry`            | → [inquiry - forms](/en/konfiguration/inquiry-formulare)                                                             |
| `maintenance`        | → [maintenance - maintenance mode](/en/konfiguration/maintenance-wartungsmodus)                                      |
| `messages`           | → [messages - event-driven emails](/en/konfiguration/messages-ereignisgesteuerte-e-mails)                            |
| `newsletter`         | → [newsletter - newsletter](/en/konfiguration/newsletter-newsletter)                                                 |
| `payment`            | → [payment - payment methods](/en/konfiguration/payment-zahlungsmethoden)                                            |
| `search`             | → [search - search (core)](/en/konfiguration/search-sortierung-und-filterung)                                        |
| `security`           | → [security - security](/en/konfiguration/security-sicherheitsregeln)                                                |
| `seoMetaData`        | → [seoMetaData - meta data & SEO texts](/en/konfiguration/seometadata-meta-daten-seo-texte)                          |
| `shopSystemServices` | → [shopSystemServices - additional modules](/en/frontend/referenz/module)                                            |
| `urls`               | → [urls - URL (web addresses)](/en/konfiguration/urls-url-webadressen)                                               |

## Methods for settings

This section describes the available REST endpoints for managing the shop configuration in the admin area. The interface can be used to retrieve schemas, analyze, check, delete, or completely reset configuration nodes.

The configuration is divided into so-called schemas and nodes that are assigned to different areas such as accounts, actions, or system functions.

All settings apply either globally or subshop-specifically and can be adjusted depending on the schema and type.

The use of the methods requires appropriate read, write, or delete permissions.

### GET config/setup

This endpoint retrieves the setup configuration per subshop and stage (e.g. `work`, `active`).

The return contains technical information such as the `host`, `staticDomain`, and `contentDomain` values, which are required for runtime configuration and content delivery in the respective subshop. This endpoint is primarily intended for internal system or administrative analysis of the current shop setup.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/setup
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
    {
        "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"
    }
]
```

#### Error codes

| **Error**        | **Type** | **Reason**                                |
| ---------------- | -------- | ----------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in.    |
| 403 Forbidden    |          | You do not have the required permissions. |

### GET config/status

This endpoint checks the configuration data for incompleteness and redundancy.

It reports whether mandatory fields are missing or whether nodes with identical data exist multiple times.\
If no problem is detected, `"status": "ok"` is returned.

Use requires read permission for configurations.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/status
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "status": "ok"
}
```

#### Response on errors

If errors are detected, the response additionally contains details about the problems found:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "status": "errors",
    "nonUniqueFields": [
        {
            "id": "general.salutation.1",
            "type": "general.salutation",
            "field": "code"
        }
    ],
    "missingRequiredFields": {
        "general.salutation.1": [
            "codeList"
        ]
    }
}
```

The `nonUniqueFields` and `missingRequiredFields` fields appear only when corresponding problems are detected.

#### Error codes

| **Error**        | **Type** | **Reason**                                                       |
| ---------------- | -------- | ---------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in.                           |
| 403 Forbidden    |          | You do not have the required permissions to read configurations. |

### GET config/schemas

This endpoint returns a complete list of all available configuration schemas in the system.

A schema describes the structure and properties of a particular configuration type, including, for example, mandatory fields, data types, write protection, overwriteability per subshop, or singleton status.

The schemas serve as a technical basis for the validation and editing of configuration data in the admin interface or in automated processes.

Use requires read permissions for configuration data.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/schemas
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        },
        ...
    ]
}
```

#### Error codes

| **Error**        | **Type** | **Reason**                                                       |
| ---------------- | -------- | ---------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in.                           |
| 403 Forbidden    |          | You do not have the required permissions to read configurations. |

### GET config/schemas/\{type}

This endpoint can be used to retrieve the schema of a specific configuration type.

The schema defines the permitted fields, their data types, optional and mandatory information, and administrative properties such as write protection, deletability, or subshop overwriteability.

The information is used by the admin interface and other tools for structural validation and display of configuration entries in the system.

Read rights for configuration data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/schemas/general.salutation
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                       |
| ---------------- | ------------------ | ---------------------------------------------------------------- |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                           |
| 403 Forbidden    |                    | You do not have the required permissions to read configurations. |
| 404 Not Found    | "schema not found" | The schema was not found.                                        |

### GET config/schemas/\{type}/defaults

This endpoint can be used to retrieve default parameters of a configuration.

The response contains a complete template for the specified configuration type.

Read rights for configuration data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/schemas/content.imageFormat/defaults
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                       |
| ---------------- | ------------------ | ---------------------------------------------------------------- |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                           |
| 403 Forbidden    |                    | You do not have the required permissions to read configurations. |
| 404 Not Found    | "schema not found" | The schema was not found.                                        |

### GET config/nodeTypes

This endpoint returns an overview of all **configuration node types** present in the system, grouped by schema.

For each type, the number of recorded nodes is returned — i.e. how many configuration entries of a given type currently exist. This information is suitable, for example, for inventory taking, validation of the configuration structure, or as a basis for dynamic display in the admin interface.

Read permissions for configurations are required for retrieval.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodeTypes
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
    {
        "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"
    },
    ...
]
```

#### Error codes

| **Error**        | **Type** | **Reason**                                                       |
| ---------------- | -------- | ---------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in.                           |
| 403 Forbidden    |          | You do not have the required permissions to read configurations. |

## Methods for managing nodes in the shop

These methods can be used to read, create, update, or delete configuration nodes in the shop. These are specific instances of settings maintained in the admin area of the shop — e.g. for account login behavior or for consent services such as cookie services.

Depending on the type of the underlying schema, a configuration node can either:

* be defined as a singleton — i.e. only a single node of this type may exist in the shop (e.g. a global login node),
* or as a multi-node — where multiple nodes of the same type are allowed (e.g. multiple cookie services under `general.consentCookieService`).

The validity of the data is checked against the corresponding schema when creating or updating.

Access requires appropriate permissions for reading, writing, or deleting configurations.

### GET config/nodes/\{selector}

This method loads the configuration of one or more nodes based on the specified `selector`. The `selector` is generally composed of the schema and the node type (e.g. `actions.guestRegister` or `general.consentCookieService`).

Depending on the node, the endpoint returns either a single configuration element or a list of elements.

The response contains the configuration data as well as meta information such as `id`, `type`, `label`, and `updatedAt`.

Read permission for configuration data is required.

#### Example 1

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/actions.guestRegister
```

#### Response 1

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        }
    ]
}
```

#### Example 2

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService
```

#### Response 2

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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
}
```

#### Error codes

| **Error**        | **Type**          | **Reason**                                                                                                                                                                                                                                                |
| ---------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                   | Not authorized: you are not logged in.                                                                                                                                                                                                                    |
| 403 Forbidden    |                   | You do not have the required permissions to read configurations.                                                                                                                                                                                          |
| 400 Bad Request  | "invalidSelector" | `{selector}` has more than 3 parts separated by a `.`. <br /> The configuration was not found.                                                                                                                                                            |
| 400 Bad Request  | "invalidParams"   | The `sort` query parameter is invalid. The response contains an `errorContext` object with details (e.g. `{"sort": {"type": "invalidValue"}}`). Valid format: `{field}:{direction}` with `field` = `id` or `updatedAt` and `direction` = `asc` or `desc`. |

### PUT config/nodes/\{selector}

This method is used to update a configuration node by its selector. The data content provided is automatically checked against the stored schema. If the schema is violated, a detailed error message is returned.

The selector consists of two or three parts separated by dots (e.g. `actions.guestRegister` or `general.consentCookieService.googleAnalytics`). The format must be correct so that the configuration can be uniquely identified.

If validation fails, the response contains text hints in the `detail` field. For example: "The value of the field 'name' has the wrong type. Expected: string.". Errors are also listed in the `errorContext` field.

Possible error types (`errorContext.{field}.type`):

`WrongType`\
`WrongEnumValue`\
`KeyNotAllowed`\
`IsReadOnly`\
`NotUnique`\
`InvalidSelfAssociation`\
`ServiceNotFound`\
`AssociationWrongType`\
`ServiceMissing`\
`AssociationNotFound`\
`ServiceWrongType`\
`TextMissing`

Write permissions for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/actions.guestRegister
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        }
    }
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
          <data from the request body>
    },
    "id": "actions.guestRegister",
    "label": "guestRegister",
    "type": "guestRegister",
    "updatedAt": "2025-02-17T14:24:08.000Z"
}
```

#### Response when validation failed

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        }
    }
}
```

#### Error codes

| **Error**               | **Type**          | **Reason**                                                                                                                                                                                                   |
| ----------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized        |                   | Not authorized: you are not logged in.                                                                                                                                                                       |
| 403 Forbidden           |                   | You do not have the required permissions to write configurations.<br />An attempt was made to update a configuration that belongs to Websale AG.                                                             |
| 400 Bad Request         |                   | Request body could not be loaded.                                                                                                                                                                            |
| 400 Bad Request         | "invalidSelector" | `{selector}` does not have 2 or 3 parts separated by a `.`.                                                                                                                                                  |
| 400 Bad Request         | "invalidParams"   | Mandatory fields are missing or have the wrong type. The response contains an `errorContext` object with details about the affected fields (e.g. `{"data": {"type": "missing", "expectedType": "object"}}`). |
| 400 Bad Request         | "dataNotCorrect"  | The data does not conform to the schema. A comment is supplied that states what exactly is wrong.                                                                                                            |
| 409 Conflict            | "alreadyExists"   | The node already exists (e.g. for simultaneous creation of a singleton node).                                                                                                                                |
| 400 Bad Request         | "updateFailed"    | The update failed.                                                                                                                                                                                           |
| 404 Not Found           | "NodeNotFound"    | The configuration was not found.                                                                                                                                                                             |
| 503 Service Unavailable | "internalError"   | Other error. Details can be found in the logs.                                                                                                                                                               |

### POST config/nodes/\{selector}

A configuration node is created; the schema validity is checked.

This method creates a new configuration node within the specified schema. It is checked whether the node may be created according to the schema (e.g. not for singleton schemas) and whether the provided data is valid. The structure must match the schema; otherwise, the operation is rejected with a precise error message.

The `selector` always consists of two parts separated by a dot (e.g. `general.consentCookieService`) that describe the schema type. Additionally, a unique `id` field must be specified in the request body, which is appended to the selector (e.g. `test` → results in `general.consentCookieService.test`).

If validation fails, the response contains text hints in the `detail` field. For example: "The value of the field 'name' has the wrong type. Expected: string.". Errors are also listed in the `errorContext` field.

Possible error types (`errorContext.{field}.type`):

`WrongType`\
`WrongEnumValue`\
`KeyNotAllowed`\
`IsReadOnly`\
`NotUnique`\
`InvalidSelfAssociation`\
`ServiceNotFound`\
`AssociationWrongType`\
`ServiceMissing`\
`AssociationNotFound`\
`ServiceWrongType`\
`TextMissing`

Create rights for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "id": "test"
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "id": "general.consentCookieService.test",
    "label": "consentCookieService",
    "type": "consentCookieService"
}
```

#### Response when validation failed

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        }
    }
}
```

#### Error codes

| **Error**               | **Type**          | **Reason**                                                                                                                                                                                                                                                                  |
| ----------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                   | Not authorized: you are not logged in.                                                                                                                                                                                                                                      |
| 403 Forbidden           |                   | You do not have the required permissions to create configurations.                                                                                                                                                                                                          |
| 400 Bad Request         |                   | Request body could not be loaded.                                                                                                                                                                                                                                           |
| 400 Bad Request         | "invalidSelector" | `{selector}` does not have 2 parts separated by a `.`.                                                                                                                                                                                                                      |
| 400 Bad Request         | "typeInvalid"     | There is no schema with the type of the configuration node.                                                                                                                                                                                                                 |
| 400 Bad Request         | "creationDenied"  | The schema is a `singleton`. <br /> The schema has the property `creatable: false`.                                                                                                                                                                                         |
| 400 Bad Request         | "invalidParams"   | Mandatory fields (`id`, `data`) are missing, have the wrong type, or are empty. The response contains an `errorContext` object with details about the affected fields (e.g. `{"id": {"type": "missing", "expectedType": "string"}}` or `{"id": {"type": "invalidValue"}}`). |
| 400 Bad Request         | "dataNotCorrect"  | The data does not conform to the schema. A comment is supplied that states what exactly is wrong.                                                                                                                                                                           |
| 409 Conflict            | "alreadyExists"   | `id` is already in use.                                                                                                                                                                                                                                                     |
| 503 Service Unavailable | "internalError"   | Other error. Details can be found in the logs.                                                                                                                                                                                                                              |

### DELETE config/nodes/\{selector}

This method deletes an existing configuration node. The specified `selector` must contain exactly three parts separated by a dot (e.g. `general.consentCookieService.google`). Before deletion, it is checked whether the corresponding schema permits this — for example whether it is not a singleton or deletion is explicitly forbidden.

Delete rights for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService.google
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                                                                                                          |
| ---------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                                                                                                              |
| 403 Forbidden    |                    | You do not have the required permissions to delete configurations. <br /> An attempt was made to delete a configuration that belongs to Websale AG. |
| 400 Bad Request  | "invalidSelector"  | `{selector}` has more or fewer than 3 parts separated by a `.`.                                                                                     |
| 400 Bad Request  | "idInvalid"        | The configuration was not found.                                                                                                                    |
| 400 Bad Request  | "typeInvalid"      | There is no schema with the type of the configuration node.                                                                                         |
| 400 Bad Request  | "deletionDenied"   | The schema is a `singleton`. <br /> The schema has the property `deletable: false`.                                                                 |
| 400 Bad Request  | "node not deleted" | The deletion failed.                                                                                                                                |

### POST config/nodes/\{selector}/move

This method reorders an existing configuration node within its type. Moving is only possible within the same type — a node can only be positioned relative to other nodes of the same type.

The new position is defined via exactly one of the two target parameters `beforeTarget` or `afterTarget`:

* With `beforeTarget` the node is placed directly **before** the specified target node.
* With `afterTarget` the node is placed directly **after** the specified target node.

Only one of the two parameters may be set at a time. If both or neither are provided, the operation is rejected.

Write rights for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService.econda/move
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "beforeTarget": "general.consentCookieService.google"
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**        | **Type**        | **Reason**                                                                                          |
| ---------------- | --------------- | --------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                 | Not authorized: you are not logged in.                                                              |
| 403 Forbidden    |                 | You do not have the required permissions to access this configuration.                              |
| 400 Bad Request  | "invalidParams" | Both `beforeTarget` and `afterTarget` were provided, or neither of the two parameters was provided. |
| 400 Bad Request  | "badSelector"   | The configuration `{selector}` does not exist.                                                      |
| 400 Bad Request  | "idInvalid"     | `beforeTarget`/`afterTarget` do not exist or are of a different type than `{selector}`.             |

## Methods for managing nodes in subshops

The endpoints documented here allow you to specifically overwrite configuration nodes for individual subshops. This makes it possible to implement differing settings per subshop — for example different privacy services or differing email configurations.

The methods follow the general schema of node management but extend it with the additional specification of a `subshopId`.

### GET config/nodes/\{selector}/overwrites

This method returns a list of all overrides for a specific configuration node. These are configurations that have been specifically adapted for individual subshops. If the node is not overwriteable, an empty JSON array (`[]`) is returned. If no overrides exist, the result contains an `items` object with an empty array.

Read permissions for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService.econda/overwrites/
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "items": [
        {
            "data": {
                "description": "",
                "label": "",
                "name": "",
                "service": {
                    "externalService": null,
                    "shopService": null
                }
            },
            "nodeId": "general.consentCookieService.econda",
            "subshopId": "deutsch"
        }
    ]
}
```

#### Error codes

| **Error**        | **Type**          | **Reason**                                                       |
| ---------------- | ----------------- | ---------------------------------------------------------------- |
| 401 Unauthorized |                   | Not authorized: you are not logged in.                           |
| 403 Forbidden    |                   | You do not have the required permissions to read configurations. |
| 400 Bad Request  | "invalidSelector" | `{selector}` does not have 2 or 3 parts separated by a `.`.      |
| 400 Bad Request  | "typeInvalid"     | There is no schema with the type from `{selector}`.              |
| 404 Not found    | "nodeNotFound"    | The configuration was not found.                                 |

### GET config/nodes/\{selector}/overwrites/\{subshopId}

This method loads the subshop-specific override of a specific configuration node. If no override exists for the specified subshop, a corresponding error is returned.

If the node is not overwriteable, an error is returned (`inappropriateScheme`).

Read permissions for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/security.recaptchav3/overwrites/deutsch/
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "minimumScore": 0.0,
        "name": "",
        "secretKey": "",
        "verifyUrl": ""
    },
    "nodeId": "security.recaptchav3",
    "subshopId": "deutsch"
}
```

#### Error codes

| **Error**        | **Type**                | **Reason**                                                       |
| ---------------- | ----------------------- | ---------------------------------------------------------------- |
| 401 Unauthorized |                         | Not authorized: you are not logged in.                           |
| 403 Forbidden    |                         | You do not have the required permissions to read configurations. |
| 400 Bad Request  | "invalidSelector"       | `{selector}` does not have 2 or 3 parts separated by a `.`.      |
| 400 Bad Request  | "typeInvalid"           | There is no schema with the type from `{selector}`.              |
| 400 Bad Request  | "inappropriateScheme"   | The node is not overwriteable.                                   |
| 404 Not found    | "nodeNotFound"          | The configuration was not found.                                 |
| 404 Not found    | "nodeOverwriteNotFound" | The override was not found.                                      |

### PUT config/nodes/\{selector}/overwrites/\{subshopId}

With this method, a configuration node can be overwritten for a specific subshop. The data in the request body must conform to the schema of the original node. Only nodes with the appropriate property can be overwritten.

If validation fails, the response contains text hints. For example: "The value of the field 'name' has the wrong type. Expected: string.". Errors are also listed in the `errorContext` field.

Possible error types (`errorContext.<field>.type`):

`WrongType`\
`WrongEnumValue`\
`KeyNotAllowed`\
`IsReadOnly`\
`NotUnique`\
`InvalidSelfAssociation`\
`ServiceNotFound`\
`AssociationWrongType`\
`ServiceMissing`\
`AssociationNotFound`\
`ServiceWrongType`\
`TextMissing`

Create permissions for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService/overwrites/english
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    }
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "data": {
        "description": "",
        "label": "Econda Analytics",
        "name": "econda",
        "service": {
            "externalService": {},
            "shopService": null
        }
    },
    "nodeId": "general.consentCookieService",
    "subshopId": "english"
}
```

#### Response when validation failed

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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"
        }
    }
}
```

#### Error codes

| **Error**               | **Type**           | **Reason**                                                                                                                                        |
| ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                    | Not authorized: you are not logged in.                                                                                                            |
| 403 Forbidden           |                    | You do not have the required permissions to create configurations.<br />An attempt was made to update a configuration that belongs to Websale AG. |
| 400 Bad Request         |                    | Request body could not be loaded.                                                                                                                 |
| 400 Bad Request         | "invalidSubshopId" | Subshop was not found.                                                                                                                            |
| 400 Bad Request         | "invalidSelector"  | `{selector}` does not have 2 or 3 parts separated by a `.`.                                                                                       |
| 400 Bad Request         | "typeInvalid"      | There is no schema with the type from `{selector}`.                                                                                               |
| 400 Bad Request         | "overwriteDenied"  | The node must not be overwritten.                                                                                                                 |
| 400 Bad Request         | "invalidParams"    | `data` is missing or has a wrong type. The response contains an `errorContext` object with details.                                               |
| 400 Bad Request         | "dataNotCorrect"   | The data does not conform to the schema. A comment is supplied that states what exactly is wrong.                                                 |
| 409 Conflict            | "alreadyExists"    | Conflict: the override already exists.                                                                                                            |
| 404 Not Found           | "NodeNotFound"     | The node to be overwritten was not found.                                                                                                         |
| 503 Service Unavailable | "internalError"    | Other error. Details can be found in the logs.                                                                                                    |

### DELETE config/nodes/\{selector}/overwrites/\{subshopId}

This method removes the existing override of a configuration node for a specific subshop. If no valid override is found or deletion is not allowed, a corresponding error message is returned.

Delete permissions for configurations are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/config/nodes/general.consentCookieService/overwrites/english
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**        | **Type**             | **Reason**                                                                                                                                        |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                      | Not authorized: you are not logged in.                                                                                                            |
| 403 Forbidden    |                      | You do not have the required permissions to delete configurations.<br />An attempt was made to delete a configuration that belongs to Websale AG. |
| 400 Bad Request  | "invalidSelector"    | `{selector}` does not have 2 or 3 parts separated by a `.`.                                                                                       |
| 400 Bad Request  | "typeInvalid"        | There is no schema with the type from `{selector}`.                                                                                               |
| 400 Bad Request  | "subshopIdMissing"   | `subshopId` was not provided.                                                                                                                     |
| 400 Bad Request  | "unknownOverwriting" | The deletion failed.                                                                                                                              |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.