Der Endpunkt sitemaps/ stellt Ihnen eine Schnittstelle zur Verfügung, mit der Sie XML-Sitemaps in Ihrem Shop-System verwalten können. Über die API lassen sich neue Sitemaps erstellen, bestehende bearbeiten oder löschen sowie manuelle und geplante Generierungen durchführen. Zusätzlich ermöglicht die Schnittstelle das Abfragen von Statusinformationen zu vergangenen oder laufenden Generierungsvorgängen.

Sitemaps können dabei individuell für bestimmte Subshops und auf Basis von frei definierbaren Vorlagen generiert werden. Die REST-API erlaubt eine präzise Steuerung über Parameter wie maximale Dateigröße oder maximale Anzahl von URLs pro Datei – so lässt sich die Auslieferung der Sitemaps gezielt optimieren.

Die Nutzung dieser API erfordert entsprechende Berechtigungen für das Lesen, Schreiben oder Generieren von Sitemaps.

Inhaltsverzeichnis:

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Sitemaps	sitemaps/
Sitemap-Vorlagen	sitemaps/templates
Generierung	sitemaps/generate

2. Datenfelder

2.1 Datenfelder der Sitemaps

Sitemaps definieren, welche URLs eines Shops in welcher Form exportiert werden sollen. Sie basieren jeweils auf einer Sitemap-Vorlage und enthalten zusätzliche Parameter, z. B. zur Dateigröße, Anzahl der Einträge oder Subshop-Zuordnung. Sitemaps können für verschiedene Subshops erstellt werden und lassen sich zu definierten Zeiten automatisch exportieren.

Die erzeugten Dateien werden standardmäßig im Verzeichnis /sitemaps/<subshopId> abgelegt. Sie sind öffentlich zugänglich und können z. B. über eine URL wie www.ihre-shopdomain.de/sitemap.xml aufgerufen werden.

Name	Typ	Verwendung

Name	Typ	Verwendung
id	Integer	Eindeutige ID der Sitemap.
active	Boolean	Gibt an, ob die Sitemap für den Export aktiv ist.
name	String	Name der Sitemap.
fileName	String	Name der Datei, die generiert wird.
subshopIds	String	Liste der Subshop-IDs für die Sitemap. Wenn leer, werden die Sitemaps für alle Subshops exportiert.
templateId	Integer	Eindeutige ID der verwendeten Sitemap-Vorlage
maxFileSize	Integer	Maximale Dateigröße einer Sitemap-Datei
maxFileEntries	Integer	Maximale Anzahl der URLs in einer Sitemap-Datei
options	Objekt	Zusätzliche Einstellungen (zurzeit nur `exportCharset`)
writeIntoRobots	Boolean	Gibt an, ob ein Eintrag in die robots.txt-Datei geschrieben werden soll.
exportAfterImport	Boolean	Gibt an, ob die Sitemap nach dem Import von Produktdaten exportiert werden soll.
exportPlan	String	Stunden, an denen Sitemaps exportiert werden.
exportStatus	Integer	Status des Exportprozesses (z. B. beendet, beginnt, fehlgeschlagen) Mögliche Werte: `0 = Idle` `1 = Finished` `2 = Error` `3 = Starting` `4 = Running`
protocolId	Integer	Eindeutige ID des Protokolls.
lastExportStarted	String	Zeitpunkt des letzten Exportstarts.
lastExportFinished	String	Zeitpunkt des letzten erfolgreichen Exports.
createdAt	String	Zeitpunkt der Erstellung (ISO 8601-Format, UTC).
updatedAt	String	Zeitpunkt der letzten Aktualisierung (ISO 8601-Format, UTC).

Beispiel:

{
    "active": true,
    "createdAt": "2025-03-19 11:06:47",
    "exportAfterImport": false,
    "exportPlan": [],
    "exportStatus": 1,
    "fileName": "sitemap121",
    "id": 129,
    "lastExportFinished": "0000-00-00 00:00:00",
    "lastExportStarted": "0000-00-00 00:00:00",
    "maxFileEntries": 50000,
    "maxFileSize": 52428800,
    "name": "sitemap1217",
    "options": {
        "exportCharset": "utf-8"
    },
    "protocolId": 10,
    "subshopIds": [
        "deutsch"
    ],
    "templateId": 3,
    "updatedAt": "2025-03-19 11:31:21",
    "writeIntoRobots": false
}

Hinweise zur Aufteilung von Sitemaps

Um die Ladezeit von Suchmaschinen zu optimieren und technischen Vorgaben gerecht zu werden, kann die Generierung von Sitemaps automatisch auf mehrere Dateien aufgeteilt werden. Dies geschieht, wenn eine der folgenden Grenzen überschritten wird:

Maximale Anzahl an URLs pro Datei: Standardmäßig 50.000 URLs
Maximale Dateigröße pro Datei: Standardmäßig 50 MB

Diese Grenzen können über die Felder maxFileEntries und maxFileSize pro Sitemap individuell konfiguriert werden. Wird eine dieser Grenzen überschritten, erzeugt das System automatisch eine neue Sitemap-Datei mit einem fortlaufenden Zähler im Dateinamen.

2.2 Datenfelder der Sitemap-Vorlagen

Sitemap-Vorlagen (Templates) beschreiben die Struktur und den Inhalt einer Sitemap. Sie geben an, welche Ressourcen (z. B. Produkte, Kategorien oder Inhalte) exportiert werden und welche Felder dabei einbezogen werden sollen – etwa loc, lastmod, priority oder changefreq.

Jede Sitemap muss auf einer Vorlage basieren. Änderungen an einer Vorlage beeinflussen alle Sitemaps, die darauf aufbauen. Auf diese Weise lassen sich verschiedene Exportkonfigurationen effizient wiederverwenden und zentral verwalten.

Name	Typ	Verwendung

Name	Typ	Verwendung
id	Integer	Eindeutige ID der Sitemap-Vorlage
name	String	Name der Sitemap-Vorlage
content	String	Der Inhalt der Vorlage. Hier darf die Template-Sprache verwendet werden.
createdAt	String	Zeitpunkt der Erstellung
updatedAt	String	Zeitpunkt der letzten Aktualisierung

Beispiel:

{
    "content": "{{ var $product = true }}\n{{ while($product) }}\n{{ $product = $wsProducts.loadNext() }}\n<url>\n  <loc>{{= $wsViews.url('Product', {productId: $product.id}, 'absolute') }}</loc>\n  <lastmod>2005-01-01</lastmod>\n  <changefreq>monthly</changefreq>\n  <priority>0.8</priority>\n</url>\n{{ /while }}",
    "createdAt": "2025-04-30 14:55:27",
    "id": 5,
    "name": "products",
    "updatedAt": "2025-04-30 14:55:27"
}

3. Methoden für Sitemaps

Über die folgenden Endpunkte können bestehende Sitemaps im System abgerufen, bearbeitet, erstellt oder gelöscht werden. Zusätzlich lassen sich Statusinformationen zum letzten Export sowie zugehörige Protokolle abfragen.

Um diese Endpunkte zu nutzen, müssen entsprechende Berechtigungen für den Zugriff auf Sitemap-Daten vorhanden sein.

3.1 GET sitemaps

Mit dieser Methode können Sie eine Liste aller im System vorhandenen Sitemaps abrufen.

Die Antwort enthält zu jeder Sitemap die zugehörigen Einstellungen sowie – falls bereits erfolgt – Informationen über erzeugte Dateien. Die Daten lassen sich nach verschiedenen Kriterien filtern oder sortieren, z. B. nach Subshop, Exportstatus oder Dateiname.

Damit der Endpunkt verwendet werden kann, müssen entsprechende Berechtigungen zum Lesen von Sitemaps vorhanden sein.

Beispiel:

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

Antwort:

{
    "endReached": true,
    "items": [
        {
            "filelist": [],
            "sitemap": {
                "active": true,
                "createdAt": "2025-02-14 11:11:53",
                "exportAfterImport": false,
                "exportPlan": [
                    0
                ],
                "exportStatus": 0,
                "fileName": "123",
                "id": 1,
                "lastExportFinished": "0000-00-00 00:00:00",
                "lastExportStarted": "0000-00-00 00:00:00",
                "maxFileEntries": 0,
                "maxFileSize": 0,
                "name": "123",
                "options": {
                    "exportCharset": "utf-8"
                },
                "protocolId": 0,
                "subshopIds": [
                    "deutsch",
                    "english"
                ],
                "templateId": 1,
                "updatedAt": "2025-02-14 11:11:53",
                "writeIntoRobots": true
            },
            "templateName": "1233122"
        },
        ...
    ],
    "nextPageToken": "MQ",
    "totalCount": 2
}

Filterfelder:

id, active, name, fileName, templateId, subshopIds, maxFileSize, maxFileEntries, exportAfterImport, exportStatus, lastExportStarted, lastExportFinished, createdAt, updatedAt

Sortierfelder:

id, active, name, fileName, templateId, subshopIds, maxFileSize, maxFileEntries, exportAfterImport, exportStatus, lastExportStarted, lastExportFinished, createdAt, updatedAt

Fehlercodes:

Fehler	Typ	Grund

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

3.2 GET sitemaps/{id}

Mit dieser Methode kann ein einzelner Sitemap-Eintrag anhand seiner ID abgerufen werden. Die Antwort enthält sämtliche Konfigurationsdaten der Sitemap, einschließlich Subshop-Zuordnung, Exportstatus und Einstellungen zur Generierung.

Damit der Endpunkt verwendet werden kann, müssen entsprechende Berechtigungen zum Lesen von Sitemaps vorhanden sein.

Beispiel:

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

Antwort:

{
    "active": true,
    "createdAt": "2025-02-14 11:11:53",
    "exportAfterImport": false,
    "exportPlan": [
        0
    ],
    "exportStatus": 0,
    "fileName": "123",
    "id": 1,
    "lastExportFinished": "0000-00-00 00:00:00",
    "lastExportStarted": "0000-00-00 00:00:00",
    "maxFileEntries": 0,
    "maxFileSize": 0,
    "name": "123",
    "options": {
        "exportCharset": "utf-8"
    },
    "protocolId": 0,
    "subshopIds": [
        "deutsch",
        "english"
    ],
    "templateId": 1,
    "updatedAt": "2025-02-14 11:11:53",
    "writeIntoRobots": true
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Sitemaps.
400 Bad Request	"invalidValue"	`id` ist ungültig.
404 Not Found		Sitemap mit `id`=`{id}` wurde nicht gefunden.

3.3 GET sitemaps/{id}/status

Mit dieser Methode kann der aktuelle Exportstatus einer bestimmten Sitemap abgefragt werden. Sie liefert pro Subshop den jeweiligen Status, etwa ob ein Export erfolgreich abgeschlossen wurde oder fehlgeschlagen ist. Obwohl der Endpunkt derzeit keine echten Prozesse verfolgt, stellt er strukturierte Statusdaten bereit.

Damit der Endpunkt verwendet werden kann, müssen entsprechende Berechtigungen zum Lesen von Sitemaps vorhanden sein.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/sitemaps/1/status

Antwort:

[
	{
		"createdAt": "2025-02-21 08:43:42",
		"exportStatus": 2,
		"fileCount": 0,
		"fileName": "",
		"files": [],
		"id": 1,
		"lastExportError": "",
		"lastExportFinished": "0000-00-00 00:00:00",
		"lastExportStarted": "2025-02-21 08:47:58",
		"sitemapId": 1,
		"subshopId": "deutsch",
		"updatedAt": "2025-02-21 08:47:58"
	},
	{
		"createdAt": "2025-02-21 08:43:42",
		"exportStatus": 2,
		"fileCount": 0,
		"fileName": "",
		"files": [],
		"id": 2,
		"lastExportError": "",
		"lastExportFinished": "0000-00-00 00:00:00",
		"lastExportStarted": "2025-02-21 08:47:58",
		"sitemapId": 1,
		"subshopId": "english",
		"updatedAt": "2025-02-21 08:47:58"
	}
]

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Sitemaps.
400 Bad Request	"invalidValue"	`id` ist ungültig.
404 Not Found		Die Sitemap wurde nicht gefunden.

3.4 GET sitemaps/protocols

Mit dieser Methode kann eine Liste aller Protokolleinträge für Sitemaps abgerufen werden.

Die Protokolle enthalten Metainformationen zu vergangenen Exportvorgängen – etwa wann eine Sitemap exportiert wurde, welcher Subshop betroffen war und welchen Status der Export hatte.

Um diesen Endpunkt nutzen zu können, müssen entsprechende Berechtigungen zum Lesen von Sitemaps vorhanden sein.

Beispiel:

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

Antwort:

{
	"endReached": true,
	"items": [
		{
			"createdAt": "2025-02-21 08:43:42",
			"exportError": "",
			"exportFinished": "0000-00-00 00:00:00",
			"exportStarted": "0000-00-00 00:00:00",
			"exportStatus": 1,
			"id": 1,
			"sitemapName": "my sitemap",
			"subshopData": [
				{
					"createdAt": "",
					"exportError": "",
					"exportFinished": "0000-00-00 00:00:00",
					"exportStarted": "2025-02-21 08:43:42",
					"exportStatus": 2,
					"fileCount": 0,
					"fileName": "123.xml",
					"name": "",
					"subshopId": "deutsch",
					"updatedAt": "",
					"writeIntoRobots": false
				},
				{
					"createdAt": "",
					"exportError": "",
					"exportFinished": "0000-00-00 00:00:00",
					"exportStarted": "2025-02-21 08:43:42",
					"exportStatus": 2,
					"fileCount": 0,
					"fileName": "123.xml",
					"name": "",
					"subshopId": "english",
					"updatedAt": "",
					"writeIntoRobots": false
				}
			],
			"templateName": "defaultTemplate",
			"updatedAt": "2025-02-21 08:43:47"
		},
		...
	],
	"nextPageToken": "NQ",
	"totalCount": 6
}

Filterfelder:

id, sitemap, template, subshopIds, exportStatus, lastExportStarted, lastExportFinished, createdAt, updatedAt

Sortierfelder:

id, sitemap, template, exportStatus, lastExportStarted, lastExportFinished, createdAt, updatedAt

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Man ist kein Administrator und hat keine Berechtigung zum Lesen von Sitemaps.
400 Bad Request	"invalidValue"	`size` ∉ [1;300] \| `sort` ∉ {"asc", "desc"} \| `pageToken` ist keine Zahl oder kleiner als 0.
400 Bad Request	"invalidCharacters"	`size` ist keine Ganzzahl. \| Filterwert ist ungültig.
400 Bad Request	"unknownDataField"	Ein Filter- oder Sortierfeld ist ungültig.
400 Bad Request	"unknownOperation"	Ein Filtertyp ist ungültig.
400 Bad Request	"syntaxError"	`sort` enthält mehr als einen oder keinen ":".

3.5 POST sitemaps

Diese Methode ermöglicht das Erstellen eines neuen Sitemap-Eintrags mit allen relevanten Parametern wie Dateiname, Template-Zuweisung, Exportzeitpunkten und betroffenen Subshops.

Damit diese Methode verwendet werden kann, müssen entsprechende Berechtigungen zum Erstellen von Sitemap-Daten vorhanden sein.

Beispiel:

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

Request Body:

{
    "name": "123",
    "fileName": "123",
    "writeIntoRobots": true,
    "active": true,
    "exportAfterImport": false,
    "templateId": 1,
    "subshopIds": [
        "deutsch",
        "english"
    ],
    "exportPlan": [
        0
    ],
    "maxFileSize": 0,
    "maxFileEntries": 0,
    "indexFileName": "123_index"
}

Antwort:

{
    "active": true,
    "createdAt": "",
    "exportAfterImport": false,
    "exportPlan": [
        0
    ],
    "exportStatus": 0,
    "fileName": "123",
    "id": 1,
    "lastExportFinished": "",
    "lastExportStarted": "",
    "maxFileEntries": 0,
    "maxFileSize": 0,
    "name": "123",
    "options": {
        "exportCharset": "utf-8"
    },
    "protocolId": 0,
    "subshopIds": [
        "deutsch",
        "english"
    ],
    "templateId": 1,
    "updatedAt": "",
    "writeIntoRobots": true
}

Fehlercodes:

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Sitemaps.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidValue"	`templateId` ist ungültig. \| `options` existiert und ist kein Objekt.
400 Bad Request	"invalidFormat"	`name` oder `fileName` sind keine Strings. `active`, `exportAfterImport` oder `writeIntoRobots` sind keine Booleans. `templateId`, `maxFileEntries` oder `maxFileSize` sind keine Ganzzahlen. `exportPlan` ist kein Array von Ganzzahlen. `subshopIds` ist kein Array. `options.exportCharset` existiert und ist kein String.
400 Bad Request	"missing"	`name`, `active`, `fileName`, `templateId`, `exportAfterImport`, `exportPlan`, `maxFileEntries`, `maxFileSize`, `writeIntoRobots` oder `subshopIds` fehlen.
400 Bad Request	"duplicateEntry"	Der neue Dateiname wurde schon verwendet.

3.6 PUT sitemaps/{id}

Diese Methode ermöglicht das Aktualisieren einer bestehenden Sitemap anhand ihrer eindeutigen ID.

Es können sowohl technische Parameter (z. B. Dateiname, Template-Zuordnung, Exportoptionen) als auch organisatorische Einstellungen (z. B. betroffene Subshops, Zeitpläne) geändert werden.

Damit diese Methode verwendet werden kann, müssen entsprechende Berechtigungen zum Schreiben von Sitemap-Daten vorhanden sein.

Beispiel:

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

Request Body:

{
    "name": "my sitemap",
    "fileName": "123",
    "writeIntoRobots": true,
    "active": true,
    "exportAfterImport": false,
    "templateId": 1,
    "subshopIds": [
        "deutsch",
        "english"
    ],
    "maxFileEntries": 50000,
    "maxFileSize": 52428800,
    "exportPlan": [
        0
    ],
    "indexFileName": "123_index"
}

API-Referenz Sitemaps

Inhaltsverzeichnis:

1. Unterstützte Methoden

2. Datenfelder

2.1 Datenfelder der Sitemaps

Beispiel:

Hinweise zur Aufteilung von Sitemaps

2.2 Datenfelder der Sitemap-Vorlagen

Beispiel:

3. Methoden für Sitemaps

3.1 GET sitemaps

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET sitemaps/{id}

Beispiel:

Antwort:

Fehlercodes:

3.3 GET sitemaps/{id}/status

Antwort:

Fehlercodes:

3.4 GET sitemaps/protocols

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.5 POST sitemaps

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.6 PUT sitemaps/{id}

Beispiel:

Request Body:

Antwort: