API-Referenz Template-Optionen

Der Endpunkt templates/options stellt eine Schnittstelle zur Verwaltung der Template-Optionen bereit. Über diese Schnittstelle lassen sich alle im Template definierten Optionen auflisten, ihre Einstellungen abrufen und bearbeiten sowie die gepflegten Werte einzelner Optionen lesen und speichern. Optionen werden im Template definiert und anschließend im Admin-Interface bzw. über diese API gepflegt. Die Definition selbst (Name, Typ und Einschränkungen) ist durch das Template fest vorgegeben und kann über die API nicht verändert werden. Wie Optionen im Template definiert und ausgelesen werden, ist im Dokument Optionen beschrieben.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl/Info	Endpunkte	GET	POST	PUT	DELETE
Template-Optionen	templates/options/

Datenfelder

Name	Typ	Bedeutung
name	String	Eindeutiger Name der Option, wie er im Template definiert wurde.
type	String	Typ der Option (`String`, `Int`, `Float`, `Bool` oder `Enum`). Bestimmt die Eingabemaske im Admin-Interface.
constraints	Objekt	Typabhängige Einschränkungen der Option, z. B. `values` bei Typ `Enum` oder `min`/`max` bei `Int` und `Float`.
attachTo	String	Konfigurationstyp, an den die Option gebunden ist (z. B. `payment.payment`). Ist das Feld leer, handelt es sich um eine globale Option.
displayOptions	Objekt \| null	Steuert über `location` die Anzeigeposition der Option in der Konfigurationsoberfläche. `null`, wenn keine Position festgelegt wurde.
label	String	Anzeigelabel der Option. Dient ausschließlich der Anzeige und kann bearbeitet werden.
description	String	Beschreibung der Option. Dient ausschließlich der Anzeige und kann bearbeitet werden.
subshopIds	Array von Strings	Liste der Subshops, in denen die Option definiert ist (z. B. `["deutsch"]`).

Methoden für Template-Optionen

Die folgenden Methoden ermöglichen es, die definierten Optionen aufzulisten, ihre Einstellungen zu lesen und zu bearbeiten sowie die gepflegten Werte einzelner Optionen abzurufen und zu speichern. Die Nutzung setzt entsprechende Lese- bzw. Schreibrechte für Template-Daten voraus.

GET templates/options

Mit dieser Methode wird eine Liste aller im Template definierten Optionen zurückgegeben. Jeder Eintrag enthält die Definition der jeweiligen Option (u. a. name, type, constraints und attachTo) sowie das bearbeitbare label und die description. Der Endpunkt funktioniert wie alle anderen suchbaren API-Endpunkte und unterstützt Filterung, Sortierung und Paginierung. Leseberechtigungen für Template-Daten sind erforderlich.

Beispiel

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

Antwort

{
    "endReached": true,
    "items": [
        {
            "attachTo": "",
            "constraints": {
                "values": [
                    "grid",
                    "list",
                    "slider"
                ]
            },
            "description": "",
            "displayOptions": null,
            "label": "",
            "name": "enumValue",
            "subshopIds": [
                "deutsch"
            ],
            "type": "Enum"
        },
        ...
    ],
    "nextPageToken": "MA",
    "totalCount": 5
}

Filterfelder

name, type, attachTo

Sortierfelder

name, type

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 Template-Daten.
400 Bad Request	”invalidValue”	`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 ”:”.

GET templates/options/{name}

Mit dieser Methode werden die Einstellungen einer einzelnen Option anhand ihres Namens zurückgegeben. Leseberechtigungen für Template-Daten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/templates/options/enumValue

Antwort

{
    "attachTo": "",
    "constraints": {
        "values": [...]
    },
    "description": "",
    "displayOptions": null,
    "label": "",
    "name": "enumValue",
    "subshopIds": [
        "deutsch"
    ],
    "type": "Enum"
}

Das Feld constraints.values ist nur bei Optionen vom Typ Enum enthalten.

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 Template-Daten.
404 Not Found		Die Option wurde nicht gefunden.

PUT templates/options/{name}

Mit dieser Methode werden die Einstellungen einer Option aktualisiert. Es können ausschließlich label und description geändert werden. Alle anderen Parameter sind durch die Definition im Template fest vorgegeben und lassen sich über die API nicht ändern. Schreibberechtigungen für Template-Daten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/templates/options/enumValue

Request Body

{
    "label": "",
    "description": ""
}

Antwort

{
    "attachTo": "",
    "constraints": {
        "values": [...]
    },
    "description": "",
    "displayOptions": null,
    "label": "",
    "name": "enumValue",
    "subshopIds": [
        "deutsch"
    ],
    "type": "Enum"
}

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 Template-Daten.
400 Bad Request		Request-Body konnte nicht als JSON geladen werden.
404 Not Found		Die Option wurde nicht gefunden.

GET templates/options/{name}/value/{nodeId}

Mit dieser Methode wird der gepflegte Wert einer Option zurückgegeben. Der Parameter {nodeId} wird nur benötigt, wenn bei der Definition der Option attachTo angegeben wurde. Bei globalen Optionen (ohne attachTo) entfällt er. Da der Wert pro Subshop gepflegt wird, sollte die URL den Parameter subshopId enthalten. Wird er nicht angegeben, wird der erste Subshop des Shops verwendet. Leseberechtigungen für Template-Daten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch

Antwort

{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": true
}

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 Template-Daten.
404 Not Found		Die Option oder der Wert wurde nicht gefunden.

PUT templates/options/{name}/value/{nodeId}

Mit dieser Methode wird der Wert einer Option gespeichert. Der Parameter {nodeId} wird nur benötigt, wenn bei der Definition der Option attachTo angegeben wurde. Bei globalen Optionen (ohne attachTo) entfällt er. Da der Wert pro Subshop gepflegt wird, sollte die URL den Parameter subshopId enthalten. Wird er nicht angegeben, wird der erste Subshop des Shops verwendet. Schreibberechtigungen für Template-Daten sind erforderlich.

Beispiel

https://www.<ihr-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch

Request Body

{
    "value": true
}

Antwort

{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": 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 Template-Daten.
400 Bad Request		Request-Body konnte nicht als JSON geladen werden.
404 Not Found		Die Option wurde nicht gefunden.

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.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Datenfelder

Methoden für Template-Optionen

GET templates/options

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET templates/options/{name}

Beispiel

Antwort

Fehlercodes

PUT templates/options/{name}

Beispiel

Request Body

Antwort

Fehlercodes

GET templates/options/{name}/value/{nodeId}

Beispiel

Antwort

Fehlercodes

PUT templates/options/{name}/value/{nodeId}

Beispiel

Request Body

Antwort

Fehlercodes

Support

​Unterstützte Methoden

​Datenfelder

​Methoden für Template-Optionen

​GET templates/options

​Beispiel

​Antwort

​Filterfelder

​Sortierfelder

​Fehlercodes

​GET templates/options/{name}

​Beispiel

​Antwort

​Fehlercodes

​PUT templates/options/{name}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​GET templates/options/{name}/value/{nodeId}

​Beispiel

​Antwort

​Fehlercodes

​PUT templates/options/{name}/value/{nodeId}

​Beispiel

​Request Body

​Antwort

​Fehlercodes

​Support

Unterstützte Methoden

Datenfelder

Methoden für Template-Optionen

GET templates/options

Beispiel

Antwort

Filterfelder

Sortierfelder

Fehlercodes

GET templates/options/{name}

Beispiel

Antwort

Fehlercodes

PUT templates/options/{name}

Beispiel

Request Body

Antwort

Fehlercodes

GET templates/options/{name}/value/{nodeId}

Beispiel

Antwort

Fehlercodes

PUT templates/options/{name}/value/{nodeId}

Beispiel

Request Body

Antwort

Fehlercodes

Support