> ## 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-Referenz SEO-URLs

> Suchmaschinenfreundliche URLs für Shop-Seiten über die Admin Interface API verwalten, manuell pflegen oder per Schema automatisch erzeugen.

Mit dem Endpunkt `seo/urls/` stellen wir Ihnen eine Schnittstelle bereit, mit der Sie technische Namen der Shop-Seiten verbergen können und stattdessen klarere Bezeichnungen zu benutzen. Diese können manuell gesetzt oder nach einem Schema generiert werden.

***

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl/Info**              | **Endpunkte** | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| ---------------------------- | ------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **SEO-URLs der Shop-Seiten** | seo/urls/     | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |

### 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)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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)

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/generate/status
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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`.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/categories?sort=resourceIdentifier:asc&filter_eq[main]=1
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

Dieser Endpunkt liefert eine Liste aller SEO-URLs von Produkten. Mithilfe von optionalen Parametern können die Ergebnisse gefiltert und sortiert werden, z. B. nach Erstellungsdatum oder nach Produkt-ID. Der Parameter `size` steuert die Anzahl der Einträge pro Seite und muss im Bereich 1–300 liegen.

Für den Zugriff werden entsprechende Leserechte für SEO-Daten benötigt.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/products?sort=resourceIdentifier:asc
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

Dieser Endpunkt ruft eine Liste der SEO-URLs für allgemeine Shop-Seiten (z. B. Login, Registrierung) ab. Die Ergebnisse lassen sich über optionale Parameter filtern und sortieren. Der Parameter `size` legt die maximale Anzahl an Ergebnissen pro Seite fest und muss im Bereich von 1 bis 300 liegen.

Für den Zugriff sind entsprechende Leserechte für SEO-Daten erforderlich.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/templates?sort=resourceIdentifier:desc
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/check
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "seoPath": "/neue_kategorie-176/"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

URLs werden erneut generiert. Optionaler Parameter `deleteOld` bestimmt, ob alle zurzeit nicht genutzte, aber noch gültige URLs gelöscht werden. Ob eine URL im Shop genutzt wird und nicht einfach nur gültig ist, bestimmt das Feld `main`.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/generate
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "deleteOld": false
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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

Dieser Endpunkt startet die (Re-)Generierung einer SEO-URL. Der alte Wert wird nicht gelöscht.

Die Nutzung des Endpunkts erfordert Schreibrechte für SEO-Daten.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/reset
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "viewControllerId": "Product",
    "resourceIdentifier": "139-55414"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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 Endpunkt erfordert Schreibrechte für SEO-Daten.

#### Beispiel

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "viewControllerId": "Product",
    "resourceIdentifier": "100-41232",
    "optimalPathEsc": "/NewCategory/Something"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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. |
| 400 Bad Request  | "invalidFormat"    | `viewControllerId`, `resourceIdentifier` oder `optimalPathEsc` ist kein String.        |
| 400 Bad Request  | "unknownDataField" | Es wurde ein unbekanntes Feld übergeben.                                               |

### 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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<ihr-shop>.de/admin/api/v1/seo/urls/
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "seoPath": "/Neue_Kategorie/Neues_Produkt-7"
}
```

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "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](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.