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.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
customdes Objekts - Technische Felder zur Strukturabbildung: Dienen der Darstellung der Kategoriestruktur im Shop
Dazu gehören:_parent– ID der übergeordneten Kategorie_children– Liste der untergeordneten KategoriensortValue– technischer Sortierwert zur Bestimmung der tatsächlichen Reihenfolge im Shop
Zusätzliche Felder
Beispiel des Datensatzes
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 Parameterfilter[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
Antwort
Filterfelder
parent
Sortierfelder
Nicht unterstützt
Fehlercodes
GET categories/{categoryId}
Dieser Endpunkt lädt die vollständigen Daten einer einzelnen Kategorie anhand ihrer ID. Optional kann mit dem ParameterwithExternData=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
Antwort
Fehlercodes
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 ParametercreateMissing=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
Request Body
Antwort
Fehlercodes
PUT categories/{categoryId}/assign
Mit diesem Endpunkt können einer bestehenden Kategorie anhand ihrer ID mehrere Unterkategorien zugewiesen werden. Der spezielle WertcategoryId: “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
Request Body
Antwort
Fehlercodes
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
Request Body
Antwort
Fehlercodes
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
Request Body
Antwort
Fehlercodes
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
Request Body
Antwort
Fehlercodes
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
intoTargetwird 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
beforeTargetoderafterTargetwird sie auf derselben Ebene vor oder nach einer vorhandenen Kategorie einsortiert.
Beispiel
Request Body
Antwort
Fehlercodes
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
Antwort
Fehlercodes
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”.
GET categories/{categoryId}/products
Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die einer bestimmten Kategorie anhand ihrer ID zugewiesen sind. Die Parameterfrom 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
Antwort
Filterfelder
nicht unterstützt
Sortierfelder
productId (muss nicht explizit angegeben werden. sort:asc bzw. sort:desc reicht aus)
Fehlercodes
GET categories/products/unassigned
Mit diesem Endpunkt wird eine Liste aller Produkte abgerufen, die aktuell keiner Kategorie zugewiesen sind. Die Parameterfrom 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 textSearchermöglicht eine Textsuche innerhalb der nicht zugewiesenen Produkte.
Für die Nutzung dieses Endpunkts sind Leseberechtigungen für Kategorie-Daten erforderlich.
Beispiel
Antwort
Filterfelder
nicht unterstützt
Sortierfelder
productId (muss nicht explizit angegeben werden.sort:ascbzw.sort:desc reicht aus)
Fehlercodes
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 FeldprodId ü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
Request Body
Antwort
Fehlercodes
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
Request Body
Antwort
Fehlercodes
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
Antwort
Fehlercodes
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 FeldprodId 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
Request Body
Antwort
Fehlercodes
Ergänzende Referenzen
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 Knotencontent.customCategoryField verwendet werden. → 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).