Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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

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

​
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

​
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
}

​
Unterstützte Parameter

Die folgenden URL-Parameter werden zur Steuerung von Ergebnislisten unterstützt. Die Schreibweise ist case-sensitive.
ParameterBeschreibung
sizeAnzahl der zurückgegebenen Einträge pro Seite (1 bis maximal 300)
pageTokenOptionaler Paginierungsmarker für den Abruf der nächsten Seite
sortErgebnis-Sortierung nach einem oder mehreren Feldern
filter_...Filterbedingungen zur Einschränkung der Ergebnisse
subshopIdOptionaler Parameter zur Einschränkung auf einen bestimmten Subshop. Bei einigen Endpunkten (z. B. Produkte, Kategorien, SEO) erforderlich.
textSearchOptionaler Parameter für die Volltextsuche.

​
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

FehlercodeTypBeschreibung
400InvalidCharacterUngültige Zeichen im Parameterwert
400InvalidValueWert 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

FehlercodeTypBeschreibung
400Token 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

​
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

FehlercodeTypBeschreibung
400SyntaxErrorFehlender oder mehrfach vorhandener Doppelpunkt.
400InvalidValueUngültige Sortierrichtung (nicht asc oder desc)
400UnknownFieldDas angegebene Sortierfeld ist unbekannt

​
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

OperationBedeutung
eqGleichheit (=)
neqUngleichheit (!=)
ltKleiner als (<)
lteKleiner oder gleich (≤)
gtGrößer als (>)
gteGrößer oder gleich (≥)
beginsWithBeginnt mit
endsWithEndet mit
containsEnthält
notContainsEnthält nicht
filter_withinGilt für benutzerdefinierte Felder vom Typ Liste
filter_notWithinGilt für benutzerdefinierte Felder vom Typ Liste

​
Fehlercodes

FehlercodeTypBeschreibung
400UnknownOperationDie Filteroperation ist nicht bekannt
400UnknownFieldDas angegebene Feld ist ungültig

​
Volltextsuche

Die meisten Endpunkte unterstützen eine Volltextsuche über den optionalen URL-Parameter textSearch. 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.

​
Syntax

textSearch=<Suchbegriff>&textSearch=<Suchbegriff>

​
Beispiel (einzelner Suchbegriff)

https://<ihr-shop>.de/admin/api/v1/orders?textSearch=Mustermann

​
Beispiel (mehrere Suchbegriffe)

https://<ihr-shop>.de/admin/api/v1/orders?textSearch=Mustermann&textSearch=Berlin

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