Basis-URL
Alle REST-API-Endpunkte sind unter folgendem Pfad erreichbar: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:subshopId explizit angegeben werden. Das betrifft unter anderem Methoden für Produkte, Kategorien, SEO-Daten und ähnliche kontextabhängige Inhalte.
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:X-Authorization enthalten. Der Wert besteht aus dem Wort Bearer, gefolgt vom Token:
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:nextPageToken, den Gesamtzähler (totalCount) sowie das Flag endReached, das angibt, ob weitere Seiten zur Verfügung stehen:
Unterstützte Parameter
Die folgenden URL-Parameter werden zur Steuerung von Ergebnislisten unterstützt. Die Schreibweise ist case-sensitive.| 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. |
textSearch | Optionaler Parameter für die Volltextsuche. |
Anzahl & Paginierung
Die Anzahl der zurückgegebenen Datensätze pro API-Anfrage kann über den Parametersize 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.Fehlercodes
| Fehlercode | Typ | Beschreibung |
|---|---|---|
| 400 | InvalidCharacter | Ungültige Zeichen im Parameterwert |
| 400 | InvalidValue | Wert kleiner als 1 oder größer als 300 |
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
Fehlercodes
| 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 einsearchAfterToken zurückgegeben.
Statt pageToken kann searchAfterToken in der URL angegeben werden, um auch bei vielen Ergebnissen die Produkte effizient laden zu können.
Beispiel
Sortierung
Die Sortierung von Ergebnissen erfolgt über den Parametersort. 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
Sortierung nach Preis aufsteigend
Fehlercodes
| 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 |
Filter
Filter ermöglichen eine gezielte Einschränkung von Ergebnislisten. Jeder Filter folgt dem Muster.Syntax
Unterstützte Filteroperationen
| 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 |
|---|---|---|
| 400 | UnknownOperation | Die Filteroperation ist nicht bekannt |
| 400 | UnknownField | Das angegebene Feld ist ungültig |
Volltextsuche
Die meisten Endpunkte unterstützen eine Volltextsuche über den optionalen URL-ParametertextSearch. Damit lassen sich Ergebnisse nach einem Suchbegriff filtern, ohne explizite Filterfelder angeben zu müssen. Der Parameter kann mehrfach angegeben werden – mehrere Werte werden mit OR verknüpft. Die Suche ist schreibungsabhängig.