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

> Filialen und Märkte des Shops über die Admin Interface API anlegen, abrufen, aktualisieren sowie gezielt aus dem Shopsystem entfernen.

Der Endpunkt `stores/` stellt Ihnen eine Schnittstelle zur Verwaltung von Filialen (Märkten) in unserem Shop-System bereit. Mit dieser Schnittstelle können Sie Marktdaten abrufen, neue Märkte anlegen und bestehende Märkte aktualisieren.

## Unterstützte Methoden

Angabe aller unterstützten Methoden.

| **Befehl/Info**             | **Endpunkte** | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| --------------------------- | ------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Verwaltung der Filialen** | stores/       | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |

## Datenfelder eines Stores

| **Name**                         | **Typ** | **Bedeutung**                                                                                                                                       |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | number  | Eindeutige ID des Stores (nur lesbar).                                                                                                              |
| `info`                           | object  | Objekt mit generellen Informationen zum Store.                                                                                                      |
| `info.name`                      | string  | Name des Stores.                                                                                                                                    |
| `info.street`                    | string  | Straße und Hausnummer des Stores.                                                                                                                   |
| `info.zipCode`                   | string  | Postleitzahl des Stores.                                                                                                                            |
| `info.city`                      | string  | Stadt des Stores.                                                                                                                                   |
| `info.country`                   | string  | Ländercode des Stores (z.B. `DE`).                                                                                                                  |
| `info.zipcodes`                  | array   | Liste von Postleitzahl-Präfixen, die dem Store zugeordnet sind.                                                                                     |
| `info.zipcodes[].prefix`         | string  | Postleitzahl-Präfix.                                                                                                                                |
| `info.zipcodes[].country`        | string  | Ländercode des Postleitzahl-Präfixes.                                                                                                               |
| `info.timeZone`                  | string  | Zeitzone des Stores (z.B. `Europe/Berlin`).                                                                                                         |
| `info.metadata`                  | object  | Beliebige Zusatzinformationen des Stores                                                                                                            |
| `storageId`                      | string  | Lager-ID des Stores (wird für die Funktion “Abholung im Markt” verwendet).                                                                          |
| `subshops`                       | array   | Liste der Subshops, für die dieser Store freigeschaltet ist.                                                                                        |
| `location`                       | object  | Geografische Koordinaten des Stores.                                                                                                                |
| `location.longitude`             | number  | Längengrad des Stores.                                                                                                                              |
| `location.latitude`              | number  | Breitengrad des Stores.                                                                                                                             |
| `openingHours`                   | object  | Öffnungszeiten des Stores.                                                                                                                          |
| `openingHours.{0-6}`             | array   | Reguläre Öffnungszeiten je Wochentag (0=Sonntag, 6=Samstag). Jeder Eintrag ist ein Array von Zeitfenstern. Ein leeres Array bedeutet “geschlossen”. |
| `openingHours.{0-6}[].startTime` | number  | Öffnungszeit in Sekunden seit Tagesbeginn (z.B. 08:00 Uhr = `28800`).                                                                               |
| `openingHours.{0-6}[].endTime`   | number  | Schließzeit in Sekunden seit Tagesbeginn (z.B. 18:00 Uhr = `64800`). Muss größer als `startTime` sein.                                              |
| `openingHours.specialDays`       | object  | Sonderöffnungszeiten. Der Key hat das Format `<monat>-<tag>` (z.B. `12-24`). Jeder Wert ist ein Array von Zeitfenstern (wie bei den Wochentagen).   |
| `clickAndCollect`                | boolean | Gibt an, ob der Markt für Click & Collect freigeschaltet ist.                                                                                       |
| `createdAt`                      | string  | Erstellungszeitpunkt (ISO 8601-Format, UTC, nur lesbar).                                                                                            |
| `updatedAt`                      | string  | Letzter Aktualisierungszeitpunkt (ISO 8601-Format, UTC, nur lesbar).                                                                                |

#### Beispiel des Datensatzes

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-99",
    "subshops": ["deutsch", "english"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 57600 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }],
            "12-25": []
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

## Verwendung der Methoden

### GET stores

Diese Methode liefert eine Liste aller Märkte aus dem Admin-Interface des Shops.

#### Beispiel

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

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "id": 42,
            "info": {
                "name": "Markt Musterstadt",
                "street": "Musterstra\u00dfe 1",
                "zipCode": "12345",
                "city": "Musterstadt",
                "country": "DE",
                "zipcodes": [
                    { "prefix": "123", "country": "DE" }
                ],
                "timeZone": "Europe/Berlin",
                "metadata": {}
            },
            "storageId": "storage-99",
            "subshops": ["deutsch"],
            "location": {
                "longitude": 13.405,
                "latitude": 52.52
            },
            "openingHours": {
                "0": [],
                "1": [{ "startTime": 28800, "endTime": 64800 }],
                "2": [{ "startTime": 28800, "endTime": 64800 }],
                "3": [{ "startTime": 28800, "endTime": 64800 }],
                "4": [{ "startTime": 28800, "endTime": 64800 }],
                "5": [{ "startTime": 28800, "endTime": 72000 }],
                "6": [{ "startTime": 36000, "endTime": 57600 }],
                "specialDays": {}
            },
            "clickAndCollect": true,
            "createdAt": "2025-01-15T10:30:00.000Z",
            "updatedAt": "2025-06-20T14:45:00.000Z"
        }
    ],
    "nextPageToken": "Mw",
    "totalCount": 1
}
```

#### Filterfelder

`id`, `subshops`, `clickAndCollect`, `storageId`, `createdAt`, `updatedAt`

#### Sortierfelder

`id`, `clickAndCollect`, `storageId`, `createdAt`, `updatedAt`

#### Fehlercodes

| **Fehler**       | **Typ**             | **Grund**                                                                                                                  |                                                |   |
| ---------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | - |
| 401 Unauthorized |                     | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Store-Daten. |                                                |   |
| 400 Bad Request  | "invalidValue"      | `size` ∉ \[1;300]                                                                                                          | `pageToken` ist keine Zahl oder kleiner als 0. |   |
| 400 Bad Request  | "unknownDataField"  | Ein Filter- oder Sortierfeld ist ungültig.                                                                                 |                                                |   |
| 400 Bad Request  | "unknownOperation"  | Ein Filtertyp ist ungültig.                                                                                                |                                                |   |
| 400 Bad Request  | "invalidCharacters" | `size` ist keine Ganzzahl. <br /> Ein Filterwert ist ungültig.                                                             |                                                |   |
| 400 Bad Request  | "syntaxError"       | `sort` enthält mehr als einen oder keinen ":".                                                                             |                                                |   |

### GET stores/\{id}

Diese Methode ruft die Details eines einzelnen Stores anhand seiner eindeutigen Store-ID ab.

#### Beispiel

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

#### Antwort

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-99",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 57600 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }]
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ**        | **Grund**                                                                                                                  |
| ---------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Store-Daten. |
| 400 Bad Request  | "invalidValue" | Die Store-ID ist ungültig (keine gültige Zahl).                                                                            |
| 404 Not Found    |                | Der Store mit der angegebenen ID wurde nicht gefunden.                                                                     |

### POST stores

Diese Methode erstellt einen neuen Store. Alle Felder außer `id`, `createdAt` und `updatedAt` sind bei der Erstellung erforderlich.

#### Beispiel

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

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "info": {
        "name": "Neuer Markt",
        "street": "Beispielstra\u00dfe 5",
        "zipCode": "54321",
        "city": "Beispielstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "543", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-10",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 9.993,
        "latitude": 53.551
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 64800 }],
        "6": [{ "startTime": 36000, "endTime": 43200 }],
        "specialDays": {}
    },
    "clickAndCollect": false
}
```

#### Antwort

Die Antwort enthält das vollständige Store-Objekt mit der zugewiesenen `id` sowie den Feldern `createdAt` und `updatedAt`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 43,
    "info": {
        "name": "Neuer Markt",
        "street": "Beispielstra\u00dfe 5",
        "zipCode": "54321",
        "city": "Beispielstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "543", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-10",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 9.993,
        "latitude": 53.551
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 64800 }],
        "6": [{ "startTime": 36000, "endTime": 43200 }],
        "specialDays": {}
    },
    "clickAndCollect": false,
    "createdAt": "2025-06-20T14:45:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ**            | **Grund**                                                                                                                      |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized |                    | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Store-Daten. |
| 400 Bad Request  | "badRequest"       | Der Request-Body ist kein gültiges JSON-Objekt.                                                                                |
| 400 Bad Request  | "missing"          | Ein erforderliches Feld fehlt im Request-Body. Das betroffene Feld wird im `errorContext` angegeben.                           |
| 400 Bad Request  | "invalidFormat"    | Ein Feld hat einen falschen Datentyp. Der erwartete Typ wird im `errorContext` unter `expectedType` angegeben.                 |
| 400 Bad Request  | "invalidValue"     | Ein Feldwert ist ungültig (z.B. ungültige Zeitzone, `startTime` ≥ `endTime`, ungültiges Datumsformat bei `specialDays`).       |
| 400 Bad Request  | "unknownDataField" | Ein unbekanntes Feld wurde im Request-Body gesendet.                                                                           |

### PUT stores/\{id}

Diese Methode aktualisiert einen bestehenden Store anhand seiner eindeutigen Store-ID. Es können einzelne oder mehrere Felder übergeben werden – nur die gesendeten Felder werden aktualisiert.

#### Beispiel

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

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "clickAndCollect": true,
    "storageId": "storage-77",
    "openingHours": {
        "6": [{ "startTime": 36000, "endTime": 50400 }],
        "specialDays": {
            "12-31": [{ "startTime": 28800, "endTime": 36000 }]
        }
    }
}
```

#### Antwort

Die Antwort enthält das vollständige aktualisierte Store-Objekt.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-77",
    "subshops": ["deutsch", "english"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 50400 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }],
            "12-31": [{ "startTime": 28800, "endTime": 36000 }]
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T15:00:00.000Z"
}
```

#### Fehlercodes

| **Fehler**       | **Typ**            | **Grund**                                                                                                                                                    |
| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 401 Unauthorized |                    | Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Aktualisieren von Store-Daten.                           |
| 400 Bad Request  | "invalidValue"     | Die Store-ID ist ungültig (keine gültige Zahl).                                                                                                              |
| 404 Not Found    |                    | Der Store mit der angegebenen ID wurde nicht gefunden.                                                                                                       |
| 400 Bad Request  | "badRequest"       | Der Request-Body ist kein gültiges JSON-Objekt.                                                                                                              |
| 400 Bad Request  | "missing"          | Ein Pflichtunterfeld fehlt in einem Array-Element. Betroffen: `startTime` oder `endTime` in Zeitfenstern, `prefix` oder `country` in Postleitzahl-Einträgen. |
| 400 Bad Request  | "invalidFormat"    | Ein Feld hat einen falschen Datentyp. Der erwartete Typ wird im `errorContext` unter `expectedType` angegeben.                                               |
| 400 Bad Request  | "invalidValue"     | Ein Feldwert ist ungültig (z.B. ungültige Zeitzone, `startTime` ≥ `endTime`, ungültiges Datumsformat bei `specialDays`).                                     |
| 400 Bad Request  | "unknownDataField" | Ein unbekanntes Feld wurde im Request-Body gesendet.                                                                                                         |

### DELETE stores/\{id}

Diese Methode löscht einen bestehenden Store anhand seiner eindeutigen Store-ID.

#### Beispiel

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

#### 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 oder verfügen nicht über die erforderlichen Rechte zum Löschen von Stores. |
| 400 Bad Request  | "invalidValue" | `id` ist ungültig.                                                                                                      |
| 404 Not Found    |                | Store mit `id`=`{id}` 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.