API-Referenz Stores - WEBSALE Dokumentation

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/

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

{
    "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

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

Antwort

{
    "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. 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

https://www.<ihr-shop>.de/admin/api/v1/stores/42

Antwort

{
    "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

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

Request Body

{
    "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.

{
    "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

https://www.<ihr-shop>.de/admin/api/v1/stores/42

Request Body

{
    "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.

{
    "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

https://www.<ihr-shop>.de/admin/api/v1/stores/42

Antwort

{
    "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 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 eines Stores

​Beispiel des Datensatzes

​Verwendung der Methoden

​GET stores

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET stores/{id}

​Beispiel

​Antwort

​Fehlercodes

​POST stores

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT stores/{id}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE stores/{id}

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder eines Stores

Beispiel des Datensatzes

Verwendung der Methoden

GET stores

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET stores/{id}

Beispiel

Antwort

Fehlercodes

POST stores

Beispiel

Request Body

Antwort

Fehlercodes

PUT stores/{id}

Beispiel

Request Body

Antwort

Fehlercodes

DELETE stores/{id}

Beispiel

Antwort

Fehlercodes

Support