> ## 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. # API Basics > Grundlagen der Admin Interface API: Basis-URL, Berechtigungen, Authentifizierung, Filter, Sortierung und Paginierung im WEBSALE Shop. 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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/ ``` Diese URL ist die Basis für sämtliche Anfragen, z.B. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} GET https://.de/admin/api/v1/products ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/profile ``` Die Vergabe von Rechten erfolgt über den Service „Benutzer“: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.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. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} POST https://.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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} "X-Authorization": "Bearer " ``` Details zur Authentifizierung (Request-Varianten, Token-Verwendung, Fehlercodes etc.) finden Sie in der separaten Dokumentation: [API-Referenz Authentifizierung](/schnittstellen/admin-interface-api/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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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. | **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 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. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=50 ``` #### Fehlercodes | **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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?size=100&pageToken=MTAw ``` #### 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 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} sort=:asc|desc ``` #### Sortierung nach Preis aufsteigend ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?sort=price:asc ``` Ein weiteres Beispiel für eine Sortierung nach dem Namen (aufsteigend) und anschließend nach dem Preis (absteigend): ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/?sort=name:asc&sort=price:desc ``` #### 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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} filter_[]= ``` 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. ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} ?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** | | ------------------ | ------------------------------------------------ | | `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-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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} textSearch=&textSearch= ``` #### Beispiel (einzelner Suchbegriff) ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.de/admin/api/v1/orders?textSearch=Mustermann ``` #### Beispiel (mehrere Suchbegriffe) ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://.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](https://websale.atlassian.net/servicedesk/customer/portal/6) Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können. ## Related topics - [Storefront API Basics](/schnittstellen/storefront-api/storefront-api-basics.md) - [Storefront API Lagerbestand](/schnittstellen/storefront-api/storefront-api-lagerbestand.md) - [Storefront API Merkliste](/schnittstellen/storefront-api/storefront-api-merkliste.md) - [Storefront API Warenkorb](/schnittstellen/storefront-api/storefront-api-warenkorb.md) - [Storefront API Gutscheine](/schnittstellen/storefront-api/storefront-api-gutscheine.md)