Mit dem Endpunkt seo/texts/ steht Ihnen eine Schnittstelle zur Verfügung, mit der Sie SEO-Meta-Daten für verschiedene Bereiche des Shops (z. B. Seiten, Kategorien, Produkte) verwalten können. Die API ermöglicht es, Meta-Titel und Meta-Beschreibungen manuell zu pflegen oder sie bei Bedarf auf die automatisch generierten Standardwerte zurückzusetzen.

Meta-Daten werden dabei entweder direkt gesetzt oder auf Basis hinterlegter Schemata erzeugt.

Inhaltsverzeichnis

1 1. Unterstützte Methoden
2 2. Datenfelder (Meta-Data Resource)
3 3. Methoden für Meta-Daten von Shop-Seiten (Views)
4 4. Methoden für Meta-Daten von Kategorien
- 4.1 4.1 PUT seo/texts/categories/reset
5 5. Methoden für Meta-Daten von Produkten
- 5.1 5.1 PUT seo/texts/products/reset
6 6. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Meta-Daten der Shop-Seiten	seo/texts/
Zurücksetzen auf Standardeinstellungen	seo/texts/…/reset

2. Datenfelder (Meta-Data Resource)

Meta-Daten von Kategorie- und Produkt-Seiten werden in benutzerdefinierten Feldern metaTitle und metaDescription gespeichert. Um damit zu arbeiten, werden Endpunkte categories/ und products/ verwendet. Meta-Daten der Start-Seite befinden sich in subshop-spezifischen Konfigurationen und können über API nicht abgefragt werden. Für Meta-Daten der sonstigen Shop-Seiten gibt es eine Tabelle in der Datenbank.

Datenfelder:

Name	Typ	Bedeutung

Name	Typ	Bedeutung
id	Integer	Eindeutige ID des Datensatzes
resourceId	String	Eindeutiger Name der Seite einschließlich Pfad.
metaTitle	String	Enthält den Meta-Titel der Seite.
metaTitleSetManually	Boolean	Gibt an, ob der Meta-Titel manuell gesetzt ist und sich nach dem Aktualisieren vom Schema nicht ändern soll.
metaDescription	String	Enthält die Meta-Beschreibung der Seite.
metaDescriptionSetManually	Boolean	Gibt an, ob die Meta-Beschreibung manuell gesetzt ist und sich nach dem Aktualisieren vom Schema nicht ändern soll.
createdAt	String	Zeitpunkt, zu dem die Meta-Daten erstellt wurden (ISO 8601-Format, UTC).
updatedAt	String	Zeitpunkt der letzten Aktualisierung der Meta-Daten (ISO 8601-Format, UTC).

Beispiel von einem Datensatz:

{
    "createdAt": "2025-01-22 19:49:29",
    "id": 7,
    "metaDescription": "some text",
    "metaDescriptionSetManually": true,
    "metaTitle": "some generated text",
    "metaTitleSetManually": false,
    "resourceId": "newPage2",
    "updatedAt": "2025-01-22 19:49:34"
}

3. Methoden für Meta-Daten von Shop-Seiten (Views)

In diesem Abschnitt finden Sie alle Endpunkte zur Verwaltung von Meta-Daten für Shop-Seiten, die intern als Views bezeichnet werden. Sie können Meta-Daten wie Titel und Beschreibung aktualisieren oder zurücksetzen, Daten der vorhandenen Seiten abrufen, neue Seiten registrieren sowie einzelne Einträge löschen.

Die Views werden über ihre resourceId eindeutig identifiziert.

Rechte für SEO-Daten sind erforderlich.

3.1 GET seo/texts/views

Diese Methode liefert eine paginierte Liste von Meta-Daten (z. B. Titel und Beschreibung) aller im Shop vorhandenen Seitenressourcen, die für SEO-Zwecke gepflegt werden können. Mithilfe der Filter- und Sortierparameter lassen sich gezielt nur bestimmte Einträge laden – etwa nur Seiten mit manuell gesetzten Meta-Titeln oder -Beschreibungen.

Die Anzahl der Einträge pro Seite kann mit dem Parameter size im Bereich von 1 bis 300 festgelegt werden.

Zur Nutzung sind Leserechte für SEO-Daten erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/views

Antwort:

{
    "endReached": true,
    "items": [
        {
            "createdAt": "2025-01-09 11:07:55",
            "id": 5,
            "metaDescription": "",
            "metaDescriptionSetManually": true,
            "metaTitle": "My page",
            "metaTitleSetManually": true,
            "resourceId": "newPage",
            "updatedAt": "2025-03-06 16:10:42"
        },
        ...
    ],
    "nextPageToken": "NA",
    "totalCount": 5
}

Filterfelder:

createdAt, updatedAt, metaTitleSetManually, metaDescriptionSetManually

Sortierfelder:

createdAt, updatedAt, resourceId, metaTitle, metaDescription

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 SEO-Daten.
400 Bad Request	"invalidValue"	"stage" ist ungültig. \| `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 ":".
503 Service Unavailable	"internalError"	Das Lesen von Daten ist fehlgeschlagen.

3.2 POST seo/texts/views

Mit dieser Methode kann eine neue Shop-Seite zur SEO-Verwaltung registriert werden.

Beim Anlegen werden metaTitle und metaDescription zunächst leer gespeichert. Es muss ein eindeutiger Seitenname (viewName) übergeben werden, der als resourceId dienen wird. Der Name darf noch nicht existieren.

Für diese Aktion sind Erstellrechte für SEO-Daten erforderlich.

Hinweis: Wenn eine neue Shop-Seite nicht manuell registriert wird, werden für sie Meta-Daten automatisch nach dem Schema aus der Konfiguration generiert, wenn auf sie zum ersten Mal zugegriffen wird.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/views

Request Body:

{
    "viewName": "Über uns"
}

Antwort:

{
    "success": 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 SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidValue"	"stage" ist ungültig.
409 Conflict	"existsAlready"	Der Name steht schon in der Tabelle.
503 Service Unavailable	"internalError"	Die Seite konnte nicht registriert werden.

3.3 PUT seo/texts/views/{viewId}

Mit dieser Methode können die SEO-Meta-Daten (Titel und Beschreibung) einer bestimmten Shop-Seite gezielt aktualisiert werden. Es dürfen ausschließlich metaTitle und/oder metaDescription verändert werden – begleitende technische Felder wie metaTitleSetManually, metaDescriptionSetManually und updatedAt werden automatisch gesetzt.

Die Angabe der viewId in der URL ist erforderlich und verweist auf die eindeutige Seitenressource.

Zum Aktualisieren müssen entsprechende Schreibrechte für SEO-Daten vorhanden sein.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/views/agb

Request Body:

{
    "metaDescription": "Informieren Sie sich hier über die Allgemeinen Geschäftsbedingungen (AGB)"
}

Antwort:

{
    "success": 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 Schreiben von SEO-Daten.
400 Bad Request		Request body oder `viewId` konnten nicht geladen werden.
400 Bad Request	"invalidValue"	"stage" ist ungültig.
400 Bad Request	"missing"	`viewId` fehlt.
404 Not Found		Es gibt keine Seite mit `resourceId=viewId`.
503 Service Unavailable	"internalError"	Die Datenaktualisierung ist fehlgeschlagen.

3.4 PUT seo/texts/views/reset

Dieser Endpunkt setzt die manuell gesetzten Meta-Daten ausgewählter Seiten zurück und ersetzt sie durch automatisch generierte Werte gemäß dem festgelegten Schema. Die Felder metaTitleSetManually und metaDescriptionSetManually werden dabei auf false gesetzt.

Schreibrechte für SEO-Daten sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/views/reset

Request Body:

{
    "items": [
        "newPage",
        "newPage2"
    ]
}

Antwort:

{
    "success": 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 Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidValue"	"stage" ist ungültig.

3.5 DELETE seo/texts/views/{viewId}

Mit diesem Endpunkt lassen sich die Meta-Daten (Titel und Beschreibung) einer registrierten Seite gezielt löschen. Die Seite wird anhand ihrer resourceId (viewId) identifiziert.

Für die Ausführung sind Löschrechte für SEO-Daten erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/views/agb

Antwort:

{}

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Löschen von SEO-Daten.
400 Bad Request	"invalidValue"	"stage" ist ungültig.
404 Not Found		Die Seite wurde nicht gefunden.

4. Methoden für Meta-Daten von Kategorien

Dieser Abschnitt behandelt die Verarbeitung von SEO-Meta-Daten für Kategorien. Die API erlaubt ausschließlich das Zurücksetzen manuell gepflegter Meta-Titeln und Meta-Beschreibungen.

Dabei werden bestehende Inhalte entfernt und durch Werte ersetzt, die anhand eines Schemas generiert werden.

4.1 PUT seo/texts/categories/reset

Setzt die Meta-Daten der übergebenen Kategorien zurück. Manuell gesetzte Felder metaTitle und metaDescription werden durch automatisch generierte Inhalte ersetzt. Die Felder metaTitleSetManually und metaDescriptionSetManually werden dabei auf false gesetzt.

Schreibrechte für SEO-Daten sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/categories/reset

Antwort:

{
    "success": true
}

Fehler	Typ	Grund

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidValue"	"stage" ist ungültig.

5. Methoden für Meta-Daten von Produkten

Für Produkte steht ebenfalls nur eine Reset-Option zur Verfügung. Die API bietet keine Möglichkeit, einzelne SEO-Felder direkt zu aktualisieren. Stattdessen werden manuelle Meta-Angaben vollständig durch automatisch generierte Daten ersetzt.

5.1 PUT seo/texts/products/reset

Dieser Endpunkt löscht die manuell eingetragenen Meta-Daten von Produkten und ersetzt sie durch generierte Inhalte. Die Felder metaTitleSetManually und metaDescriptionSetManually werden dabei auf false gesetzt.

Schreibrechte für SEO-Daten sind erforderlich.

Beispiel:

https://www.<ihr-shop>.de/admin/api/v1/seo/texts/products/reset

Antwort:

{
    "success": 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 Schreiben von SEO-Daten.
400 Bad Request		Request body konnte nicht geladen werden.
400 Bad Request	"invalidValue"	"stage" ist ungültig.

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

API-Referenz Meta-Daten

Inhaltsverzeichnis

1. Unterstützte Methoden

2. Datenfelder (Meta-Data Resource)

Datenfelder:

Beispiel von einem Datensatz:

3. Methoden für Meta-Daten von Shop-Seiten (Views)

3.1 GET seo/texts/views

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 POST seo/texts/views

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.3 PUT seo/texts/views/{viewId}

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.4 PUT seo/texts/views/reset

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.5 DELETE seo/texts/views/{viewId}

Beispiel:

Antwort:

4. Methoden für Meta-Daten von Kategorien

4.1 PUT seo/texts/categories/reset

Beispiel:

Antwort:

5. Methoden für Meta-Daten von Produkten

5.1 PUT seo/texts/products/reset

Beispiel:

Antwort:

Fehlercodes:

6. Support