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

# urls - URL (Webadressen)

> Der urls-Knoten bündelt die URL-Konfiguration: hreflang-Alternativen, Weiterleitungen, veraltete URLs sowie Aufbau und Bereinigung der SEO-URLs.

export const KonfigDeeplink = ({node}) => <>
    Die Einstellung kann über folgenden Link direkt im Admin-Interface geöffnet werden:{" "}
    <code>{`https://<shop-domain>/admin/config/${node}`}</code>{" "}
    (<a href="/admin-interface/konfigurations-deeplinks">Deeplink-Übersicht</a>)
  </>;

Der Knoten `urls` bündelt die URL-Konfiguration des Shops. Er umfasst Sprach-/Länder-Alternativen per `hreflang`, Weiterleitungen sowie fehlerhafte oder veraltete URLs und den Aufbau und die Bereinigung der SEO-URLs (Struktur, Trennzeichen, Parameterbereinigung).

***

## `urls*` - Grundstruktur

Nachfolgend der Grundaufbau des Knotens `urls`

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

#### Parameterbeschreibung

| **Parameter** | **Beschreibung** |
| - | - |
| `hreflang` | Steuert, welche Seiten-URLs Suchmaschinen per `hreflang` kennen sollen. |
| `redirects` | Steuert, wie der Shop auf fehlerhafte oder nicht mehr gültige URLs reagieren soll. |
| `urls` | Steuert, wie sprechende URLs im Shop aufgebaut und bereinigt werden. |

***

## `urls.hreflang` - Sprach-/Länder-Alternativen für Seiten-URLs

Über diesen Knoten wird gesteuert, welche alternativen Seiten-URLs (z. B. DE/AT/CH/EN) Suchmaschinen per `hreflang` zu einer Seite kennen sollen. Dazu werden Subshops zu Gruppen zusammengefasst. Pro Gruppe lässt sich festlegen, ob Produkte/Kategorien automatisch oder manuell zugeordnet werden und in welchem Exportformat (CSV/JSON) die Zuordnungen ausgegeben werden sollen.

<KonfigDeeplink node="urls.hreflang" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "collectInfo": true,
  "subshopGroups": [
    {
      "categoryAlloc": "automatic",
      "checkMode": true,
      "fileNameCategory": "catAlloc.csv",
      "fileNameProduct": "prodAlloc.csv",
      "fileType": "csv",
      "groupId": "hrefGroup",
      "groupName": "Href-Group",
      "productAlloc": "automatic",
      "subshops": [
        {
          "default": true,
          "subshopId": "deutsch"
        },
        {
          "default": false,
          "subshopId": "englisch"
        }
      ]
    }
  ]
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung** |
| - | - | - |
| `collectInfo` | bool | Wenn diese Option aktiviert wird, sammelt das System Informationen darüber, welche Sprach-/Länderversionen zu welcher Seite gehören und ob die Verknüpfungen korrekt gesetzt sind - das hilft beim finden von Fehlern.  <br />Default: `true` |
| `subshopGroups` | list (object) | Liste der Subshop-Gruppen, die für hreflang zusammengefasst werden. |
| `groupId` | string | Eindeutige Kennung der hreflang-Gruppe innerhalb von `subshopGroups`. <br />Frei wählbar. |
| `groupName` | string | Lesbarer Name der hreflang-Gruppe. |
| `checkMode` | bool | Schaltet Prüfungen ein, die typische Fehler in den Sprach-/Länder-Zuordnungen finden. |
| `productAlloc` | enum | Legt fest, wie sprach-/subshop-spezifische Gegenstücke desselben Produkts (hreflang-Varianten) verknüpft werden.      <br />`automatic` - Automatische Zuordnung  <br />`manual` - Zuordnung wird manuell gepflegt (z.B. per Datei/Liste).  <br />Default: `automatic` |
| `categoryAlloc` | enum | Legt fest, wie sprach-/subshop-spezifische Kategorien verknüpft werden.  <br />`automatic` - Automatische Zuordnung   <br />`manual` - Zuordnung wird manuell gepflegt (z.B. per Datei/Liste).  <br />Default: `automatic` |
| `fileType` | enum | Legt das Exportformat der Hreflang-Zuordnungen für Kategorien und Produkte fest.  <br />`csv` - stellt die Export-Datei im csv-Format bereit   <br />`json` - stellt die Export-Datei im json-Format bereit |
| `fileNameProduct` | string | Legt den Dateinamen für den Export der Produktzuordnungen fest. |
| `fileNameCategory` | string | Legt den Dateinamen für den Export der Kategoriezuordnungen fest. |
| `subshops` | list (object) | Enthält eine Liste der verfügbaren Sprach-/Subshops. |
| `subshopId` | string | ID des Subshops (z.B. `de`, `en`) |
| `default` | bool | Markiert die primäre Sprache/Region.  Default: `false` |

***

## `urls.redirects` - Weiterleitungen für fehlerhafte URLs

Über den Unterknoten `redirects` wird gesteuert, wie der Shop auf nicht mehr gültige oder fehlerhafte URLs reagiert (z. B. gelöschte Produkte/Kategorien oder veraltete Links). Hier wird festgelegt, welches Fehlerseiten-Template verwendet werden soll, ob nach Möglichkeit automatisch auf die Elternkategorie umgeleitet wird und auf welche Seite im Allgemeinen als Fallback weitergeleitet wird.

<KonfigDeeplink node="urls.redirects" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "errorPageTemplate": "error.htm",
  "redirectFallback": "errorPage",
  "redirectToParentCategory": true
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung** |
| - | - | - |
| `errorPageTemplate` | string | Name des Templates, das für Fehlerseiten (z.B. 404-Seite) verwendet wird. |
| `redirectFallback` | string | Fallback-Ziel, wenn keine spezifische Weiterleitung greift.  <br />`startPage` - im Fehlerfall wird auf die Startseite des Shops weitergeleitet   <br />`errorPage` - Im Fehlerfall wird auf die Default-Fehlerseite weitergeleitet  Default: `startPage` |
| `redirectToParentCategory` | bool | Wenn `true`, wird bei Fehlerhaften Weiterleitungen nach Möglichkeit auf die Elternkategorie umgeleitet.  <br />Default: `true` |

***

## `urls.urls` - Allgemeine Einstellungen für SEO-URLs

Über den Unterknoten `urls` wird gesteuert, wie sprechende URLs im Shop aufgebaut und bereinigt werden. Dabei wird unter anderem festgelegt, ob die URL-Logik aktiv ist, ob URLs kleingeschrieben werden und welche Trennzeichen verwendet werden.

<KonfigDeeplink node="urls.urls" />

#### Beispielkonfiguration

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "alwaysEndWithSlash": true,
  "generate": [
    {
      "options": {
        "urlschema": [
          {
            "schema": [
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "reverse",
                  "top": 2
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ],
            "subshop": "englisch"
          },
          {
            "schema": [
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "normal",
                  "top": 1
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ]
          }
        ]
      },
      "service": "seoUrlHandler.category"
    },
    {
      "options": {
        "urlschema": [
          {
            "schema": [
              {
                "fields": [
                  "brand"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "categoryPath"
                ],
                "listOptions": {
                  "categoryField": "name",
                  "order": "normal",
                  "top": 1
                },
                "optional": true,
                "separator": "/",
                "type": "field"
              },
              {
                "fields": [
                  "name"
                ],
                "optional": true,
                "separator": "/",
                "type": "field"
              }
            ]
          }
        ]
      },
      "service": "seoUrlHandler.product"
    }
  ],
  "lowercase": true,
  "mappings": {
    "ß": "ss",
    "ä": "ae",
    "ö": "oe",
    "ü": "ue"
  },
  "parametersToRemove": [
    "ref"
  ],
  "suffixSeparator": "-",
  "wordSeparator": "_"
}
```

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung** |
| - | - | - |
| `active` | bool | Schaltet die URL-Logik ein/aus. Wenn `false`, wird die automatische SEO-URL-Verarbeitung (Funktion, die die URLs suchmaschinenfreundlich macht) deaktiviert.  Default: `true` |
| `lowercase` | bool | Wenn `true`, werden URLs in Kleinbuchstaben ausgegeben (z.B. `/produkte/t-shirt`). |
| `suffixSeparator` | string | Separator zwischen Basis-URL und Suffix (z.B. Produkt-ID). Häufig z.B. `-` (z.B. `/t-shirt-1234`). |
| `wordSeparator` | string | Separator zwischen Wörtern im Pfad, z.B. `_` → `/t_shirt_herren/`) |
| `alwaysEndWithSlash` | bool | Wenn `true`, enden generierte URLs immer mit `/` (z.B. `/herren/t-shirts/`) |
| `parametersToRemove` | list (string) | Liste von Query-Parametern, die aus URLs entfernt werden sollen (z.B. Tracking-Parameter wie `ref`, `utm`). |
| `mappings` | map | Zeichen-Mappings für die URL-Erzeugung. <br />Schlüssel = Originalzeichen (meist für Umlaute verwendet), Wert = Ersatzzeichenfolge. |
| `<Schlüssel>` | string | Originalzeichen (z.B. `ä`, `ß`), das in URLs ersetzt werden soll. |
| `<Wert>` | string | Ersatzzeichen (z.B. `ae` statt `ä`), das das Originalzeichen ersetzt. |
| `generate` | list (object) | Ein Eintrag in `generate` beschreibt die URL-Erzeugung für einen bestimmten Typ, z.B. Kategorien oder Produkte. |
| `service` | string | Name des URL-Handlers, z.B. `seoUrlHandler.category`. |
| `options` | object | Optionen für diesen Service, insbesondere die Definition der URL-Schemate über `urlschema`. |
| `urlschema` | list (object) | Jedes `urlschema` beschreibt ein Schema für die Zusammensetzung des URL-Pfads. |
| `subshop` | string | Subshop-ID, für den dieses Schema gilt (z.B. `englisch`). |
| `schema` | list (object) | Liste von Schema Bausteinen, die nacheinander den URL-Pfad aufbauen. |
| `type` | string | Art des Schema-Bausteins, z.B. `field`. |
| `fields` | list (string) | Liste von Feldnamen, deren Werte in diesen Abschnitt einfließen (z.B. `categoryPath`, `brand`, `name`). |
| `separator` | string | Trenner, der hinter diesem Abschnitt in der URL gesetzt wird (z.B. `/` ). |
| `optional` | bool | Wenn `true`, wird der Baustein übersprungen, falls keine Werte vorhanden sind. |
| `listOptions` | object | Zusätzliche Optionen, wenn das Feld eine Liste/Hierarchie ist (z.B. `categoryPath`). |
| `categoryField` | string | Feld, das für den Kategorienamen genutzt wird (typisch: `name`). |
| `order` | enum | Reihenfolge, in der Kategorien ausgegeben werden.  `normal` - von oben nach unten   `reverse` - von unten nach oben |
| `top` | int | Anzahl der Ebenen, die übernommen werden sollen (z.B. `1` → nur die oberste Kategorie oder `2` → die ersten beiden Ebenen). |


## Related topics

- [Konfigurations-Deeplinks](/admin-interface/konfigurations-deeplinks.md)
- [Storefront API URL-Resolution](/schnittstellen/storefront-api/storefront-api-url-resolution.md)
- [API-Referenz Konfiguration](/schnittstellen/admin-interface-api/api-referenz-konfiguration.md)
- [Übersicht - Konfiguration](/konfiguration.md)
- [API-Referenz SEO-URLs](/schnittstellen/admin-interface-api/api-referenz-seo-urls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.