> ## Documentation Index > Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt > Use this file to discover all available pages before exploring further. # API-Referenz Textbausteine > Sprachabhängige Textbausteine für Templates über die Admin Interface API abrufen, bearbeiten, löschen und Änderungen im Shop publizieren. 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 ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/authors ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/button.addToCart ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} [ { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "name": "button.addToCart", "data": [ { "languageId": "DE", "text": "In den Warenkorb" }, { "languageId": "EN", "text": "Add to cart" } ] } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} [ { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/button.addToCart/duplicate ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/button.addToCart ``` #### Request Body ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "name": "button.addToCart", "data": [ { "languageId": "EN", "text": "Buy now" } ] } ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} [ { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/button.addToCart ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/publish ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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 ```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} https://www..de/admin/api/v1/text/publish ``` #### Antwort ```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}} { "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](https://websale.atlassian.net/servicedesk/customer/portal/6) Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.