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

# Storefront API URL-Resolution

> Sprechende Storefront-URLs über die Storefront API auf Produkt- oder Kategorie-IDs auflösen und das Routing eines Headless-Frontends darauf stützen.

Die URL-Resolution API dient dazu, eine Storefront-URL (insbesondere SEO-URLs) auf den passenden Shop-Inhalt aufzulösen. Damit kann das Frontend sein Routing auf sprechenden URLs aufbauen und erhält als Ergebnis, ob die URL beispielsweise zu einem Produkt oder einer Kategorie gehört – inklusive der erforderlichen internen IDs.

Anschließend lassen sich die Detaildaten gezielt über die Katalog API abrufen. Ein typischer Ablauf ist: Die Storefront übermittelt eine URL wie `/herren/schuhe/sneaker`, die API liefert den Zieltyp (z. B. Kategorie) und die zugehörige Kategorie-ID zurück, und danach werden die Inhalte über die [Katalog API](/schnittstellen/storefront-api/storefront-api-katalog) geladen.

***

## Unterstützte Methoden

Angabe aller Unterstützten Methoden.

| **Befehl**                      | **Endpunkte**   | **GET**               | **PUT**             | **POST**            | **DELETE**          |
| ------------------------------- | --------------- | --------------------- | ------------------- | ------------------- | ------------------- |
| SEO-URLs erkennen               | `urls/identify` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| SEO-URL eines Produkts abrufen  | `urls/product`  | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| SEO-URL einer Kategorie abrufen | `urls/category` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |

## SEO-URLs

### GET urls/identify

Mithilfe des folgenden Aufrufs lässt sich ermitteln, wohin eine SEO-URL im Shop führt (Produkt, Kategorie, Inhaltsseite oder Startseite).

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

Im Response steht der Typ der URL und - je nach Typ - eine Ressource (z.B. eine ID oder ein Pfad).\
**Die API unterscheidet dabei zwischen folgenden Typen**

| **Typ**       | **Ressource** | **Beschreibung**                                                                                   |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------- |
| `“Product"`   | Produkt-ID    | Verweist auf eine Produktseite und enthält die zugehörige Produkt-ID, zu dem die URL gehört.       |
| `“Category"`  | Kategorie-ID  | Verweist auf eine Kategorieseite und enthält die Kategorie-ID, die über die URL aufgerufen wird.   |
| `“View"`      | Template-Pfad | Verweist auf eine Shop-Seite oder ein Template, die über den angegebenen Pfad geladen wird.        |
| `“Startpage"` | --            | Verweist auf die Startseite des Shops. Für diesen Typ wird keine zusätzliche Ressource ausgegeben. |

#### Beispiele

Erfolgreiche Identifikation (Haupt-URL)

Die URL zeigt direkt auf ein Produkt. In der Antwort werden der Typ und die zugehörige ID angegeben.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/urls/identify?url=/products/awesome-widget
```

**Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Product",
  "id": "12345"
}
```

#### Erfolgreiche Identifikation mit Weiterleitung

Veraltete URLs werden erkannt und auf die aktuelle URL weitergeleitet. Zusätzlich zur ID wird ein Redirect mitgeliefert.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/urls/identify?url=/products/old-product-name
```

**Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Product",
  "id": "12345",
  "redirect": "/products/awesome-widget"
}
```

#### Kategorie

Wenn die URL zu einer Kategorie führt, enthält die Antwort eine Kategorie-ID.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/urls/identify?url=/categories/electronics
```

**Beispiel-Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Category",
  "id": "789"
}
```

#### Startseite

Wenn die URL zur Startseite führt, gibt es keine zusätzliche (ID-)Ressource im Response.

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

**Beispiel-Response**

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

#### Ungültige URL

Wenn die URL dem System nicht bekannt ist, antwortet die API mit einem „`404 Not Found`”.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/urls/identify?url=/non-existent-page
```

**Beispiel-Response**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
HTTP/1.1 404 Not Found
```

### GET urls/product

Mithilfe des folgenden Aufrufs lässt sich die SEO-URL eines Produkts anhand der Produkt-ID ermitteln.

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

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                                            |
| ------------- | ------- | --------------------------------------------------------------------------- |
| `productId`   | string  | **Pflichtfeld**<br />ID des Produkts, dessen SEO-URL ermittelt werden soll. |

#### Beispiel-Response

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

* Wenn das Produkt nicht gefunden wurde, gibt die Anfrage `404 Not Found` zurück.
* Bei Erfolg gibt die Anfrage `200 OK` zurück inklusive der im Beispiel genannten Ausgabe der SEO-URL des Produkts im Body.

### GET urls/category

Mithilfe des folgenden Aufrufs lässt sich die SEO-URL einer Kategorie anhand der Kategorie-ID ermitteln.

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

#### Parameterübersicht

| **Parameter** | **Typ** | **Beschreibung**                                                            |
| ------------- | ------- | --------------------------------------------------------------------------- |
| `categoryId`  | string  | **Pflichtfeld**<br />ID der Kategorie, deren SEO-URL ermittelt werden soll. |

#### Beispiel-Response

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

* Wenn die Kategorie nicht gefunden wurde, gibt die Anfrage `404 Not Found` zurück.
* Bei Erfolg gibt die Anfrage `200 OK` zurück inklusive der im Beispiel genannten Ausgabe der SEO-URL der Kategorie im Body.