> ## 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-Referenz Kategorien
> Kategorien und Kategoriestrukturen über die Admin Interface API erstellen, abrufen, aktualisieren, löschen und Produkte gezielt zuweisen.
Erstellen, Abrufen und Zuordnen von Kategorien.Der Endpunkt `categories/` stellt Ihnen eine Schnittstelle bereit mit der Sie Kategorie-Daten in unserem Shop-System verwalten können. Mit dieser Schnittstelle können Sie Kategorien abrufen, erstellen, löschen und Produkte Kategorien zuweisen.
***
## Unterstützte Methoden
Angabe aller unterstützten Methoden.
| **Befehl/Info** | **Endpunkte** | **GET** | **PUT** | **POST** | **DELETE** |
| -------------------- | --------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Kategorien** | categories/ | | | | |
| **Produktzuweisung** | | | | | |
## Datenfelder eine Kategorie (Category Resource)
Die Datenfelder einer Kategorie werden in der Konfiguration verwaltet und intern als JSON-Objekt gespeichert.\
Es wird zwischen folgenden Feldtypen unterschieden:
* Standardfelder: Vom System vorgegeben und immer vorhanden (z. B. `id`, `name`, `descr`, `hidden`)
* Benutzerdefinierte Felder: Können flexibel angelegt werden und befinden sich im Abschnitt `custom` des Objekts
* Technische Felder zur Strukturabbildung: Dienen der Darstellung der Kategoriestruktur im Shop\
Dazu gehören:
* `_parent` – ID der übergeordneten Kategorie
* `_children` – Liste der untergeordneten Kategorien
* `sortValue` – technischer Sortierwert zur Bestimmung der tatsächlichen Reihenfolge im Shop
| **Name** | **Typ** | **Bedeutung** |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| **id** | String | Eindeutige ID der Kategorie |
| **name** | String | Anzeigename der Kategorie |
| **descr** | String | Beschreibungstext (z. B. zur Anzeige im Frontend) |
| **active** | String | Aktivitätsstatus (`"always"`, `"never"`, `"test"` (aktiv nur im Testmodus)) |
| **productAssignmentType** | String | Art der Produktzuweisung (`"manual", "ruleBased", "handUp"`) |
| **productRules** | String | Geparstes Objekt, das Regeln für Produktzuweisung enthält |
| **hidden** | Boolean | Gibt an, ob die Kategorie im Frontend ausgeblendet werden soll |
| **timestampCreatedAt** | String | Zeitpunkt, zu dem die Kategorie erstellt wurde (ISO 8601-Format, UTC). |
| **timestampUpdatedAt** | String | Zeitpunkt, der letzten Änderung (ISO 8601-Format, UTC). |
| **custom** | Objekt | Objekt für benutzerdefinierte Felder |
| **custom.\** | Benutzerdefiniert | Benutzerdefiniertes Feld, frei definierbar über die Konfiguration (z. B. `image`, `seoName`, `robotsNoIndex` etc.) |
#### Zusätzliche Felder
| | | |
| -------------- | ----------------- | --------------------------------------------------------- |
| **\_parent** | String | ID der übergeordneten Kategorie (leer bei Hauptkategorie) |
| **\_children** | Array von Strings | Liste der IDs untergeordneter Kategorien |
| **sortValue** | Int | Position der Kategorie in dem Shop |
#### Beispiel des Datensatzes
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"_children": [
"107-06636",
"108-64674"
],
"_parent": "",
"active": "always",
"custom": {
"alternativeTemplate": "",
"image": [],
"robotsNoFollow": false,
"robotsNoIndex": false,
"seoName": ""
},
"descr": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, ...",
"hidden": false,
"id": "100-14213",
"name": "Bekleidung",
"productAssignmentType": "manual",
"productRules": "[{\"field\":\"active\",\"mode\":\"eq\",\"value\":\"always\"},{\"field\":\"itemNumber\",\"mode\":\"contains\",\"value\":\"5\"}]",
"sortValue": 62,
"timestampCreatedAt": "2024-01-10T13:36:31.000Z",
"timestampUpdatedAt": "2024-09-26T10:41:54.000Z"
}
```
## Methoden für Kategorien
### GET categories
Dieser Endpunkt liefert eine Liste von Kategorien aus dem Shopsystem.
Eine Sortierung, Textsuche oder komplexe Filterung ist derzeit nicht möglich. Es kann jedoch gezielt nach Unterkategorien einer bestimmten Kategorie gefiltert werden, indem der Parameter `filter[parent]` verwendet wird.
Wird `parent=root` gesetzt, werden alle Hauptkategorien der obersten Ebene zurückgegeben.
Durch den Parameter `withExternData=yes` können zusätzlich die IDs der übergeordneten Kategorie (`_parent`) sowie der untergeordneten Kategorien (`_children`) mitgeladen werden.
Mit `subshopId` lassen sich die Kategorien eines bestimmten Subshops abfragen.
Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": [
{
"_children": [],
"_parent": "372-87532",
"active": "never",
"custom": {
"alternativeTemplate": "",
"image": [],
"metaDescription": "",
"metaDescriptionSetManually": false,
"metaTitle": "",
"metaTitleSetManually": false,
"regger": "",
"robotsNoFollow": false,
"robotsNoIndex": false,
"seoName": ""
},
"descr": "test",
"hidden": false,
"id": "245-10358",
"name": "Neue Kategorie",
"productAssignmentType": "manual",
"productRules": "",
"sortValue": 42,
"timestampCreatedAt": "2024-09-17T07:44:56.000Z",
"timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
},
...
],
"endReached": true,
"nextPageToken": "",
"totalCount": 7
}
```
#### Filterfelder
`parent`
#### Sortierfelder
`Nicht unterstützt`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "invalidCombination" | `pageToken` und `from` sind gleichzeitig gesetzt. |
| 400 Bad Request | "illegalOperation" | Es wird versucht, Kategorien nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu filtern.
Eine ungültige Filteroperation wurde auf ein Enum-Feld angewendet – nur `=` oder `≠` sind erlaubt. |
| 400 Bad Request | "unknownDataField" | Ein Filter- oder Sortierfeld ist ungültig. |
| 400 Bad Request | "unknownOperation" | Ein Filtertyp ist ungültig. |
| 400 Bad Request | "invalidCharacters" | `size` ist keine Ganzzahl.
Ein Filterwert ist ungültig. |
| 400 Bad Request | "syntaxError" | `sort` enthält mehr als einen oder keinen ":". |
| 404 Not Found | | Die übergeordnete Kategorie wurde nicht gefunden. |
### GET categories/\{categoryId}
Dieser Endpunkt lädt die vollständigen Daten einer einzelnen Kategorie anhand ihrer ID.
Optional kann mit dem Parameter `withExternData=yes` zusätzlich die ID der übergeordneten Kategorie (`_parent`) sowie die Liste aller direkt untergeordneten Kategorien (`_children`) mitgeliefert werden.
Für die Nutzung des Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/942-53775
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"_children": [],
"_parent": "",
"active": "always",
"custom": {
"alternativeTemplate": "",
"image": [],
"metaDescription": "",
"metaDescriptionSetManually": false,
"metaTitle": "",
"metaTitleSetManually": false,
"regger": "",
"robotsNoFollow": false,
"robotsNoIndex": false,
"seoName": ""
},
"descr": "123",
"hidden": false,
"id": "942-53775",
"name": "Neue Kategorie",
"productAssignmentType": "manual",
"productRules": "",
"sortValue": 42,
"timestampCreatedAt": "2024-09-25T15:03:15.000Z",
"timestampUpdatedAt": "2024-12-16T14:14:43.000Z"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 404 Not Found | | Es gibt keine Kategorie mit `id`=`categoryId`. |
### PUT categories/\{categoryId}
Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID aktualisiert werden.
Der Request-Body muss nur die Felder enthalten, die tatsächlich geändert werden sollen – eine vollständige Kategorie-Definition ist nicht erforderlich.
Wird der optionale Parameter `createMissing=yes` gesetzt und existiert keine Kategorie mit der angegebenen ID, wird stattdessen eine neue Kategorie mit dieser ID angelegt.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/1081-68843
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"custom": {
"robotsNoFollow": true
},
"active": "always",
"descr": "My new description"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "always",
"custom": {
"alternativeTemplate": "",
"image": [],
...
},
"descr": "My new description",
"hidden": false,
"id": "1081-68843",
"name": "Bekleidung",
"productAssignmentType": "manual",
"productRules": "",
"timestampCreatedAt": "2024-01-10T13:36:31.000Z",
"timestampUpdatedAt": "2025-05-02T14:22:10.000Z"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. Ein Feld vom Typ `Enumeration` enthält einen Wert, der nicht in der Menge von möglichen Werten enthalten ist. Ein Bild hat einen Format, der nicht unterstützt wird. |
| 400 Bad Request | "invalidFormat" | `custom` ist kein Objekt. Ein Feld enthält den Wert `null`. Ein Wert hat den Typ, der mit dem Typ aus der Konfiguration nicht übereinstimmt. Ein Preis-Wert kann nicht geparst werden. Ein Feld vom Typ `Map` hat einen Schlüssel, der kein String ist. Ein Feld vom Typ `List` ist kein Array von Strings. Ein Zeitwert ist nicht in ISO 8601 Format. Bild-Daten von einem Bild sind kein Array von Objekten. `id` des Formats oder `path` sind keine Strings. |
| 400 Bad Request | "unknownDataField" | Es wird versucht, ein unbekanntes Feld zu aktualisieren. Bild-Daten enthalten etwas außer `id` und `path`. |
| 400 Bad Request | "notManualEditable" | In der Konfiguration wurde manuelles Bearbeiten verboten. |
| 404 Not Found | | Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden und der Parameter `createMissing` ist nicht auf `yes` gesetzt. |
| 503 Service Unavailable | "internalError" | Die Aktualisierung ist fehlgeschlagen. |
### PUT categories/\{categoryId}/assign
Mit diesem Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Unterkategorien zugewiesen werden.
Der spezielle Wert `categoryId`: "root" sorgt dafür, dass die Kategorien als **Hauptkategorien** auf die oberste Ebene kommen.
Im Request-Body muss ein Array von Kategorie-IDs übergeben werden, die der angegebenen Kategorie als untergeordnet (`_children`) zugeordnet werden sollen.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/1081-68843/assign
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"categoryIds": [
"1032-22182",
"109-30589",
"105-09206"
]
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 404 Not Found | | Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden. |
| 400 Bad Request | "unknownDataField" | Es wurde etwas außer `categoryIds` übergeben. |
| 400 Bad Request | "invalidFormat" | `categoryIds` ist kein Array von Strings. |
### POST categories/\{categoryId}/move
Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID innerhalb der Kategoriestruktur verschoben werden.
Die Positionierung erfolgt entweder durch Einordnung als Unterkategorie (`intoTarget`) oder durch Sortierung auf derselben Ebene (`beforeTarget` oder `afterTarget`). Es darf nur einer dieser Zielparameter gesetzt sein.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/1081-68843/move
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"beforeTarget": "1080-40793"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "never",
"custom": {
"alternativeTemplate": "",
"defaultSort": "",
"image": [],
"metaDescription": "",
"metaDescriptionSetManually": false,
"metaTitle": "",
"metaTitleSetManually": false,
"robotsNoFollow": false,
"robotsNoIndex": false,
"seoName": "",
"video": ""
},
"descr": "test",
"hidden": false,
"id": "1081-68843",
"name": "Neue Kategorie",
"productAssignmentType": "manual",
"productRules": "",
"timestampCreatedAt": "2025-05-02T13:59:38.000Z",
"timestampUpdatedAt": "2025-05-02T13:59:38.000Z"
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig.
Die neue Position ist in einer Unterkategorie der Kategorie, die verschoben werden soll. |
| 400 Bad Request | "missing" | Es fehlt ein Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`). |
| 400 Bad Request | "invalidFormat" | `intoTarget`, `beforeTarget` oder `afterTarget` sind keine Strings. |
| 400 Bad Request | "unknownDataField" | Request body enthält etwas außer `intoTarget`, `beforeTarget`, `afterTarget`. |
| 400 Bad Request | "invalidCombination" | Mehrere Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`) können nicht gleichzeitig gesetzt werden. |
| 404 Not Found | | Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden.
"Target" enthält keine gültige Id. |
### POST categories/\{categoryId}/setRule
Mit diesem Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Produkte zugewiesen werden.
Im Request-Body muss ein als JSON serialisiertes Array von Regeln übergeben werden. Produkte, auf die die Regeln zutreffen, werden der Kategorie zugewiesen.
`rebuilt` in der Antwort gibt an, ob die Regel sofort angewendet werden konnte. Wenn der Wert `false` ist, wird es später erneut versucht – der Endpunkt muss dafür nicht erneut getriggert werden.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/1081-68843/setRule
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"rule": "[{\"field\":\"name\",\"mode\":\"contains\",\"value\":\"h\"},{\"field\":\"price\",\"mode\":\"lt\",\"value\":\"100\"}]"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"count": 167,
"rebuilt": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden.
Die Regel funktioniert nicht.
Diese Regel trifft auf zu viele Produkte zu. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 404 Not Found | | Die Kategorie mit `id`=`{categoryId}` wurde nicht gefunden. |
| 400 Bad Request | "invalidFormat" | `rule` ist kein String. |
| 400 Bad Request | "unknownDataField" | Request body enthält etwas außer `rule`. |
### POST categories/rebuildRules
Dieser Endpunkt aktualisiert Produkte in Kategorien mit regelbasierter Produktzuweisung.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/rebuildRules
```
#### Request Body
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ----------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 503 Service Unavailable | "internalError" | Die interne URL des Rebuilder-Programms ist nicht gesetzt.
Das Rebuilder-Programm konnte nicht gestartet werden. |
### POST categories
Mit diesem Endpunkt kann eine neue Kategorie im Shop-System erstellt werden.\
Über die optionalen Parameter `intoTarget`, `beforeTarget` oder `afterTarget` lässt sich festlegen, wo die neue Kategorie in der Kategoriestruktur einsortiert werden soll:
* Mit `intoTarget` wird sie als Unterkategorie einer bestehenden Kategorie angelegt.
* Der spezielle Wert `intoTarget: "root"` sorgt dafür, dass die neue Kategorie als **Hauptkategorie** auf der obersten Ebene erstellt wird.
* Mit `beforeTarget` oder `afterTarget` wird sie auf derselben Ebene vor oder nach einer vorhandenen Kategorie einsortiert.
Es darf jeweils nur ein Zielparameter gesetzt sein.
Für die Nutzung dieses Endpunkts sind Erstellberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "Neue Kategorie",
"intoTarget": "root"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "never",
"custom": {
"alternativeTemplate": "",
"image": [],
"metaDescription": "",
"metaDescriptionSetManually": false,
"metaTitle": "",
"metaTitleSetManually": false,
...
},
"descr": "",
"hidden": false,
"id": "1080-40793",
"name": "Neue Kategorie",
"productAssignmentType": "manual",
"productRules": "",
"timestampCreatedAt": "",
"timestampUpdatedAt": ""
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig.
"Target" enthält keine gültige Id.
Ein Feld vom Typ `Enumeration` enthält einen Wert, der nicht in der Menge von möglichen Werten enthalten ist.
Ein Bild hat einen Format, der nicht unterstützt wird. |
| 400 Bad Request | "invalidCombination" | Mehrere Target-Parameter (`intoTarget`, `beforeTarget`, `afterTarget`) können nicht gleichzeitig gesetzt werden. |
| 400 Bad Request | "invalidFormat" | `custom` ist kein Objekt.
Ein Feld enthält den Wert `null`.
Ein Wert hat den Typ, der mit dem Typ aus der Konfiguration nicht übereinstimmt.
Ein Preis-Wert kann nicht geparst werden.
Ein Feld vom Typ `Map` hat einen Schlüssel, der kein String ist.
Ein Feld vom Typ `List` ist kein Array von Strings.
Ein Zeitwert ist nicht in ISO 8601 Format.
Bild-Daten von einem Bild sind kein Array von Objekten.
`id` des Formats oder `path` sind keine Strings. |
| 400 Bad Request | "unknownDataField" | Es wird versucht, ein unbekanntes Feld zu aktualisieren.
Bild-Daten enthalten etwas außer `id` und `path`. |
| 400 Bad Request | "notManualEditable" | In der Konfiguration wurde manuelles Bearbeiten verboten. |
### DELETE categories/\{categoryId}
Mit diesem Endpunkt kann eine bestehende Kategorie anhand ihrer ID gelöscht werden.\
Dabei werden nicht nur die gewählte Kategorie selbst, sondern auch alle zugehörigen Unterkategorien aus dem System entfernt.
Für die Nutzung dieses Endpunkts sind Löschberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/1081-68843
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 404 Not Found | | Die Kategorie wurde nicht gefunden. |
## Methoden für Produktzuweisung
### Technische Limits
Produkte können Kategorien manuell, regelbasiert oder über die Unterkategorien zugewiesen werden:
* **Manuelle Zuweisung** bedeutet, dass bestimmte Produkte gezielt einzelnen Kategorien zugeordnet werden (z. B. „Produkt A gehört zu Kategorie B“).
* **Regelbasierte Zuweisung** erlaubt es, Kategorien automatisch mit Produkten zu befüllen, die bestimmte Kriterien erfüllen (z. B. „alle reduzierten Produkte“ oder „alle Produkte mit Lagerbestand > 0“).
* **Produkte von Unterkategorien übernehmen**, hiermit werden Kategorien automatisch mit allen Produkten befüllt, die den direkten Unterkategorien zugewiesen sind. Z. B. die Kategorie "Damen" enthält alle Produkte aus den Unterkategorien "Damenblusen" und "Damenröcke".
Bei regelbasierten Kategorien ist die **maximale Anzahl an zugewiesenen Produkten technisch auf 1.000 Ergebnisse begrenzt**, unabhängig von der Anzahl der Produkte im Shop oder von der formulierten Regel.
Wenn Produkte über mehrere Hierarchie-Ebenen übernommen werden sollen, müssen alle Kategorieebenen ihre Produkte ebenfalls aus den Unterkategorien übernehmen. Andernfalls werden nur die Produkte der direkten Unterkategorie übernommen, aber nicht die Produkte deren Kinder.
Beispiel:
```
|-Kategorie A (Produkte von Unterkategorien übernehmen)
| |-Kategorie B (Manuell)
| | |-Kategorie C (Manuell)
| |-Kategorie D (Produkte von Unterkategorien übernehmen)
| | |-Kategorie E (Regelbasiert)
| | |-Kategorie F (Manuell)
| |- Kategorie G (Regelbasiert)
```
Kategorie A bekommt alle Produkte aus den Kategorien B, D, E, F und G zugeordnet. Die Produkte aus Kategorie C werden Kategorie A jedoch nicht zugeordnet, da die Produktzuweisung für Kategorie B "Manuell" ist und nicht "Produkte von Unterkategorien übernehmen".
### GET categories/\{categoryId}/products
Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die einer bestimmten Kategorie anhand ihrer ID zugewiesen sind.
Die Parameter `from` und `size` dienen der Aufteilung großer Ergebnismengen in Seiten – damit die API nicht z. B. 10.000 Produkte auf einmal übertragen muss. `from` gibt an, wie viele Einträge am Anfang übersprungen werden, `size` bestimmt die maximale Anzahl der zurückgegebenen Produkte.
Zusätzlich kann mit dem optionalen Parameter `textSearch` eine Textsuche innerhalb der zugewiesenen Produkte durchgeführt werden.
Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/105-09206/products?from=0&size=50
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"active": "never",
"custom": {
"brand": "",
"commission": 0,
"commissionTaxRate": "",
...
},
"descr": "SUPER COOL PRODUCT",
"id": "100-41232",
"itemNumber": "999999999",
"name": "Something",
"price": "0.000000",
"taxRateId": "7",
"timestampCreatedAt": "2024-09-11T09:01:15.000Z",
"timestampUpdatedAt": "2024-12-16T14:20:41.000Z"
},
...
],
"totalCount": 8
}
```
#### Filterfelder
`nicht unterstützt`
#### Sortierfelder
`productId` (muss nicht explizit angegeben werden. `sort:asc` bzw. `sort:desc` reicht aus)
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "syntaxError" | `sort` enthält mehr als einen oder keinen ":". |
### GET categories/products/unassigned
Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die aktuell keiner Kategorie zugewiesen sind.
Die Parameter `from` und `size` dienen der Aufteilung großer Ergebnismengen in Seiten – damit die API nicht z. B. 10.000 Produkte auf einmal übertragen muss. `from` gibt an, wie viele Einträge am Anfang übersprungen werden, `size` bestimmt die maximale Anzahl der zurückgegebenen Produkte.
Der optionale Parameter `textSearch`ermöglicht eine Textsuche innerhalb der nicht zugewiesenen Produkte.
Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/products/unassigned?from=0&size=50
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"active": "never",
"custom": {
"brand": "",
"commission": 0,
"commissionTaxRate": "",
...
},
"descr": "",
"id": "124-28218",
"itemNumber": "",
"name": "Neues Produkt",
"price": "0.000000",
"taxRateId": "",
"timestampCreatedAt": "2024-09-26T10:50:23.000Z",
"timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
},
...
],
"totalCount": 15
}
```
#### Filterfelder
`nicht unterstützt`
#### Sortierfelder
`productId (muss nicht explizit angegeben werden.`sort:asc`bzw.`sort:desc` reicht aus)`
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | |
| 400 Bad Request | "syntaxError" | `sort` enthält mehr als einen oder keinen ":". |
### POST categories/\{categoryId}/products/assign
Mit diesem Endpunkt können ein oder mehrere Produkte anhand ihrer Produkt-IDs einer bestimmten Kategorie anhand ihrer Kategorie-ID zugewiesen werden.
Die Produkt-IDs werden im Feld `prodId` übergeben – entweder als String (ein einzelnes Produkt) oder als Array von Strings (mehrere Produkte).
Optional kann mit den Parametern `beforeTarget` oder `afterTarget` festgelegt werden, an welcher Position innerhalb der Kategorie die Produkte einsortiert werden sollen. Beide dürfen nicht gleichzeitig gesetzt sein.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/105-09206/products/assign
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"prodId": [
"111-28077",
"110-64564"
]
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 400 Bad Request | "invalidFormat" | `prodId` ist kein Array von Strings und kein String.
`beforeTarget` oder `afterTarget` sind keine Strings. |
| 400 Bad Request | "unknownDataField" | Ein anderes Feld außer `prodId`, `beforeTarget` oder `afterTarget` wurde übergeben. |
| 400 Bad Request | "missing" | Keine Produkt-ID wurde übergeben. |
| 404 Not Found | "missingCategory" | Die Kategorie wurde nicht gefunden. |
| 404 Not Found | "missingTarget" | Die Position innerhalb der Kategorie ist ungültig. |
| 409 Conflict | "multipleTargets" | `beforeTarget` und `afterTarget` wurden gleichzeitig gesetzt. |
| 409 Conflict | "entityNotFound" | Man versucht, ein Produkt, das nicht existiert, zuzuweisen. |
### POST categories/\{categoryId}/products/swap
Dieser Endpunkt ermöglicht es, die Position von zwei Produkten innerhalb einer bestimmten Kategorie zu tauschen. Die Produkt-IDs werden im Request-Body übergeben. Die Antwort gibt zurück, ob der Tausch erfolgreich durchgeführt werden konnte.
Für die Nutzung dieses Endpunkts sind Schreibrechte für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/105-09206/products/swap
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"productId1": "111-28077",
"productId2": "110-64564"
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 400 Bad Request | "invalidFormat" | `productId1` oder `productId2` sind keine Strings. |
| 400 Bad Request | "missing" | `productId1` oder `productId2` fehlen. |
| 400 Bad Request | "unknownDataField" | Ein unbekanntes Feld wurde übergeben. |
| 404 Not Found | "missingCategory" | Die Kategorie wurde nicht gefunden. |
### DELETE categories/\{categoryId}/products/\{productId}
Mit diesem Endpunkt wird ein Produkt anhand seiner ID aus einer bestimmten Kategorie anhand ihrer ID entfernt.
Dadurch wird die Verknüpfung zwischen Produkt und Kategorie aufgehoben – das Produkt bleibt im System bestehen, ist jedoch nicht mehr dieser Kategorie zugeordnet.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/105-09206/products/123456
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 404 Not Found | "missingCategory" | Die Kategorie wurde nicht gefunden. |
| 404 Not Found | "missingProduct" | Das Produkt wurde nicht gefunden. |
### DELETE categories/\{categoryId}/products/
Mit diesem Endpunkt können mehrere Produkte gleichzeitig aus einer bestimmten Kategorie anhand ihrer ID entfernt werden.
Die zu entfernenden Produkt-IDs werden im Feld `prodId` als Array übergeben.\
Dadurch wird die Zuordnung der Produkte zur angegebenen Kategorie aufgehoben – die Produkte selbst bleiben im System erhalten.
Für die Nutzung dieses Endpunkts sind Schreibberechtigungen für Kategorie-Daten erforderlich.
#### Beispiel
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/categories/105-09206/products/
```
#### Request Body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"prodId": [
"111-28077",
"110-64564"
]
}
```
#### Antwort
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Fehlercodes
| **Fehler** | **Typ** | **Grund** |
| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized | | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Kategorie-Daten. |
| 400 Bad Request | | Request body konnte nicht geladen werden. |
| 400 Bad Request | "invalidValue" | "stage" ist ungültig. |
| 400 Bad Request | "invalidFormat" | Ein Produktindex ist kein String. `prodId` ist kein Array. |
| 400 Bad Request | "unknownDataField" | Ein anderes Feld außer `prodId` wurde übergeben. |
| 400 Bad Request | "missing" | `prodId` fehlt. |
| 404 Not Found | "missingCategory" | Die Kategorie wurde nicht gefunden. |
### Ergänzende Referenzen
* [API-Referenz Produkte](/schnittstellen/admin-interface-api/api-referenz-produkte)
* [API-Referenz Konfiguration](/schnittstellen/admin-interface-api/api-referenz-konfiguration)
* [content - Katalog (Kategorien & Produkte)](/konfiguration/content-katalog-kategorien-produkte)
### Hinweis zu Kategoriedatenfeldern
Neue Kategoriedatenfelder (zusätzliche Beschreibungen, Bilder etc.) können nicht direkt über die Kategorie-API erstellt werden. Die API dient ausschließlich dem Auslesen und Pflegen vorhandener Felder.
Um neue Felder zu definieren, muss die Konfiguration im Knoten `content.customCategoryField` verwendet werden. → [content - Katalog (Kategorien & Produkte)](/konfiguration/content-katalog-kategorien-produkte)
Dort lassen sich individuelle Felder. Sobald ein Feld dort konfiguriert wurde, steht es anschließend automatisch in der Produkt-API zur Verfügung (z. B. in `GET categories` oder `POST categories`).
## 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.