Storefront API Katalog - WEBSALE Dokumentation

Die Katalog API stellt die zentralen Informationen für Produkte und Kategorien bereit und bildet damit die Grundlage für Produktdetailseiten, Kategorieseiten und Navigationselemente. Sie liefert Standardattribute (z. B. Name, Beschreibung, Preis), ergänzt um individuelle Produkt- und Kategorieattribute sowie SEO-Informationen wie Meta-Daten und sprechende URLs. Zusätzlich können Kategoriestrukturen (Hierarchien, Unterkategorien, Verknüpfungen) abgerufen werden, ebenso einzelne Produkte/Kategorien oder Produktlisten im Kontext einer Kategorie. Funktionen für Suchergebnisse und Kategorieseiten – etwa Filter, Sortierung, Paging oder die Anzahl der Produkte pro Seite – werden nicht über die Katalog API bereitgestellt. Diese Aufgaben übernimmt das separate Modul WEBSALE search und die Einbindung kann entweder über die entsprechenden WEBSALE WebComponents oder die Search API erfolgen.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
Produktdetails zu einem Artikel abrufen	`catalog/product/load`
Produktdetails zu mehreren Artikeln abrufen	`catalog/product/loadList`
Varinanten-Informationen zu einem Produkt abrufen	`catalog/product/variantInfo`
Alle Kategorien laden, in denen ein bestimmtes Produkt vorkommt	`catalog/product/categoryMembership`
Kategoriepfade laden, in denen ein bestimmtes Produkt vorkommt	`catalog/product/categoryMembershipPaths`
Liste aller verfügbaren Produktfelder laden	`catalog/product/fields`
Liste aller verfügbaren benutzerdefinierten Produktfelder laden	`catalog/product/customFields`
Details einer Kategorie laden	`catalog/category/load`
Unterkategorie einer Kategorie laden	`catalog/category/loadChildren`
Kompletten Pfad bis zur Kategorie laden	`catalog/category/path`
Produktliste für eine angegebene Kategorie laden	`catalog/category/products`
Liste aller verfügbaren Kategoriefelder laden	`catalog/category/fields`
Liste aller benutzerdefinierten Kategoriefelder laden	`catalog/category/customFields`

Methoden für Produkte

Mithilfe dieser Methoden werden Produktinformationen für die Storefront bereitgestellt. Dabei werden die Detaildaten eines einzelnen Artikels (inklusive konfigurierbarer Produktfelder und ggf. Custom-Felder) geladen und ergänzend Varianteninformationen (z. B. auswählbare Attribute und zugehörige Variantenartikel) geliefert. Darüber hinaus können alle Kategorien und Kategoriepfade ermittelt werden, in denen ein Produkt geführt wird, beispielsweise für Breadcrumbs, Kachel-Teaser oder Filter. Über eigene Endpunkte wird zudem die vollständige Liste aller standardisierten und benutzerdefinierten Produktfelder zurückgegeben. Somit können Suche, Filter, Detailseiten und Integrationen (z. B. ERP-/PIM-Anbindung) dynamisch auf der tatsächlich im Shop konfigurierten Datenstruktur aufbauen.

GET catalog/product/load

Folgender Aufruf lädt die Produktdetails zu einem Artikel: Welche Felder im Response erscheinen, lässt sich in der Katalog-Konfiguration steuern: storefrontApi - Storefront-API. Dies ist zum Anzeigen einer Produktdetailseite oder zum gezielten Nachladen von Produktinfos verwendbar. Ist die Ausgabe von Produkt- beziehungsweise Kategoriedaten in der Konfiguration abgeschaltet (enableProductDataEndpoint beziehungsweise enableCategoryDataEndpoint), antwortet der Endpunkt mit HTTP 200 und dem Body null. Prüfen Sie den Body deshalb auf null, bevor Sie Felder auslesen. Beispiel-Aufruf, der die Produktdetails für das Produkt mit der ID 146-78608 lädt:

GET https://<ihr-shop>.de/api/v1/catalog/product/load?productId=146-78608

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld* Produkt-ID des Artikels.
`itemNumber`	string	Pflichtfeld* Produktnummer (SKU) des Artikels.
`customNumber`	string	Pflichtfeld* Eine frei vergebene Artikelkennung (z.B. ERP-ID oder Marketing-Nummer).

*Es muss genau einer der drei Parameter übergeben werden.

Beispiel-Response

{
  "custom": {
    "image": {},
    "setOrgPrice": 0.0
  },
  "id": "146-78608",
  "name": "Plushie",
  "price": 6.7,
  "setOrgPrice": 0.0
}

Benutzerdefinierte Felder liefert der Response gesammelt im Objekt custom. Felder vom Typ MultiFormatImage (in den Beispielen das Feld image) werden als Objekt zurückgegeben. Ein solches Feld speichert ein Bild in mehreren Formaten. Die Formate legen Sie im Admin Interface im Service Bildkonverter fest. Den Typ eines Feldes fragen Sie über catalog/product/customFields ab. Wie Sie Bildfelder in Frontend-Templates je Format ausgeben, beschreibt WSProducts: Produktbilder. Bild-URLs können Sie außerdem über die API-Referenz Bildkonverter der Admin Interface API abfragen.

GET catalog/product/loadList

Folgender Aufruf lädt die Produktdetails zu mehreren Artikeln: Welche Felder im Response erscheinen, lässt sich in der Katalog-Konfiguration steuern: storefrontApi - Storefront-API. Dies ist zum effizienten Anzeigen mehrer Produkte auf einer Kategorieseite verwendbar. Ist die Ausgabe von Produkt- beziehungsweise Kategoriedaten in der Konfiguration abgeschaltet (enableProductDataEndpoint beziehungsweise enableCategoryDataEndpoint), antwortet der Endpunkt mit HTTP 200 und dem Body null. Prüfen Sie den Body deshalb auf null, bevor Sie Felder auslesen. Beispiel-Aufruf, der die Produktdetails für die Produkte mit der ID 146-78608 und 147-3720 lädt:

GET https://<ihr-shop>.de/api/v1/catalog/product/loadList?productId=146-78608&productId=147-3720

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld* Produkt-ID des Artikels.
`itemNumber`	string	Pflichtfeld* Produktnummer (SKU) des Artikels.
`customNumber`	string	Pflichtfeld* Eine frei vergebene Artikelkennung (z.B. ERP-ID oder Marketing-Nummer).

*Es können nur Parameter eines Typs (productId, itemNumber, customNumber) übergeben werden. Es können beliebig viele Parameter eines Typs angegeben werden.

Beispiel-Response

[
  {
    "custom": {
      "image": {},
      "setOrgPrice": 0.0
    },
    "id": "146-78608",
    "name": "Plushie",
    "price": 6.7,
    "setOrgPrice": 0.0
  },
  {
    "custom": {
      "image": {},
      "setOrgPrice": 0.0
    },
    "id": "147-3720",
    "name": "Stift",
    "price": 3.7,
    "setOrgPrice": 0.0
  }
]

GET catalog/product/variantInfo

Der folgende Aufruf liefert die Varianteninformationen zu einem Produkt. Er kann beispielsweise zum Aufbau des Varianten-Selectors auf der Produktseite verwendet werden. Beispiel-Aufruf, der die Varianteninformationen zum Produkt mit der ID 146-78608 lädt:

GET https://<ihr-shop>.de/api/v1/catalog/product/variantInfo?productId=146-78608

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produktes, dessen Varianten geladen werden sollen.

Beispiel-Response

{
  "numVariants": 2,
  "variantAttributes": [
    {
      "name": "Arbeitsspeicher",
      "options": [
        {
          "name": "128 GB",
          "resolvedVariant": {
            "base": {
              "base": null,
              "custom": { "image": {}, "setOrgPrice": 0.0 },
              "id": "146-78608",
              "name": "Plushie",
              "price": 6.7,
              "setOrgPrice": 0.0
            },
            "custom": { "image": {}, "setOrgPrice": 0.0 },
            "id": "146-78608.1",
            "name": "Plushie",
            "price": 6.7,
            "setOrgPrice": 0.0
          }
        },
        { "name": "512 GB" }
      ]
    }
  ]
}

GET catalog/product/categoryMembership

Mit folgendem Aufruf werden alle Kategorien ausgegeben, in denen ein bestimmtes Produkt aktuell einsortiert ist. Er kann für Breadcrumbs verwendet werden oder dazu, die Produktnavigation/Filter vorzubelegen. Beispiel-Aufruf, der alle Kategorien ausgibt, in denen das Produkt mit der ID 147-15732 einsortiert ist:

GET https://<ihr-shop>.de/api/v1/catalog/product/categoryMemberships?productId=147-15732

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produktes, dessen Kategoriezugehörigkeiten geladen werden sollen.

Beispiel-Response

[
  {
    "custom": { "image": {} },
    "id": "135-98530",
    "name": "Coole Dinge"
  },
  {
    "custom": { "image": {} },
    "id": "104-40827",
    "name": "Sale"
  }
]

GET catalog/product/categoryMembershipPaths

Mit dem folgenden Aufruf werden alle vollständigen Kategoriepfade (von der Wurzel zur Zielkategorie) geliefert, in denen ein bestimmtes Produkt vorkommt. Er kann für Breadcrumbs, die SEO-Navigation oder die Anzeige alternativer Pfade eines Produkts genutzt werden. Beispiel-Aufruf, der die vollständigen Kategoriepfade für das Produkt mit der ID 147-15732 anzeigt:

GET https://<ihr-shop>.de/api/v1/catalog/product/categoryMembershipPaths?productId=147-15732

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produktes, dessen Kategoriezugehörigkeiten geladen werden sollen.

Beispiel-Response

Zurückgegeben wird ein Array. Jedes Element ist ein vollständiger Kategoriepfad, also selbst ein Array von Kategorieobjekten von der Wurzel bis zur Zielkategorie. Ist das Produkt in keiner Kategorie einsortiert, ist das äußere Array leer.

[
  [
    { "custom": { "image": {} }, "id": "135-98530", "name": "Coole Dinge" },
    { "custom": { "image": {} }, "id": "100-14213", "name": "Bekleidung" }
  ],
  [
    { "custom": { "image": {} }, "id": "104-40827", "name": "Sale" }
  ]
]

GET catalog/product/fields

Der folgende Aufruf listet alle im System verfügbaren Standard-Produktfelder inklusive ihrer Metadaten. Er kann zum Aufbau von Produktseiten oder zur Anpassung von Such- und Filterfunktionen verwendet werden.

GET https://<ihr-shop>.de/api/v1/catalog/product/fields

Parameterübersicht

Parameter	Typ	Beschreibung
—	—	Keine zusätzlichen Parameter.

Beispiel-Response

[
  {
    "dataId": "active",
    "label": "",
    "manualEditable": true,
    "name": "active",
    "nodeId": "content.productField.active",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": true,
    "type": "Enumeration"
  },
  {
    "dataId": "descr",
    "label": "",
    "manualEditable": true,
    "name": "descr",
    "nodeId": "content.productField.descr",
    "protectedField": false,
    "required": false,
    "searchBoost": 2,
    "searchable": true,
    "type": "Text"
  },
  {
    "dataId": "id",
    "label": "",
    "manualEditable": false,
    "name": "id",
    "nodeId": "content.productField.id",
    "protectedField": false,
    "required": true,
    "searchBoost": 2,
    "searchable": true,
    "type": "Text"
  },
  {
    "dataId": "itemNumber",
    "label": "",
    "manualEditable": true,
    "name": "itemNumber",
    "nodeId": "content.productField.itemNumber",
    "protectedField": false,
    "required": true,
    "searchBoost": 2,
    "searchable": true,
    "type": "Text"
  },
  {
    "dataId": "name",
    "label": "",
    "manualEditable": true,
    "name": "name",
    "nodeId": "content.productField.name",
    "protectedField": false,
    "required": true,
    "searchBoost": 6,
    "searchable": true,
    "type": "Text"
  },
  {
    "dataId": "price",
    "label": "",
    "manualEditable": true,
    "name": "price",
    "nodeId": "content.productField.price",
    "protectedField": false,
    "required": true,
    "searchBoost": 1,
    "searchable": false,
    "type": "Price"
  }
]

GET catalog/product/customFields

Der folgende Aufruf listet alle im System verfügbaren benutzerdefinierten Produktfelder inklusive ihrer Metadaten. Er kann zum Aufbau von Produktseiten oder zur Anpassung von Such- und Filterfunktionen verwendet werden.

GET https://<ihr-shop>.de/api/v1/catalog/product/customFields

Parameterübersicht

Parameter	Typ	Beschreibung
—	—	Keine zusätzlichen Parameter.

Beispiel-Response

[
  {
    "dataId": "4682",
    "label": "activityLevel",
    "manualEditable": true,
    "name": "activityLevel",
    "nodeId": "content.customProductField.activityLevel",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "4683",
    "label": "animalSize",
    "manualEditable": true,
    "name": "animalSize",
    "nodeId": "content.customProductField.animalSize",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "4684",
    "label": "animalSpecies",
    "manualEditable": true,
    "name": "animalSpecies",
    "nodeId": "content.customProductField.animalSpecies",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "4685",
    "label": "areaOfApplication",
    "manualEditable": true,
    "name": "areaOfApplication",
    "nodeId": "content.customProductField.areaOfApplication",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "type": "Text"
  }
]

Methoden für Kategorien

Diese Methoden arbeiten mit den Kategorien im Katalog: Sie laden die Detaildaten einer einzelnen Kategorie, geben deren direkte Unterkategorien zurück und liefern den vollständigen Pfad von der Wurzel bis zur Zielkategorie (z. B. für Breadcrumbs). Darüber hinaus können alle Produkte einer Kategorie abgefragt und die im System verfügbaren Kategoriefelder ausgelesen werden.

GET catalog/category/load

Folgender Aufruf lädt die Details einer einzelnen Kategorie (z. B. ID, Name). Er kann zur Anzeige von Kategorietiteln, -bildern/-inhalten sowie für Navigations- oder Breadcrumb-Aufbauten verwendet werden. Beispiel-Aufruf, der die Details zur Kategorie mit der ID 135-98530 anzeigt:

GET https://<ihr-shop>.de/api/v1/catalog/category/load?categoryId=135-98530

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie, die geladen werden soll.

Beispiel-Response

{
  "custom": { "image": {} },
  "id": "135-98530",
  "name": "Coole Dinge"
}

GET catalog/category/loadChildren

Mit folgendem Aufruf werden die direkten Unterkategorien einer Kategorie zurückgegeben. Er kann zum Aufbau von Navigationsbäumen, Kachel- oder Teaser-Listen auf Kategorieseiten sowie für Breadcrumb-Erweiterungen verwendet werden. Beispiel-Aufruf, der die direkten Unterkategorien der Kategorie mit der ID 135-98530 zurückgibt:

GET https://<ihr-shop>.de/api/v1/catalog/category/loadChildren?categoryId=135-98530

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie, die geladen werden soll.

Beispiel-Response

[
  {
    "custom": { "image": {} },
    "id": "100-14213",
    "name": "Bekleidung"
  }
]

GET catalog/category/path

Der folgende Aufruf liefert den vollständigen Kategoriepfad von der Wurzel bis zur angegebenen Kategorie (inklusive dieser). Er ist verwendbar für Breadcrumbs, SEO-Pfadangaben, Navigationsleisten oder Kontextanzeigen auf Kategorieseiten. Beispiel-Aufruf, der den vollständigen Pfad der Kategorie mit der ID 104-40827 ausliefert:

GET https://<ihr-shop>.de/api/v1/catalog/category/path?categoryId=104-40827

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie, deren Pfad geladen werden soll.

Beispiel-Response

[
  { "custom": { "image": {} }, "id": "135-98530", "name": "Coole Dinge" },
  { "custom": { "image": {} }, "id": "100-14213", "name": "Bekleidung" },
  { "custom": { "image": {} }, "id": "104-40827", "name": "Sale" }
]

GET catalog/category/products

Mit dem folgenden Aufruf wird die Produktliste für eine angegebene Kategorie geliefert. Er kann beispielsweise verwendet werden, um Kategorie-Listingseiten zu befüllen.

GET https://<ihr-shop>.de/api/v1/catalog/category/products?categoryId=135-98530

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie, deren Produkte geladen werden sollen.

Beispiel-Response

[
  {
    "custom": { "image": {}, "setOrgPrice": 0.0 },
    "id": "146-78608",
    "name": "Plushie",
    "price": 6.7,
    "setOrgPrice": 0.0
  },
  {
    "custom": { "image": {}, "setOrgPrice": 0.0 },
    "id": "147-3720",
    "name": "Stift",
    "price": 3.7,
    "setOrgPrice": 0.0
  }
]

GET catalog/category/fields

Der folgende Aufruf liefert eine Liste aller verfügbaren Kategoriefelder inklusive Typ-Informationen. Er kann für Formulare, Validierungen oder zur Anzeige von Kategorieattributen verwendet werden.

GET https://<ihr-shop>.de/api/v1/catalog/category/fields

Parameterübersicht

Parameter	Typ	Beschreibung
—	—	Keine zusätzlichen Parameter.

Beispiel-Response

[
  {
    "dataId": "active",
    "label": "",
    "manualEditable": true,
    "name": "active",
    "required": false,
    "searchable": false,
    "type": "Enumeration"
  },
  {
    "dataId": "descr",
    "label": "",
    "manualEditable": true,
    "name": "descr",
    "required": false,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "hidden",
    "label": "",
    "manualEditable": true,
    "name": "hidden",
    "required": false,
    "searchable": false,
    "type": "Bool"
  },
  {
    "dataId": "id",
    "label": "",
    "manualEditable": false,
    "name": "id",
    "required": true,
    "searchable": false,
    "type": "Text"
  }
]

GET catalog/category/customFields

Der folgende Aufruf liefert eine Liste aller verfügbaren benutzerdefinierten Kategoriefelder inklusive Typ-Informationen. Er kann für Formulare, Validierungen oder zur Anzeige von Kategorieattributen verwendet werden.

GET https://<ihr-shop>.de/api/v1/catalog/category/customFields

Parameterübersicht

Parameter	Typ	Beschreibung
—	—	Keine zusätzlichen Parameter.

Beispiel-Response

[
  {
    "dataId": "4645",
    "label": "alternatives Template",
    "manualEditable": true,
    "name": "alternativeTemplate",
    "required": false,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "4651",
    "label": "Default Sortierung",
    "manualEditable": true,
    "name": "defaultSort",
    "required": false,
    "searchable": false,
    "type": "Text"
  },
  {
    "dataId": "4641",
    "label": "Kategorie",
    "manualEditable": true,
    "name": "image",
    "required": false,
    "searchable": false,
    "type": "MultiFormatImage"
  },
  {
    "dataId": "4644",
    "label": "Produkte an übergeordnete Kategorien vererben",
    "manualEditable": false,
    "name": "inheritProductsToParents",
    "required": false,
    "searchable": false,
    "type": "Bool"
  }
]

​Unterstützte Methoden

​Methoden für Produkte

​GET catalog/product/load

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/loadList

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/variantInfo

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/categoryMembership

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/categoryMembershipPaths

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/fields

​Parameterübersicht

​Beispiel-Response

​GET catalog/product/customFields

​Parameterübersicht

​Beispiel-Response

​Methoden für Kategorien

​GET catalog/category/load

​Parameterübersicht

​Beispiel-Response

​GET catalog/category/loadChildren

​Parameterübersicht

​Beispiel-Response

​GET catalog/category/path

​Parameterübersicht

​Beispiel-Response

​GET catalog/category/products

​Parameterübersicht

​Beispiel-Response

​GET catalog/category/fields

​Parameterübersicht

​Beispiel-Response

​GET catalog/category/customFields

​Parameterübersicht

​Beispiel-Response

Unterstützte Methoden

Methoden für Produkte

GET catalog/product/load

Parameterübersicht

Beispiel-Response

GET catalog/product/loadList

Parameterübersicht

Beispiel-Response

GET catalog/product/variantInfo

Parameterübersicht

Beispiel-Response

GET catalog/product/categoryMembership

Parameterübersicht

Beispiel-Response

GET catalog/product/categoryMembershipPaths

Parameterübersicht

Beispiel-Response

GET catalog/product/fields

Parameterübersicht

Beispiel-Response

GET catalog/product/customFields

Parameterübersicht

Beispiel-Response

Methoden für Kategorien

GET catalog/category/load

Parameterübersicht

Beispiel-Response

GET catalog/category/loadChildren

Parameterübersicht

Beispiel-Response

GET catalog/category/path

Parameterübersicht

Beispiel-Response

GET catalog/category/products

Parameterübersicht

Beispiel-Response

GET catalog/category/fields

Parameterübersicht

Beispiel-Response

GET catalog/category/customFields

Parameterübersicht

Beispiel-Response