API-Referenz Textbausteine - WEBSALE Dokumentation

Der Endpunkt /text stellt eine Schnittstelle zur Verwaltung von Textbausteinen in unserem Shopsystem bereit. Darüber können Sie sprachspezifische Variablen definieren, die innerhalb von Templates verwendet werden. Änderungen an diesen Texten können bequem über das Admin-Interface oder automatisiert per API vorgenommen werden, ohne dass die Templates selbst angepasst werden müssen. Zusätzlich bietet die Schnittstelle Funktionen zum Abrufen, Bearbeiten und Löschen einzelner Textbausteine sowie zum Publizieren der Änderungen.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE
Textbausteine	text
Publizieren	text/publish

Datenfelder eines Textbausteins

Name	Typ	Bedeutung
variable	String	Name der Textvariablen, über die der Inhalt im Template angesprochen wird.
translations	Objekt	Array von Textbausteindaten
translations.id	String	Eindeutiger Index des Textbausteins in der Datenbank (fortlaufende Nummer).
translations.text	String	Der tatsächliche Inhalt des Textbausteins (z. B. ein Hinweistext oder eine Überschrift).
translations.languageId	String	Sprachcode (z. B. `DE`, `EN`) der Sprache, zu der dieser Textbaustein gehört.
translations.author	Integer	ID des Benutzers, der die letzte Änderung an diesem Eintrag vorgenommen hat.
translations.system	Boolean	Gibt an, ob der Textbaustein standardmäßig vom System bereitgestellt wird.
translations.used	Boolean	Wird auf `true` gesetzt, wenn der Textbaustein in einem Template verwendet wurde.
translations.changedAt	String	Zeitpunkt der letzten Änderung des Textbausteins (ISO 8601-Format, UTC).
translations.configReferences	Integer	Anzahl der Konfigurationsreferenzen, die auf diesen Textbaustein verweisen. Ist der Wert größer als 0, kann der Textbaustein nicht gelöscht werden.

Beispiel

{
    "translations": {
        "DE": {
            "author": 3,
            "changedAt": "2025-04-01T14:23:00Z",
            "configReferences": 0,
            "id": "42",
            "languageId": "DE",
            "system": true,
            "text": "In den Warenkorb",
            "used": true
        },
        "EN": {
            "author": 3,
            "changedAt": "2025-04-01T14:23:00Z",
            "configReferences": 0,
            "id": "43",
            "languageId": "EN",
            "system": true,
            "text": "Add to cart",
            "used": true
        }
    },
    "variable": "button.addToCart"
}

Methoden für Textbausteine

Die hier dokumentierten Methoden bieten eine Schnittstelle zur Verwaltung von Textbausteinen im Shop-System. Sie ermöglichen das Laden, Erstellen, Aktualisieren und Löschen von Variablen, die sprachabhängige Texte enthalten – beispielsweise für Buttons, Fehlermeldungen oder andere UI-Elemente. Jeder Textbaustein kann in mehreren Sprachen vorliegen. Um diese Methoden nutzen zu können, müssen entsprechende Berechtigungen zum Lesen, Schreiben, Erstellen oder Löschen von Textbausteinen vorhanden sein.

3.1 GET text

Mit dieser Methode wird eine Liste aller verfügbaren Textbausteine inklusive ihrer Übersetzungen geladen. Jeder Eintrag enthält die zugehörige Variable sowie die vorhandenen Sprachversionen mit zusätzlichen Metainformationen wie Änderungszeitpunkt und Autor. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Textbausteinen vorhanden sein.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "translations": {
                "DE": {
                    "author": 3,
                    "changedAt": "2025-04-01T14:23:00Z",
                    "configReferences": 0,
                    "id": "42",
                    "languageId": "DE",
                    "system": true,
                    "text": "In den Warenkorb",
                    "used": true
                },
                "EN": {
                    "author": 3,
                    "changedAt": "2025-04-01T14:23:00Z",
                    "configReferences": 0,
                    "id": "43",
                    "languageId": "EN",
                    "system": true,
                    "text": "Add to cart",
                    "used": true
                }
            },
            "variable": "button.addToCart"
        }
    ],
    "nextPageToken": "MTAw",
    "totalCount": 1
}

Filterfelder

variable, text, author, system, used, changedAt

Sortierfelder

variable, text, languageId, author, system, used, changedAt

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Textbausteinen.
400 Bad Request	”invalidValue”
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 ”:”.

GET text/authors

Mit dieser Methode wird eine Liste der Benutzer-IDs zurückgegeben, die mindestens einen Textbaustein bearbeitet haben. Die Daten können beispielsweise zur Filterung oder Analyse der Autorenaktivität verwendet werden. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Textbausteinen vorhanden sein.

Beispiel

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

Antwort

{
    "items": [
        {
            "author": "1"
        }
    ],
    "totalCount": 1
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Textbausteinen.

GET text/{id}

Mit dieser Methode werden alle Übersetzungen eines bestimmten Textbausteins geladen, identifiziert über den Namen der Variable. Für jede Sprache wird ein eigener Eintrag mit Informationen wie Textinhalt, Bearbeiter und Änderungszeitpunkt zurückgegeben. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Lesen von Textbausteinen vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/text/button.addToCart

Antwort

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": true
    },
    {
        "author": 1,
        "changedAt": "2024-12-18T14:44:54.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Add to cart",
        "used": true
    }
]

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Textbausteinen.

POST text

Mit dieser Methode kann eine neue Textvariable mit mehreren Sprachversionen erstellt werden. Dabei werden der Name der Variable name und mindestens ein Sprachobjekt mit Sprache data.languageId und Text data.text übergeben. Die Variable muss eindeutig sein – ein Eintrag mit gleichem Namen darf noch nicht existieren. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Erstellen von Textbausteinen vorhanden sein.

Beispiel

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

Request Body

{
    "name": "button.addToCart",
    "data": [
        {
            "languageId": "DE",
            "text": "In den Warenkorb"
        },
        {
            "languageId": "EN",
            "text": "Add to cart"
        }
    ]
}

Antwort

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": false
    },
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Add to cart",
        "used": false
    }
]

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Textbausteinen.
400 Bad Request		Request body konnte nicht geladen werden oder die Variable nicht erzeugt werden.
400 Bad Request	”invalidValue”	`name` oder `data.languageId` ist ein leerer String, oder ein data-Element ist kein Objekt.
400 Bad Request	”invalidFormat”	`name`, `data.languageId` oder `data.text` sind keine Strings, oder `data` ist kein Array.
400 Bad Request	”invalidCharacters”	Der Variablenname enthält ungültige Zeichen.
400 Bad Request	”missing”	`name`, `data`, `data.languageId` oder `data.text` wurden nicht angegeben.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body oder in einem data-Element übergeben.
409 Conflict		Eine Variable mit dem selben Namen existiert bereits.

POST text/{id}/duplicate

Mit dieser Methode kann eine vorhandene Textvariable dupliziert werden. Dabei werden alle Sprachversionen und Eigenschaften der Originalvariable übernommen. Der Name der neuen Variable wird automatisch generiert, indem an das Ende des ursprünglichen Namens eine Nummer angehängt wird. Falls der Ursprungsname noch keine Zahl am Ende enthält, wird die Ziffer 1 hinzugefügt (z. B. aus „titel“ wird „titel1“). Falls der Name bereits auf eine Zahl endet, wird geprüft, welche Namensvarianten mit diesem Präfix bereits existieren, und die nächsthöhere freie Zahl wird verwendet. Beispiel: Gibt es bereits Variablen mit den Namen „x1“ bis „x9“, führt die Duplizierung einer dieser Variablen zur Erstellung von „x10“. Fehlt z. B. „x4“, wird stattdessen „x4“ erzeugt. Die neue Variable ist eindeutig und kann unabhängig von der Originalvariablen weiterverwendet oder bearbeitet werden. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Erstellen von Textbausteinen vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/text/button.addToCart/duplicate

Antwort

{
    "translations": {
        "DE": {
            "author": 1,
            "changedAt": "2025-02-17T11:46:54.000Z",
            "configReferences": 0,
            "id": "41",
            "languageId": "DE",
            "system": false,
            "text": "In den Warenkorb",
            "used": false
        },
        "EN": {
            "author": 1,
            "changedAt": "2025-02-17T11:46:54.000Z",
            "configReferences": 0,
            "id": "42",
            "languageId": "EN",
            "system": false,
            "text": "Add to cart",
            "used": false
        }
    },
    "variable": "button.addToCart1"
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Erstellen von Textbausteinen.
404 Not Found		Variable mit `variable`=`{id}` wurde nicht gefunden.
503 Service Unavailable	”internalError”	Das Duplizieren ist fehlgeschlagen.

PUT text/{id}

Mit dieser Methode können bestehende Textbausteine einer Variable aktualisiert oder die Variable selbst umbenannt werden. Es ist möglich, Übersetzungen für eine oder mehrere Sprachen zu ändern – nicht angegebene Sprachen bleiben unverändert. Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Schreiben von Textbausteinen vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/text/button.addToCart

Request Body

{
    "name": "button.addToCart",
    "data": [
        {
            "languageId": "EN",
            "text": "Buy now"
        }
    ]
}

Antwort

[
    {
        "author": 1,
        "changedAt": "2025-02-17T11:46:54.000Z",
        "configReferences": 0,
        "id": "39",
        "languageId": "DE",
        "system": false,
        "text": "In den Warenkorb",
        "used": false
    },
    {
        "author": 1,
        "changedAt": "2025-04-30T14:10:12.000Z",
        "configReferences": 0,
        "id": "40",
        "languageId": "EN",
        "system": false,
        "text": "Buy now",
        "used": false
    }
]

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Schreiben von Textbausteinen.
400 Bad Request		Request Body konnte nicht geladen werden.
400 Bad Request	”invalidValue”	`name` oder `data.languageId` ist ein leerer String, oder ein data-Element ist kein Objekt.
400 Bad Request	”invalidFormat”	`name`, `data.languageId` oder `data.text` sind keine Strings, oder `data` ist kein Array.
400 Bad Request	”invalidCharacters”	Der neue Variablenname enthält ungültige Zeichen.
400 Bad Request	”missing”	`name`, `data` oder `data.languageId` wurden nicht angegeben.
400 Bad Request	”unknownDataField”	Ein unbekanntes Feld wurde im Request Body oder in einem data-Element übergeben.
404 Not Found		Variable mit `variable`=`{id}` wurde nicht gefunden.
409 Conflict		Eine Variable mit dem neuen Namen existiert bereits.

DELETE text/{id}

Mit dieser Methode kann eine bestehende Textvariable vollständig gelöscht werden. Dies betrifft alle zugehörigen Übersetzungen in verschiedenen Sprachen.
Damit der Endpunkt verwendet werden kann, müssen die entsprechenden Berechtigungen zum Löschen von Textbausteinen vorhanden sein.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/text/button.addToCart

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 Textbausteinen.
404 Not Found		Variable mit `variable`=`{id}` wurde nicht gefunden.
409 Conflict	”systemText”	Systemtexte können nicht gelöscht werden.
409 Conflict	”textInUse”	Die Variable wird noch in einer Konfiguration verwendet und kann nicht gelöscht werden.

Methoden für Publizieren

Die folgenden Methoden ermöglichen es, Textbausteine im Shop-System zu publizieren. Dabei wird geprüft, ob ein Publiziervorgang läuft oder ein neuer gestartet werden kann. Um diese Funktionen zu verwenden, müssen entsprechende Berechtigungen zum Publizieren von Textbausteinen vorhanden sein.

GET text/publish

Mit dieser Methode kann geprüft werden, ob aktuell ein Publiziervorgang für Textbausteine läuft. Ist kein Vorgang aktiv, wird zusätzlich das Ergebnis der letzten Kompilierung als success zurückgegeben. Das Feld success ist nur vorhanden, wenn running den Wert false hat. Um den Status abzufragen, müssen entsprechende Berechtigungen zum Lesen von Textbausteinen vorhanden sein.

Beispiel

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

Antwort

{
    "running": false,
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Lesen von Textbausteinen.
503 Service Unavailable	”internalError”	Interner Fehler beim Abrufen des Kompilierungsstatus.

POST text/publish

Mit dieser Methode werden die Templates des Shops mit den zuletzt geänderten Textbausteinen neu kompiliert. Damit dieser Vorgang gestartet werden kann, müssen die erforderlichen Berechtigungen zum Publizieren von Textbausteinen vorhanden sein.

Beispiel

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

Antwort

{
    "success": true
}

Fehlercodes

Fehler	Typ	Grund
401 Unauthorized		Nicht autorisiert: Sie sind nicht angemeldet oder verfügen nicht über die erforderlichen Rechte zum Publizieren von Textbausteinen.
503 Service Unavailable		Das Kompilieren der Templates konnte nicht gestartet werden.

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 Textbausteins

​Beispiel

​Methoden für Textbausteine

​3.1 GET text

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET text/authors

​Beispiel

​Antwort

​Fehlercodes

​GET text/{id}

​Beispiel

​Antwort

​Fehlercodes

​POST text

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​POST text/{id}/duplicate

​Beispiel

​Antwort

​Fehlercodes

​PUT text/{id}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​DELETE text/{id}

​Beispiel

​Antwort

​Fehlercodes

​Methoden für Publizieren

​GET text/publish

​Beispiel

​Antwort

​Fehlercodes

​POST text/publish

​Beispiel

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder eines Textbausteins

Beispiel

Methoden für Textbausteine

3.1 GET text

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET text/authors

Beispiel

Antwort

Fehlercodes

GET text/{id}

Beispiel

Antwort

Fehlercodes

POST text

Beispiel

Request Body

Antwort

Fehlercodes

POST text/{id}/duplicate

Beispiel

Antwort

Fehlercodes

PUT text/{id}

Beispiel

Request Body

Antwort

Fehlercodes

DELETE text/{id}

Beispiel

Antwort

Fehlercodes

Methoden für Publizieren

GET text/publish

Beispiel

Antwort

Fehlercodes

POST text/publish

Beispiel

Antwort

Fehlercodes

Support