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.

Inhaltsverzeichnis:

1 1. Unterstützte Methoden
2 2. Datenfelder eine Kategorie (Category Resource)
3 3. Methoden für Kategorien
4 4. Methoden für Produktzuweisung
5 5. Ergänzende Referenzen
6 6. Hinweis zu Kategoriedatenfeldern
7 7. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Kategorien	categories/
Produktzuweisung	categories/{id}/products

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

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"`)
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.<technischer Feldname>	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

{
  "_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"
}

3. Methoden für Kategorien

3.1 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:

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

Antwort:

{
    "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",
            "timestampCreatedAt": "2024-09-17T07:44:56.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:42.000Z"
        },
        ...
    ],
    "nextPageToken": "",
    "totalCount": 7
}

Filterfelder:

parent

Sortierfelder:

Nicht unterstützt

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	"invalidValue"	"stage" ist ungültig. `filter[parent]` hat keinen Wert. `size` ∉ [1;300] `sort` ∉ {"asc", "desc"} `pageToken` ist keine Zahl oder kleiner als 0. Es wird versucht, Kategorien nach einem Feld vom Typ `Liste`, `Map`, `Bild` oder `Video` zu sortieren.
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.

3.2 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:

https://www.<ihr-shop>.de/admin/api/v1/categories/942-53775

Antwort:

{
    "_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",
    "timestampCreatedAt": "2024-09-25T15:03:15.000Z",
    "timestampUpdatedAt": "2024-12-16T14:14:43.000Z"
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Kategorie-Daten.
400 Bad Request	"invalidValue"	"stage" ist ungültig.
404 Not Found		Es gibt keine Kategorie mit `id`=`categoryId`.

3.3 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:

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843

Request Body:

{
    "custom": {
        "robotsNoFollow": true
    },
    "active": "always",
    "descr": "My new description"
}

Antwort:

<updated category as json>

Fehlercodes:

Fehler	Typ	Grund

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.

3.4 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:

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/assign

Request Body:

{
    "categoryIds": [
        "1032-22182",
        "109-30589",
        "105-09206"
    ]
}

Antwort:

{}

Fehlercodes:

Fehler	Typ	Grund

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.

3.5 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:

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/move

Request Body:

{
    "beforeTarget": "1080-40793"
}

Antwort:

{
    "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

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.

3.6 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:

https://www.<ihr-shop>.de/admin/api/v1/categories/1081-68843/setRule

Request Body:

{
    "rule": "[{\"field\":\"name\",\"mode\":\"contains\",\"value\":\"h\"},{\"field\":\"price\",\"mode\":\"lt\",\"value\":\"100\"}]"
}

Antwort:

{
    "count": 167,
    "rebuilt": true
}

Fehlercodes:

Fehler	Typ

Fehler	Typ

API-Referenz Kategorien

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. Datenfelder eine Kategorie (Category Resource)

Zusätzliche Felder:

Beispiel des Datensatzes

3. Methoden für Kategorien

3.1 GET categories

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET categories/{categoryId}

Beispiel:

Antwort:

Fehlercodes:

3.3 PUT categories/{categoryId}

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.4 PUT categories/{categoryId}/assign

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.5 POST categories/{categoryId}/move

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.6 POST categories/{categoryId}/setRule

Beispiel:

Request Body:

Antwort:

Fehlercodes: