API-Referenz SEO-URLs - WEBSALE Dokumentation

Über den Endpunkt seo/urls/ stellen wir Ihnen eine Schnittstelle bereit, mit der Sie die technischen Namen der Shop-Seiten durch klarere Bezeichnungen ersetzen können. Diese Bezeichnungen können Sie entweder manuell setzen oder nach einem bestimmten Schema generieren lassen. Die folgenden Abschnitte beschreiben zunächst die Datenfelder einer SEO-URL und anschließend die einzelnen Methoden.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
SEO-URLs der Shop-Seiten	seo/urls/

Datenfelder

Name	Typ	Verwendung
path	String	Pfad zur Ausgabe der URL
main	Boolean	Gibt an, ob die URL in der aktuellen Version des Shops verwendet wird.
manual	Boolean	Gibt an, ob die URL manuell gesetzt wurde.
name (bei Kategorien und Produkten)	String	Der Name der Kategorie bzw. des Produkts
resourceIdentifier	String	Seitenname oder Identifikator für eine Kategorie/ein Produkt
updatedAt	String	Zeitpunkt der letzten Aktualisierung (ISO 8601-Format, UTC)
createdAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC)

Beispiel (Produkt)

{
    "createdAt": "2024-06-13T12:12:53.000Z",
    "main": 1,
    "manual": 0,
    "path": "/Bekleidung/Damen_NOOS_High-Waist_Curvy_Skinny_Jeans",
    "resourceIdentifier": "100-69659",
    "updatedAt": "2024-06-13T12:12:53.000Z"
}

Beispiel (Kategorie)

{
    "createdAt": "2025-04-28T11:20:45.000Z",
    "main": 1,
    "manual": 1,
    "name": "Elektronik & Computer",
    "path": "/Elektronik-Computer",
    "resourceIdentifier": "101-64607",
    "updatedAt": "2025-04-28T11:20:45.000Z"
}

Beispiel (Shop-Seite)

{
    "createdAt": "2025-05-06T08:16:05.000Z",
    "main": 1,
    "manual": 1,
    "path": "/checkout",
    "resourceIdentifier": "checkout.htm",
    "updatedAt": "2025-05-06T08:16:05.000Z"
}

Verwendung der Methoden

In diesem Abschnitt werden die verfügbaren Endpunkte zur Verwaltung von SEO-URLs beschrieben. Sie ermöglichen das Abfragen, Erzeugen, Überprüfen, Aktualisieren und Löschen von SEO-URLs für Kategorien, Produkte und Templates im Shop-System. Die Nutzung dieser Methoden erfordert entsprechende Berechtigungen für das Lesen oder Bearbeiten von SEO-Daten.

GET seo/urls/generate/status

Dieser Endpunkt dient dazu, den aktuellen Status der Generierung von SEO-URLs zu überprüfen. Er gibt an, ob aktuell ein Generierungsprozess läuft ("running": true) oder bereits abgeschlossen ist ("running": false). Dies ist insbesondere hilfreich, wenn nach dem Start eines Generierungsvorgangs auf dessen Abschluss gewartet werden soll, bevor weitere Schritte erfolgen. Für die Nutzung dieses Endpunkts sind entsprechende Leseberechtigungen für SEO-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/generate/status

Antwort

{
    "running": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von SEO-Daten.

GET seo/urls/categories

Der Endpunkt GET seo/urls/categories gibt eine Liste von SEO-URLs für Kategorien zurück. Die Liste kann über Sortier- und Filterparameter eingeschränkt werden. Der optionale Parameter size bestimmt die Anzahl der zurückgegebenen Ergebnisse und muss im Bereich von 1 bis 300 liegen. Für die Nutzung dieses Endpunkts sind entsprechende Berechtigungen zum Lesen von SEO-Daten erforderlich.

Beispiel

Das Beispiel ruft alle SEO-URLs, die zurzeit im Shop verwendet werden und nicht nur gültig sind (main = 1), von Kategorien ab und sortiert die Ergebnisse aufsteigend nach dem Feld resourceIdentifier.

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/categories?sort=resourceIdentifier:asc&filter_eq[main]=1

Antwort

{
    "endReached": false,
    "items": [
        {
            "createdAt": "2024-11-15T10:20:10Z",
            "index": 0,
            "name": "Neue Kategorie",
            "path": "/Neue_Kategorie-154",
            "resourceIdentifier": "1000-85809",
            "status": "test",
            "updatedAt": "2024-11-15T10:20:10Z"
        },
        ...
    ],
    "nextPageToken": "MTAw",
    "totalCount": 262
}

Filterfelder

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sortierfelder

createdAt, updatedAt, resourceIdentifier, path, main

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von SEO-Daten.
400 Bad Request	”invalidValue”	`size` ∉ [1;300] `pageToken` ist ungültig.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.

GET seo/urls/products

Über diesen Endpunkt wird eine Liste aller SEO-URLs von Produkten ausgegeben. Mithilfe optionaler Parametern können die Ergebnisse gefiltert und sortiert werden, beispielsweise nach Erstellungsdatum oder nach Produkt-ID. Mit dem Parameter size lässt sich die Anzahl der Einträge pro Seite steuern. Er muss einen Wert zwischen 1 und 300 enthalten. Für den Zugriff werden entsprechende Leserechte für SEO-Daten benötigt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/products?sort=resourceIdentifier:asc

Antwort

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2024-11-15T10:20:10Z",
            "index": 1,
            "name": "Something",
            "path": "/MyCategory/Something",
            "resourceIdentifier": "100-41232",
            "status": "never",
            "updatedAt": "2024-11-15T10:20:10Z"
        },
        ...
    ],
    "nextPageToken": "Mzg",
    "totalCount": 39
}

Filterfelder

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sortierfelder

createdAt, updatedAt, resourceIdentifier, path, main

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von SEO-Daten.
400 Bad Request	”invalidValue”	`size` ∉ [1;300] `pageToken` ist ungültig.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.

GET seo/urls/templates

Über diesen Endpunkt kann eine Liste der SEO-URLs für allgemeine Shop-Seiten (beispielsweise Login oder Registrierung) abgerufen werden. Die Ergebnisse lassen sich über optionale Parameter filtern und sortieren. Mit dem Parameter size kann die maximale Anzahl an Ergebnissen pro Seite festgelegt werden. Er muss einen Wert zwischen 1 und 300 enthalten. Für den Zugriff sind entsprechende Leserechte für SEO-Daten erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/templates?sort=resourceIdentifier:desc

Antwort

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-01-25T08:30:23Z",
            "index": 0,
            "path": "",
            "resourceIdentifier": "login.htm",
            "updatedAt": "2025-01-25T08:30:23Z"
        }
    ],
    "nextPageToken": "MA",
    "totalCount": 1
}

Filterfelder

createdAt, updatedAt, resourceIdentifier, path, manual, main

Sortierfelder

createdAt, updatedAt, resourceIdentifier, path, main

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Lesen von SEO-Daten.
400 Bad Request	”invalidValue”	`size` ∉ [1;300] `pageToken` ist ungültig.
400 Bad Request	”invalidCharacters”
400 Bad Request	”syntaxError”	`sort` enthält mehr als einen oder keinen ”:“.
400 Bad Request	”unknownDataField”	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	”unknownOperation”	Ein Filtertyp ist ungültig.

POST seo/urls/check

Dieser Endpunkt prüft, ob ein bestimmter SEO-Pfad (seoPath) bereits im System verwendet wird und liefert zusätzliche Informationen zur zugehörigen Ressource zurück. Damit lassen sich etwa potenzielle Kollisionen vor dem Speichern neuer URLs vermeiden. Die Nutzung erfordert Schreibrechte für SEO-Daten.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/check

Request Body

{
    "seoPath": "/neue_kategorie-176/"
}

Antwort

{
    "available": false,
    "main": true,
    "resourceIdentifier": "1001-26578",
    "viewController": "Category"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`seoPath` wurde nicht übergeben.
400 Bad Request	”invalidFormat”	`seoPath` ist kein String.
400 Bad Request	”unknownDataField”	Es wurde ein unbekanntes Feld übergeben.

POST seo/urls/generate

Über diesen Endpunkt wird die Neugenerierung aller SEO-URLs für Produkte und Kategorien im Hintergrund gestartet. Die Antwort bestätigt lediglich den Start. Ob die Generierung noch läuft, zeigt GET seo/urls/generate/status. Mit dem optionale Parameter deleteOld kann bestimmt werden, ob alle zurzeit nicht genutzten, aber noch gültigen URLs gelöscht werden sollen. Ob eine URL im Shop genutzt wird oder einfach nur gültig ist, wird durch das Feld main bestimmt.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/generate

Request Body

{
    "deleteOld": false
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Erstellen von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.

POST seo/urls/reset

Mit diesem Endpunkt kann die SEO-URL einer einzelnen Seite zurückgesetzt werden. Manuell gepflegte URLs dieser Seite werden verworfen und die URL wird anschließend gemäß dem konfigurierten Schema neu erstellt. Die neue Haupt-URL ist im Feld mainPath der Antwort zu finden. Die Nutzung des Endpunkts erfordert Schreibrechte für SEO-Daten.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/seo/urls/reset

Request Body

{
    "viewControllerId": "Product",
    "resourceIdentifier": "139-55414"
}

Antwort

{
    "success": true,
    "mainPath": "myURL"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`viewControllerId` oder `resourceIdentifier` wurden nicht übergeben.
400 Bad Request	”invalidFormat”	`viewControllerId` oder `resourceIdentifier` ist kein String.
400 Bad Request	”unknownDataField”	Es wurde ein unbekanntes Feld übergeben.

PUT seo/urls

Mit diesem Endpunkt können Sie eine neue SEO-URL erstellen oder eine bestehende URL aktualisieren. Dabei muss angegeben werden, welchem Controller (viewControllerId) und welchem Objekt (resourceIdentifier) die URL zugeordnet ist. Die URL wird über optimalPathEsc definiert. Der Shop prüft manuell gepflegte Pfade. Leerzeichen, Steuerzeichen sowie die Zeichen ? und # sind nicht erlaubt, ebenso wenig die Pfadsegmente . und ... Enthält optimalPathEsc solche Zeichen oder Segmente, lehnt der Shop die Anfrage ab und speichert den Pfad nicht. Fehlt am Anfang von optimalPathEsc der Schrägstrich, ergänzt der Shop ihn automatisch. Die gesetzte URL wird zur Haupt-URL (main) der Seite. Die bisherigen URLs der Seite führen weiterhin zu ihr, sodass bestehende Links gültig bleiben. Der Endpunkt erfordert Schreibrechte für SEO-Daten.

Beispiel

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

Request Body

{
    "viewControllerId": "Product",
    "resourceIdentifier": "100-41232",
    "optimalPathEsc": "/NewCategory/Something"
}

Antwort

{
    "success": true,
    "mainPath": "/NewCategory/Something"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`viewControllerId`, `resourceIdentifier` oder `optimalPathEsc` wurden nicht übergeben. `optimalPathEsc` ist leer oder besteht nur aus `/`.
400 Bad Request	”invalidFormat”	`viewControllerId`, `resourceIdentifier` oder `optimalPathEsc` ist kein String.
400 Bad Request	”unknownDataField”	Es wurde ein unbekanntes Feld übergeben.
400 Bad Request	”invalidFormat”	`optimalPathEsc` enthält Leerzeichen, Steuerzeichen, `?` oder `#` oder ein Pfadsegment `.` oder `..`.

DELETE seo/urls

Mit diesem Endpunkt kann eine bestehende SEO-URL entfernt werden. Nach dem Löschen ist die URL nicht mehr erreichbar, und es erfolgt keine automatische Weiterleitung mehr. Der Endpunkt setzt Löschberechtigungen für SEO-Daten voraus.

Beispiel

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

Request Body

{
    "seoPath": "/Neue_Kategorie/Neues_Produkt-7"
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Löschen von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	”missing”	`seoPath` wurde nicht übergeben.
400 Bad Request	”invalidFormat”	`seoPath` ist kein String.
400 Bad Request	”unknownDataField”	Es wurde ein unbekanntes Feld übergeben.
404 Not found		Die URL wurde nicht gefunden.

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.

​Unterstützte Methoden

​Datenfelder

​Beispiel (Produkt)

​Beispiel (Kategorie)

​Beispiel (Shop-Seite)

​Verwendung der Methoden

​GET seo/urls/generate/status

​Beispiel

​Antwort

​Fehlercodes

​GET seo/urls/categories

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET seo/urls/products

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET seo/urls/templates

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​POST seo/urls/check

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST seo/urls/generate

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST seo/urls/reset

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT seo/urls

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE seo/urls

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder

Beispiel (Produkt)

Beispiel (Kategorie)

Beispiel (Shop-Seite)

Verwendung der Methoden

GET seo/urls/generate/status

Beispiel

Antwort

Fehlercodes

GET seo/urls/categories

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET seo/urls/products

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET seo/urls/templates

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

POST seo/urls/check

Beispiel

Request Body

Antwort

Fehlercodes

POST seo/urls/generate

Beispiel

Request Body

Antwort

Fehlercodes

POST seo/urls/reset

Beispiel

Request Body

Antwort

Fehlercodes

PUT seo/urls

Beispiel

Request Body

Antwort

Fehlercodes

DELETE seo/urls

Beispiel

Request Body

Antwort

Fehlercodes

Support