API-Referenz Meta-Daten - WEBSALE Dokumentation

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.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

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

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

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.

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
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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. `sort`-Richtung ist weder “asc” noch “desc”.
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.

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

{
    "createdAt": "2025-01-22 19:49:29",
    "id": 7,
    "metaDescription": "",
    "metaDescriptionSetManually": false,
    "metaTitle": "",
    "metaTitleSetManually": false,
    "resourceId": "Über uns",
    "updatedAt": "2025-01-22 19:49:29"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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.

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. Es handelt sich dabei um die numerische id des Datensatzes (nicht die resourceId). Zum Aktualisieren müssen entsprechende Schreibrechte für SEO-Daten vorhanden sein.

Beispiel

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

Request Body

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

Antwort

{
    "createdAt": "2025-01-09 11:07:55",
    "id": 5,
    "metaDescription": "Informieren Sie sich hier über die Allgemeinen Geschäftsbedingungen (AGB)",
    "metaDescriptionSetManually": true,
    "metaTitle": "My page",
    "metaTitleSetManually": true,
    "resourceId": "agb",
    "updatedAt": "2025-03-06 16:10:42"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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. `viewId` ist keine gültige Zahl.
400 Bad Request	”missing”	`viewId` fehlt.
404 Not Found		Es gibt keine Seite mit der angegebenen `id`.
503 Service Unavailable	”internalError”	Die Datenaktualisierung ist fehlgeschlagen.

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
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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.

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 numerischen id 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/5

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie verfügen nicht über die erforderlichen Rechte zum Löschen von SEO-Daten.
400 Bad Request	”invalidValue"	"stage” ist ungültig. `viewId` ist keine gültige Zahl.
400 Bad Request	”missing”	`viewId` fehlt.
404 Not Found		Die Seite wurde nicht gefunden.

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.

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

Request Body

{
    "items": [
        "cat1",
        "cat2"
    ]
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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.

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.

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

Request Body

{
    "items": [
        "prod1",
        "prod2"
    ]
}

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet.
403 Forbidden		Sie 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.

Aktualisierung aller SEO-Texten

Dieser Abschnitt beschreibt den Endpunkt zum manuellen Auslösen einer Aktualisierung aller SEO-Texte nach den konfigurierten Schemata.

PUT seo/texts/update

Dieser Endpunkt löst eine Aktualisierung aller SEO-Texte des Shops aus. Dabei werden Meta-Titel und Meta-Beschreibungen, die nicht manuell gesetzt wurden, anhand des konfigurierten Schemas neu generiert. Schreibrechte für SEO-Daten sind erforderlich.

Beispiel

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

Antwort

{
    "success": true
}

Fehlercodes

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

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 (Meta-Data Resource)

​Datenfelder

​Beispiel von einem Datensatz

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

​GET seo/texts/views

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​POST seo/texts/views

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT seo/texts/views/{viewId}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​PUT seo/texts/views/reset

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE seo/texts/views/{viewId}

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Meta-Daten von Kategorien

​PUT seo/texts/categories/reset

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Methoden für Meta-Daten von Produkten

​PUT seo/texts/products/reset

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Aktualisierung aller SEO-Texten

​PUT seo/texts/update

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder (Meta-Data Resource)

Datenfelder

Beispiel von einem Datensatz

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

GET seo/texts/views

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

POST seo/texts/views

Beispiel

Request Body

Antwort

Fehlercodes

PUT seo/texts/views/{viewId}

Beispiel

Request Body

Antwort

Fehlercodes

PUT seo/texts/views/reset

Beispiel

Request Body

Antwort

Fehlercodes

DELETE seo/texts/views/{viewId}

Beispiel

Antwort

Fehlercodes

Methoden für Meta-Daten von Kategorien

PUT seo/texts/categories/reset

Beispiel

Request Body

Antwort

Fehlercodes

Methoden für Meta-Daten von Produkten

PUT seo/texts/products/reset

Beispiel

Request Body

Antwort

Fehlercodes

Aktualisierung aller SEO-Texten

PUT seo/texts/update

Beispiel

Antwort

Fehlercodes

Support