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.

Inhaltsverzeichnis

1 1. Unterstützte Methoden
2 2. Datenfelder eines Textbausteins
3 3. Methoden für Textbausteine
- 3.1 3.1 GET text
- 3.2 3.2 GET text/authors
- 3.3 3.3 GET text/{id}
- 3.4 3.4 POST text
- 3.5 3.5 POST text/{id}/duplicate
- 3.6 3.6 PUT text/{id}
- 3.7 3.7 DELETE text/{id}
4 4. Methoden für Publizieren
- 4.1 4.1 GET text/publish
- 4.2 4.2 POST text/publish
5 5. Support

1. Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	PUT	POST	DELETE

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

2. Datenfelder eines Textbausteins

Name	Typ	Bedeutung

Name	Typ	Bedeutung
variable	String	Name der Textvariablen, über die der Inhalt im Template angesprochen wird.
translations	Objekt	Array von Textbausteindaten
translations.id	Integer	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.systemtext	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).

Beispiel:

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

3. 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",
          "id": "42",
          "languageId": "DE",
          "system": true,
          "text": "In den Warenkorb",
          "used": true
        },
        "EN": {
          "author": 3,
          "changedAt": "2025-04-01T14:23:00Z",
          "id": "43",
          "languageId": "EN",
          "system": true,
          "text": "Add to cart",
          "used": true
        }
      },
      "variable": "button.addToCart"
    }
  ],
  "nextPageToken": "MTAw",
  "totalCount": 1
}

Filterfelder:

variable, text, author, systemtext, used, changedAt

Sortierfelder:

variable, text, languageId, author, systemtext, used, changedAt

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

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

3.3 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",
    "id": "39",
    "languageId": "DE",
    "system": false,
    "text": "In den Warenkorb",
    "used": true
  },
  {
    "author": 1,
    "changedAt": "2024-12-18T14:44:54.000Z",
    "id": "40",
    "languageId": "EN",
    "system": false,
    "text": "Add to cart",
    "used": 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 Textbausteinen.

3.4 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. Alle anderen Parameter werden ignoriert. 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:

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

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 Textbausteinen.
400 Bad Request		Request body konnte nicht geladen werden oder die Variable nicht erzeugt werden.
400 Bad Request	"invalidValue"	Die Parameter `name`, `data.languageId` oder `data.text` sind keine Strings.
400 Bad Request	“invalidCharacters”	Der Variablenname enthält ungültige Zeichen.
400 Bad Request	“missing”	`name`, `data.languageId` oder `data.text` wurden nicht angegeben.
409 Conflict		Eine Variable mit dem selben Namen existiert bereits.

3.5 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:

{
    "variable": "button.addToCart1"
}

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 Textbausteinen.
404 Not Found		Variable mit `variable`=`{id}` wurde nicht gefunden.
503 Service Unavailable	"internalError"	Das Duplizieren ist fehlgeschlagen.

3.6 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:

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

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 Textbausteinen.
400 Bad Request	"invalidValue"	Der Parameter `name`, `data.languageId` oder `data.text` sind keine Strings.
400 Bad Request	“invalidCharacters”	Der neue Variablenname enthält ungültige Zeichen.
404 Not Found		Variable mit `variable`=`{id}` wurde nicht gefunden.

3.7 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

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.

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

4.1 GET text/publish

Mit dieser Methode kann geprüft werden, ob aktuell ein Publiziervorgang für Textbausteine läuft.

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

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

4.2 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

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.

5. 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 Textbausteine

Inhaltsverzeichnis

1. Unterstützte Methoden

2. Datenfelder eines Textbausteins

Beispiel:

3. Methoden für Textbausteine

3.1 GET text

Beispiel:

Antwort:

Filterfelder:

Sortierfelder:

Fehlercodes:

3.2 GET text/authors

Beispiel:

Antwort:

Fehlercodes:

3.3 GET text/{id}

Beispiel:

Antwort:

Fehlercodes:

3.4 POST text

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.5 POST text/{id}/duplicate

Beispiel:

Antwort:

Fehlercodes:

3.6 PUT text/{id}

Beispiel:

Request Body:

Antwort:

Fehlercodes:

3.7 DELETE text/{id}

Beispiel:

Antwort:

Fehlercodes:

4. Methoden für Publizieren

4.1 GET text/publish

Beispiel:

Antwort:

Fehlercodes:

4.2 POST text/publish

Beispiel:

Antwort:

Fehlercodes:

5. Support