Die REST API bietet Ihnen die Möglichkeit, automatisiert mit dem Shop-System zu interagieren – etwa um Produktdaten zu verwalten, Bestellungen auszulesen oder eigene Integrationen anzubinden. Dieses Dokument beschreibt die grundlegenden Voraussetzungen und technischen Konzepte, um mit der API arbeiten zu können.

Inhaltsverzeichnis

1 1. Basis-URL
2 2. Zugang & Berechtigungen
3 3. Authentifizierung
4 4. Filter, Sortierung & Paginierung
- 4.1 4.1 Unterstützte Parameter
- 4.2 4.2 Anzahl & Paginierung
- 4.3 4.3 Sortierung
- 4.4 4.4 Filter
5 5. Support

1. Basis-URL

Alle REST-API-Endpunkte sind unter folgendem Pfad erreichbar:

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

Diese URL ist die Basis für sämtliche Anfragen, z.B.

GET https://<ihr-shop>.de/admin/api/v1/products

POST https://<ihr-shop>.de/admin/api/v1/login

2. Zugang & Berechtigungen

Für den Zugriff auf die REST API ist ein Benutzerkonto erforderlich, das im Admin Interface Ihres Shops verwaltet wird.

Das Admin Interface ist in sogenannte Services unterteilt (z. B. Produkte, Kategorien, Sitemaps, SEO-URLs, Datenfeeds, Statistiken etc.). Für jeden Service können im Admin-Bereich Berechtigungen vergeben werden – z. B. Lesen, Bearbeiten, Erstellen, Löschen oder Publizieren.

Diese Rechte gelten auch für die REST API und bestimmen, auf welche Endpunkte Sie zugreifen und welche HTTP-Methoden (GET, POST, PUT, DELETE) Sie verwenden dürfen.

Ein Benutzer mit z. B. nur Leserechten im Service „Produkte“ kann Produkte per API nur abrufen (GET), aber nicht bearbeiten (PUT/POST/DELETE).

Ihre zugewiesenen Rechte können Sie im Admin Interface unter folgendem Pfad einsehen:

https://<ihr-shop>.de/admin/profile

Die Vergabe von Rechten erfolgt über den Service „Benutzer“:

https://<ihr-shop>.de/admin/administration/users

Einige Endpunkte arbeiten mit subshopspezifischen Daten. In diesen Fällen muss der betreffende Subshop über den URL-Parameter subshopId explizit angegeben werden. Das betrifft unter anderem Methoden für Produkte, Kategorien, SEO-Daten und ähnliche kontextabhängige Inhalte.

https://<ihr-shop>.de/admin/api/v1/categories?subshopId=deutsch

Wird der Parameter weggelassen, kann die Anfrage fehlschlagen oder unerwartete Ergebnisse liefern.

Falls Ihnen der Zugriff auf bestimmte REST-Endpunkte verweigert wird, fehlen Ihnen möglicherweise die erforderlichen Rechte. In diesem Fall wenden Sie sich an den zuständigen Shop-Administrator.

3. Authentifizierung

Für den Zugriff auf geschützte REST-API-Endpunkte ist eine Anmeldung erforderlich.

Die Authentifizierung erfolgt entweder über Benutzername/Passwort oder per API-Schlüssel. Erfolgreich authentifizierte Anfragen erhalten ein Access Token, mit dem weitere Endpunkte angesprochen werden können. Zusätzlich wird ein Refresh Token bereitgestellt.

Der Login erfolgt über folgenden Endpunkt:

POST https://<ihr-shop>.de/admin/api/v1/login

Das erhaltene Access Token muss bei allen folgenden API-Aufrufen im HTTP-Header mitgesendet werden. Der Header muss dazu das Feld X-Authorization enthalten. Der Wert besteht aus dem Wort Bearer, gefolgt vom Token:

"X-Authorization": "Bearer <Access-Token>"

Details zur Authentifizierung (Request-Varianten, Token-Verwendung, Fehlercodes etc.) finden Sie in der separaten Dokumentation: API-Referenz Authentifizierung

4. Filter, Sortierung & Paginierung

Viele REST-Endpunkte liefern Listen von Daten – etwa Produkte, Bestellungen oder Kategorien. Um mit diesen Daten effizient zu arbeiten, stellt die API verschiedene Parameter zur Verfügung, mit denen sich die Ergebnisse eingrenzen, sortieren und seitenweise abrufen lassen. Diese Mechanismen sind besonders bei großen Datenmengen wichtig, um performante und gezielte Abfragen zu ermöglichen.

Ein API-Aufruf kann dabei verschiedene Parameter enthalten. Ein typischer GET-Request könnte wie folgt aussehen:

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=100&sort=field1:asc&filter_eq[field2]=value&pageToken=MTAw

Die Antwort der API ist standardisiert aufgebaut und enthält neben den angeforderten Datensätzen weitere Meta-Informationen wie den nextPageToken, den Gesamtzähler (totalCount) sowie das Flag endReached, das angibt, ob weitere Seiten zur Verfügung stehen:

{
	"endReached": true,
	"items": [...],
	"nextPageToken": "MTAx",
	"totalCount": 123
}

4.1 Unterstützte Parameter

Die folgenden URL-Parameter werden zur Steuerung von Ergebnislisten unterstützt. Die Schreibweise ist case-sensitive.

Parameter	Beschreibung

Parameter	Beschreibung
`size`	Anzahl der zurückgegebenen Einträge pro Seite (1 bis maximal 300)
`pageToken`	Optionaler Paginierungsmarker für den Abruf der nächsten Seite
`sort`	Ergebnis-Sortierung nach einem oder mehreren Feldern
`filter_...`	Filterbedingungen zur Einschränkung der Ergebnisse
`subshopId`	Optionaler Parameter zur Einschränkung auf einen bestimmten Subshop. Bei einigen Endpunkten (z. B. Produkte, Kategorien, SEO) erforderlich.

4.2 Anzahl & Paginierung

Die Anzahl der zurückgegebenen Datensätze pro API-Anfrage kann über den Parameter size gesteuert werden. Der Wert muss eine Ganzzahl zwischen 1 und 300 sein.

Wird kein size-Parameter übergeben, verwendet die API standardmäßig einen Wert von 100 Einträgen pro Seite.

Ist die angeforderte Datenmenge größer als der definierte size-Wert (bzw. größer als der Standardwert), liefert die API in der Antwort einen nextPageToken, mit dem weitere Seiten geladen werden können. Der Paginierungsmechanismus erlaubt es, große Datenmengen schrittweise abzurufen.

Beispiel

Beispiel für eine manuell gesetzte Seitengröße.

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=50

Fehlercodes

Fehlercode	Typ	Beschreibung

Fehlercode	Typ	Beschreibung
400	`InvalidCharacter`	Ungültige Zeichen im Parameterwert
400	`InvalidValue`	Wert kleiner als 1 oder größer als 300

Der Parameter pageToken ermöglicht den Zugriff auf die Folgeseiten von Ergebnislisten. Der Wert wird von der API automatisch als nextPageToken zurückgegeben und muss base64-url-kodiert übergeben werden. Bei einer fehlerhaften oder ungültigen Codierung erfolgt eine Fehlermeldung.

Beispiel

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=100&pageToken=MTAw

Fehlercodes

Fehlercode	Typ	Beschreibung

Fehlercode	Typ	Beschreibung
400		Token nicht dekodierbar oder negativ bzw. ungültig

Sonderfall: Produkte

Das Laden von Produkten mittels pageToken kann langsam sein, wenn mehr als 10.000 Produkte im Shop existieren. Neben dem pageToken wird bei Produkten auch ein searchAfterToken zurückgegeben.

Statt pageToken kann searchAfterToken in der URL angegeben werden, um auch bei vielen Ergebnissen die Produkte effizient laden zu können.

Beispiel

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?size=300&searchAfterToken=WzAuMCwiMTAwLTQxMjMyLTk3NDFfZGV1dHNjaF8zIl0

4.3 Sortierung

Die Sortierung von Ergebnissen erfolgt über den Parameter sort. Er erwartet als Wert einen Feldnamen und eine Sortierrichtung (asc für aufsteigend, desc für absteigend), getrennt durch einen Doppelpunkt.

Für die Kombination mehrerer Sortierkriterien ist es erforderlich, mehrere sort-Parameter zu übergeben. Jeder Parameter steht dabei für ein einzelnes Kriterium. Eine kommaseparierte Liste innerhalb eines Parameters wird nicht unterstützt.

Falls kein Sortierparameter angegeben ist, wird standardmäßig nach der internen ID sortiert.

Syntax

sort=<Feldname>:asc|desc

Sortierung nach Preis aufsteigend

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?sort=price:asc

Ein weiteres Beispiel für eine Sortierung nach dem Namen (aufsteigend) und anschließend nach dem Preis (absteigend):

https://<ihr-shop>.de/admin/api/v1/<API-Referenz>?sort=name:asc&sort=price:desc

Fehlercodes

Fehlercode	Typ	Beschreibung

Fehlercode	Typ	Beschreibung
400	`SyntaxError`	Fehlender oder mehrfach vorhandener Doppelpunkt.
400	`InvalidValue`	Ungültige Sortierrichtung (nicht `asc` oder `desc`)
400	`UnknownField`	Das angegebene Sortierfeld ist unbekannt

4.4 Filter

Filter ermöglichen eine gezielte Einschränkung von Ergebnislisten. Jeder Filter folgt dem Muster.

Syntax

filter_<Operation>[<Feldname>]=<Wert>

Mehrere Filter für unterschiedliche Felder werden logisch mit UND verknüpft. Wenn mehrere Filter für dasselbe Feld angegeben werden, interpretiert die API diese als ODER-Verknüpfung.

?filter_eq[status]=open
&filter_gte[createdAt]=2024-12-01T00:00:00Z
&filter_lte[createdAt]=2025-01-05T23:59:59Z

Unterstützte Filteroperationen:

Operation	Bedeutung

Operation	Bedeutung
`eq`	Gleichheit (`=`)
`neq`	Ungleichheit (`!=`)
`lt`	Kleiner als (`<`)
`lte`	Kleiner oder gleich (`≤`)
`gt`	Größer als (`>`)
`gte`	Größer oder gleich (`≥`)
`beginsWith`	Beginnt mit
`endsWith`	Endet mit
`contains`	Enthält
`notContains`	Enthält nicht
`filter_within`	Gilt für benutzerdefinierte Felder vom Typ Liste
`filter_notWithin`	Gilt für benutzerdefinierte Felder vom Typ Liste

Fehlercodes

Fehlercode	Typ	Beschreibung

Fehlercode	Typ	Beschreibung
400	`UnknownOperation`	Die Filteroperation ist nicht bekannt
400	`UnknownField`	Das angegebene Feld ist ungültig

5. Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: Zum Kundenportal

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

API Basics

Inhaltsverzeichnis

1. Basis-URL

2. Zugang & Berechtigungen

3. Authentifizierung

4. Filter, Sortierung & Paginierung

4.1 Unterstützte Parameter

4.2 Anzahl & Paginierung

Beispiel

Fehlercodes

Beispiel

Fehlercodes

Sonderfall: Produkte

Beispiel

4.3 Sortierung

Syntax

Sortierung nach Preis aufsteigend

Fehlercodes

4.4 Filter

Syntax

Unterstützte Filteroperationen:

Fehlercodes

5. Support