Bedienung für Shop-Betreiber

Diese Anleitung richtet sich an Shop-Betreiber und Mitarbeitende im OXID-Admin. Sie setzt keinen Server- oder Programmierzugriff voraus.

Schnellstart

1. Lassen Sie Ihre Agentur das Modul installieren und konfigurieren.

2. Öffnen Sie Erweiterungen ‣ Module ‣ ContentApi ‣ Einstell. und prüfen Sie die Einstellungen in den Bereichen Zugang und Sicherheit, Schreibzugriff und Bild-Uploads.

3. Stellen Sie sicher, dass nur vertrauenswürdige OXID-Administratoren in der Erlaubte API-Administratoren-Liste stehen (oder die Liste leer bleibt und alle Mall-Admins Zugriff haben).

4. Notieren Sie Ihre Admin-E-Mail und Ihr Admin-Passwort.

5. Öffnen Sie die OpenAI Codex Desktop-App (innerhalb der ChatGPT Desktop-App) oder OpenAI Codex CLI.

6. Fügen Sie den unten stehenden Verbindungs-Prompt ein, ersetzen Sie die Platzhalter und senden Sie ihn ab.

Tipp

Sie können der KI konkrete Artikelnummern, Kategorien, Attribute oder Hersteller nennen. Sie können sie aber auch auffordern, passende Einträge selbst anhand von Titel, Ident oder Kategorie-Bäumen im Shop zu ermitteln.

Tipp

Die ContentApi trennt Lese- und Schreibzugriff: Suchen und Lesen sind grundsätzlich möglich; Schreiben lässt sich je Bereich in den Moduleinstellungen gezielt freigeben oder sperren. Lesen Sie Änderungen vor dem finalen Speichern immer in der KI-Antwort oder einem Vorschau-Schritt.

Verbindung mit dem KI-Client herstellen

Öffnen Sie in der OpenAI Codex Desktop-App oder OpenAI Codex CLI ein neues Gespräch und fügen Sie folgenden Prompt ein. Ersetzen Sie <IHRE-SHOP-URL>, <IHRE-ADMIN-E-MAIL> und <IHRES-PASSWORT> durch Ihre echten Werte, bevor Sie ihn senden:

Verbinde dich mit meiner OXID-ContentApi:

Login-URL: https://<IHRE-SHOP-URL>/content-api/auth/token
Benutzer: <IHRE-ADMIN-E-MAIL>
Passwort: <IHRES-PASSWORT>

Melde dich an und folge danach automatisch den Anweisungen der Schnittstelle.

Beispiel mit fiktiven Werten:

Verbinde dich mit meiner OXID-ContentApi:

Login-URL: https://mein-shop.de/content-api/auth/token
Benutzer: admin@mein-shop.de
Passwort: meinSicheresPasswort123!

Melde dich an und folge danach automatischen Anweisungen der Schnittstelle.

Bemerkung

Der Prompt funktioniert mit KI-Clients, die HTTPS-API-Aufrufe ausführen können, wie die OpenAI Codex Desktop-App (innerhalb der ChatGPT Desktop-App) oder die OpenAI Codex CLI. Jeder andere Terminal-Client, der curl ausführen kann, ist ebenfalls möglich, erfordert dann aber manuelles Lesen der API-Hilfe und des Schemas.

Wenn die Anmeldung erfolgreich ist, antwortet die API mit einem Bearer-Token und empfiehlt, als nächstes die Hilfeseite und das OpenAPI-Schema zu lesen. Der KI-Client kann dann automatisch verstehen, welche Endpunkte, Felder und Datenformate verfügbar sind.

Alle Moduleinstellungen

Die Einstellungen sind im OXID-Admin in drei Bereichen gruppiert.

Zugang und Sicherheit

Einstellung	Standard	Wirkung
JWT Secret (min. 32 Zeichen)	leer	Geheimer Schlüssel für die Signierung der Tokens. Muss vor dem ersten Login gesetzt sein. Empfohlen: 64 zufällige Zeichen.
Token-Gültigkeit in Sekunden	3600	Wie lange ein Token gültig bleibt, bevor erneut ein Login nötig ist (Sekunden). 3600 entspricht einer Stunde.
HTTPS für die ContentApi erzwingen	Ein	Aufrufe über HTTP werden abgelehnt. Nur für eine abgeschottete lokale Entwicklungsumgebung ohne TLS ausschalten.
IP-Whitelist (eine IP pro Zeile)	leer	Wenn befüllt, dürfen nur die eingetragenen IP-Adressen die API nutzen. Leer lassen erlaubt alle IPs.
Vertrauenswürdige Reverse Proxies (eine IP pro Zeile)	leer	Nur von diesen Proxy-IPs werden X-Forwarded-Proto und X-Forwarded-For ausgewertet. Bei direktem HTTPS leer lassen.
Erlaubte API-Administratoren (eine Login-E-Mail pro Zeile)	leer	Wenn befüllt, erhalten nur diese OXID-Administratoren ein Token. Leer erlaubt es allen aktiven OXID-Mall-Admins.
Maximale fehlgeschlagene Loginversuche	5	Anzahl erlaubter Fehlversuche pro IP innerhalb des Sperrzeitraums.
Login-Sperrzeitraum in Sekunden	900	Zeitfenster für die Login-Begrenzung. 900 entspricht 15 Minuten.

Schreibzugriff

Jede Checkbox steuert nur das Schreiben (Anlegen, Ändern, Zuordnen). Suchen und Lesen bleiben verfügbar, auch wenn eine Checkbox deaktiviert ist – zum Beispiel können Artikel gelesen werden, während nur die Langbeschreibung bearbeitbar ist.

Einstellung	Standard	Wirkung
Artikel bearbeiten (ohne Langbeschreibung)	Ein	POST/PATCH für Stammdaten, Relationen, Varianten, Preise usw. Langbeschreibungen werden separat gesteuert.
Artikel-Langbeschreibungen bearbeiten	Ein	PATCH mit long_description und Schutzwert. Artikel bleiben lesbar, auch wenn diese Option deaktiviert ist.
Kategorien bearbeiten	Ein	Kategorien anlegen und ändern sowie Artikel zuordnen oder entkoppeln.
CMS-Inhalte bearbeiten	Ein	CMS-Seiten anlegen und ändern.
Nachrichtenbeiträge bearbeiten	Aus	Anlegen und Ändern von EcsDesk-Nachrichtenbeiträgen sowie Artikel-Widgets. Beiträge bleiben lesbar, wenn die Option aus ist. Erfordert EcsDesk mit Nachrichten-Plugin.
Webshop-Cache leeren	Aus	Erlaubt POST /maintenance/shop-cache/clear.
Freigegebene Artikel-Zusatzfelder (eines pro Zeile)	leer	Format api_name=datenbankspalte:typ:zugriff, zum Beispiel material_code=ecs_materialcode:string:read. Erlaubte Typen: string, int, float, bool. Zugriff: read oder write. Ohne Zugriff ist das Feld nur lesbar.

Bild-Uploads

Einstellung	Standard	Wirkung
Bild-Uploads über die ContentApi erlauben	Aus	Ermöglicht streng geprüfte Multipart-Uploads von JPEG-, PNG- und WebP-Bildern für die unten freigegebenen Ziele.
Freigegebene Bildziele (eines pro Zeile)	article_master, category_master, content_media, blog_media	Erlaubte Werte: article_master, category_master, content_media und blog_media. blog_media benötigt freigegebenen Schreibzugriff auf Nachrichtenbeiträge. Nur hier freigegebene Ziele sind über die API erreichbar.
Maximale Größe je Bild in Bytes	2097152	Maximale Dateigröße je Upload in Bytes. Standard ist 2 MiB. Das wirksame Limit wird außerdem durch upload_max_filesize und post_max_size des Servers begrenzt.

Achtung

JWT Secret, Erlaubte API-Administratoren und IP-Whitelist sind die wichtigsten Sicherheitseinstellungen. Für den produktiven Betrieb sollten alle drei bewusst eingesetzt und das JWT Secret niemals an Dritte weitergegeben werden.

Ablauf aus Sicht des Shop-Betreibers

1. Sie formulieren eine Aufgabe in natürlicher Sprache an den KI-Client.

2. Der KI-Client meldet sich an der ContentApi an.

3. Er liest die API-Hilfe und das OpenAPI-Schema.

4. Bei Bedarf sucht er im Shop nach passenden Artikeln, Kategorien, Attributen, Herstellern, CMS-Seiten oder Nachrichtenbeiträgen. Dabei kann er anhand von Titel, Ident, Artikelnummer, EAN, OXID oder Nachrichten-Slug suchen.

5. Für Änderungen an Langbeschreibungen oder CMS-Inhalten liest er die aktuellen Inhalte und deren Schutzwerte vollständig aus.

6. Er zeigt Ihnen geplante Änderungen an oder fragt bei Unsicherheiten nach.

7. Nach Ihrer Freigabe speichert er die Änderung.

8. Bilder werden nur hochgeladen, wenn das Bilder-Upload-Feature im Modul freigegeben und das gewünschte Ziel aktiviert ist.

9. Der Datensatz steht sofort in der OXID-Datenbank und ist im Admin sichtbar.

Tipp

Lassen Sie den KI-Client vor jedem Schreibzugriff die geplanten Werte anzeigen. Sobald die API speichert, wird der Datensatz in der Datenbank geändert.

Artikel

Über die ContentApi können Artikel angelegt, über Titel, Artikelnummer, EAN oder OXID gesucht, gelesen und geändert werden. Möglich sind Texte, Preise, SEO-Metadaten, Kategorie- und Attributzuordnungen, Zubehör, Cross-Selling, die Hauptkategorie des Artikels sowie mehrsprachige Übersetzungen. Auch Vaterartikel und deren Varianten können angelegt und gepflegt werden.

1. Neuen Artikel anlegen

Lege einen neuen Artikel "Premium Edelstahl-Trinkflasche 1 Liter" mit
Artikelnummer 21000 an. Der Preis soll 29,90 EUR betragen, der
Listenpreis 39,90 EUR, die EAN 4260000000000 und die MPN EF-1000.
Recherchiere im Web eine passende, SEO-optimierte Langbeschreibung.
Ergänze passende Suchbegriffe, SEO-Keywords und SEO-Description.
Suche im Shop die passende Kategorie und füge die sinnvollen Attribute
(z. B. Material, Volumen) mit passenden Werten hinzu. Aktiviere den
Artikel.

2. Artikel per Titel suchen und ändern

Suche im Shop nach dem Artikel mit dem Titel "Edelstahl-Trinkflasche"
oder einem ähnlichen Begriff. Wähle den passenden Treffer aus, lies
ihn auf Deutsch und optimiere die Langbeschreibung für SEO. Nutze die
Keywords "Edelstahlflasche", "Trinkflasche", "1 Liter", "BPA-frei" und
"nachhaltig". Zeige mir vor dem Speichern die Änderungen.

3. Artikel übersetzen

Lade den Artikel 21000 auf Deutsch und übersetze Titel,
Kurzbeschreibung und Langbeschreibung ins Englische. Speichere die
englischen Texte unter der Sprache ``en`` zurück.

4. Artikel mit Varianten erstellen

Ein Artikel mit Varianten besteht aus einem Vaterartikel und mindestens einer Variante. Der Vaterartikel erhält Titel, Artikelnummer und die Bezeichnung der Auswahl, zum Beispiel Farbe oder Größe. Jede Variante ist ein eigener Artikel mit eindeutiger Artikelnummer und einem Auswahlwert, zum Beispiel Rot oder Grün.

Preis, Bestand, Aktivstatus und Reihenfolge können für jede Variante getrennt gesetzt werden. Einen eigenen Titel benötigt eine Variante nicht; sie verwendet in diesem Fall den Titel des Vaterartikels. Kategorien und die Hauptkategorie pflegen Sie am Vaterartikel.

Erstelle einen Artikel "T-Shirt Classic" mit der Variantenbezeichnung
"Farbe". Lege anschließend die Varianten "Rot" und "Grün" mit jeweils
eigener Artikelnummer an. Beide Varianten sollen aktiv sein, 19,90 EUR
kosten und einen Bestand von 25 Stück haben. Prüfe danach, ob beide
Varianten beim T-Shirt vorhanden sind.

Suche den Artikel "T-Shirt Classic" und lies ihn vollständig. Falls er
noch keine Variantenbezeichnung hat, setze sie auf "Farbe". Füge dann die
Varianten A und B als "Rot" und "Grün" mit eindeutigen Artikelnummern
hinzu. Zeige mir vor dem Speichern alle vorgesehenen Werte und prüfe danach
die Variantenliste.

Für Kombinationen mehrerer Auswahlarten verwenden Sie dieselbe Reihenfolge bei Bezeichnung und Auswahl, etwa Farbe | Größe am Vaterartikel und Rot | XL an einer Variante.

Bemerkung

Eine Variantenauswahl darf bei demselben Vaterartikel nur einmal vorkommen. Eine Variante kann nicht selbst wieder Vaterartikel weiterer Varianten sein. Die Zuordnung zum Vaterartikel lässt sich nach dem Anlegen nicht mehr ändern.

5. Kategorie- und Attributzuordnung manuell setzen

Ordne dem Artikel 21000 die Kategorie "Trinkflaschen" und zusätzlich
die Kategorie "Outdoor" zu. Entferne die alte Kategorie "Testkategorie".
Setze das Attribut Material=Edelstahl und Volumen=1 Liter. Achte
darauf, dass nur die genannten Kategorien und Attribute am Artikel
verbleiben.

6. Hauptkategorie eines Artikels festlegen

Jeder Artikel kann genau eine seiner bereits zugeordneten Kategorien als Hauptkategorie verwenden. Der KI-Client liest dafür zuerst den Artikel und ermittelt die gewünschte Kategorie eindeutig über ihre OXID. Ist sie dem Artikel noch nicht zugeordnet, lässt er sie zunächst ergänzend hinzufügen; die übrigen Kategoriezuordnungen bleiben dabei erhalten. Anschließend setzt er die Hauptkategorie und liest den Artikel zur Kontrolle erneut.

Suche den Artikel 21000 und die Kategorie "Outdoor" eindeutig. Prüfe
zuerst, ob die Kategorie dem Artikel bereits zugeordnet ist. Falls
nicht, füge sie ergänzend hinzu, ohne andere Kategoriezuordnungen zu
entfernen. Setze "Outdoor" danach als Hauptkategorie des Artikels und
lies den Artikel erneut, um das Ergebnis zu kontrollieren.

Achtung

Die Hauptkategorie kann nur auf eine Kategorie gesetzt werden, die dem Artikel bereits zugeordnet ist. Senden Sie beim Ergänzen nicht unbedacht eine neue vollständige categories-Liste: Dieses Feld ersetzt alle bisherigen Kategoriezuordnungen. Das ergänzende Hinzufügen über die Kategorie erhält dagegen die bestehenden Zuordnungen.

Bemerkung

Varianten übernehmen die Hauptkategorie vom Vaterartikel. Eine Hauptkategorie kann deshalb nicht direkt an einer Variante gesetzt werden. Lassen Sie den KI-Client den Vaterartikel ermitteln und die Änderung dort ausführen. Beim Lesen einer Variante zeigt die API an, dass die Hauptkategorie geerbt ist, und nennt die OXID des Vaterartikels.

7. Kategorie- und Attributzuordnung automatisch ermitteln

Analysiere den Artikel 21000 und suche im Shop die passendsten
Kategorien und Attribute. Wenn passende Einträge existieren, ordne sie
dem Artikel automatisch zu. Zeige mir vor dem Speichern, welche
Kategorien und Attribute du gewählt hast.

8. Zubehör und Cross-Selling automatisch zuweisen

Ermittle für Artikel 21000 passende Cross-Selling-Artikel und
Zubehör aus dem Shop und weise sie automatisch zu. Wähle dafür
thematisch passende Artikel, wenn möglich aus derselben oder
verwandten Kategorie. Zeige mir vor dem Speichern, welche Artikel du
gefunden hast.

9. SEO-Metadaten pflegen

Für den Artikel 21000 setze SEO-Keywords auf
"Edelstahlflasche, Trinkflasche, 1 Liter, BPA-frei" und die
SEO-Description auf: "Premium Edelstahl-Trinkflasche ...".

10. Langbeschreibung mit Web-Recherche ergänzen

Suche den Artikel 21000, lies seine aktuellen Daten und ergänze die
Langbeschreibung um technische Daten, die du im Web findest
(z. B. Materialstärke, Gewicht, Maße, Verschluss). Strukturiere die
Beschreibung mit einer Produkteinleitung, einer Aufzählung der
technischen Daten und einem Kurz-Hinweis zur Pflege. Zeige mir die
Änderung vor dem Speichern.

11. Langbeschreibung ändern (Revisionsschutz)

Lies den Artikel 21000 auf Deutsch. Nimm die vorhandene
Langbeschreibung unverändert mit und ergänze am Ende einen
Pflegehinweis. Speichere die vollständige Langbeschreibung mit dem
passenden Schutzwert aus dem vorherigen Lesen. Bei mehrsprachigen
Sprachblöcken achte auf den passenden Sprach-Schutzwert.

Bemerkung

Langbeschreibungen, Kategorie-Langbeschreibungen und CMS-Inhalte können nur geändert werden, wenn der Client den aktuellen Inhalt soeben gelesen hat. Ein dabei ausgehändigter Schutzwert verhindert, dass parallele Änderungen überschrieben werden. Bei Konflikten muss der Client den Datensatz neu laden.

Kategorien

Über die ContentApi lassen sich Kategorien anlegen, lesen und ändern. Gelöscht werden können sie weiterhin nicht.

Beim Anlegen ist ein Titel in der mit ?lang= gewählten Standardsprache verpflichtend. Ohne ausdrücklich gesendetes active wird die neue Kategorie zunächst inaktiv angelegt; ohne hidden ist sie sichtbar.

Eine Kategorie kann folgendermaßen positioniert werden:

• Mit parent_id als Kategorie auf oberster Ebene (oxrootid) oder als Unterkategorie einer bestehenden Kategorie.

• Mit position_after_id direkt hinter einer Geschwisterkategorie. Die Elternkategorie wird dabei automatisch von der Referenz übernommen. sort und position_after_id dürfen nicht gemeinsam gesendet werden.

• Ohne beides wird die Kategorie am Ende der Geschwisterkategorien der Elternkategorie eingereiht.

Unter derselben Elternkategorie wird ein bereits vorhandener identischer Titel abgewiesen, damit wiederholte Aufrufe keine Dubletten erzeugen. Kategoriebaumänderungen werden pro Shop serialisiert und in einer Transaktion ausgeführt.

Artikel lassen sich einer Kategorie ergänzend hinzufügen, ohne dass bestehende Kategoriezuordnungen dieser Artikel verloren gehen.

Artikel können aus einer Kategorie entkoppelt werden, ohne dass die Artikel oder ihre sonstigen Kategoriezuordnungen gelöscht werden. Beim Artikel-Ändern ersetzt das Feld categories weiterhin die vollständige Kategorienliste des Artikels.

Änderbar sind pro Kategorie unter anderem:

• Titel, Kurzbeschreibung und Langbeschreibung sprachabhängig,

• Aktiv / Versteckt,

• Sortierungswert im Kategorie-Baum,

• Elternkategorie (Kategorien auf oberster Ebene verwenden oxrootid),

• Externer Link,

• SEO-Keywords und SEO-Description je Sprache.

Bemerkung

Wie bei Artikeln und CMS-Seiten wird die Kategorie-Langbeschreibung als Raw-HTML gespeichert. Die ContentApi führt keine automatische HTML-Reinigung durch. Änderungen an der Langbeschreibung benötigen den Schutzwert aus dem vorherigen Lesen.

1. Neue Kategorie anlegen

Lege eine neue Unterkategorie "Edelstahl-Geländer" unter der
Kategorie "Geländer" an. Positioniere sie direkt hinter der
Kategorie "Stahl-Geländer". Aktiviere sie für Deutsch, ergänze eine
Kurz- und Langbeschreibung mit HTML sowie passende SEO-Keywords und
SEO-Description. Zeige mir vor dem Speichern, was du anlegen möchtest.

2. Kategoriebeschreibung und SEO anpassen

Suche im Shop die Kategorie "Outdoor" und lies ihre aktuellen Daten.
Aktualisiere für Deutsch und Englisch die Kurzbeschreibung und
Langbeschreibung. Ergänze passende SEO-Keywords und SEO-Description
für beide Sprachen. Setze die Sortierung auf einen sinnvollen Wert,
damit die Kategorie an der richtigen Stelle erscheint. Zeige mir vor
dem Speichern, was du ändern möchtest.

3. Kategorie-Sortierung und Elternkategorie anpassen

Suche die Kategorie "Outdoor-Zubehör" und verschiebe sie auf die
oberste Ebene. Stelle die Sortierung so ein, dass sie direkt nach der
Kategorie "Outdoor" erscheint. Trage einen externen Link
``https://example.org/outdoor-zubehoer`` ein. Zeige mir vor dem
Speichern die geplanten Werte.

4. Artikel einer Kategorie hinzufügen

Suche die Kategorie "Outdoor" und füge ihr die Artikel mit den
Nummern 1001, 1002 und 1003 hinzu. Achte darauf, dass die Artikel
ihre bisherigen Kategorien behalten und keine bestehende Zuordnung
überschrieben wird. Zeige mir vor dem Speichern, welche Artikel
zugeordnet werden.

5. Artikel aus einer Kategorie entkoppeln

Suche die Kategorie "Outdoor" und entferne die Artikel mit den
Nummern 1001 und 1002 aus dieser Kategorie. Die Artikel selbst und
ihre anderen Kategoriezuordnungen sollen erhalten bleiben. Zeige mir
vor dem Speichern, welche Artikel tatsächlich entkoppelt werden.

CMS-Seiten

CMS-Seiten können neu angelegt, über Titel oder Ident gesucht und mehrsprachig gepflegt werden. Änderbar sind Titel, HTML-Inhalt, Ordner, Aktiv-Status und SEO-Metadaten.

Bemerkung

Beim Ändern des CMS-Inhalts ist der Schutzwert aus dem vorherigen Lesen erforderlich. Bei mehrsprachigen Blöcken wird der passende Sprach-Schutzwert verwendet, zum Beispiel für Deutsch. Der Client muss den vorhandenen Inhalt vollständig übernehmen und gezielt ergänzen.

1. CMS-Landingpage erstellen

Erstelle eine neue CMS-Seite mit dem Ident "summer-sale-2026" und dem
Titel "Sommer-Sale 2026". Schreibe einen HTML-Inhalt mit
Hauptüberschrift, Einleitungstext, drei Vorteilen und einem
Banner-Platzhalter. Aktiviere die Seite, setze den Ordner "Content"
und ergänze SEO-Keywords sowie SEO-Description.

2. CMS-Seite per Titel/Ident suchen und übersetzen

Suche die CMS-Seite mit dem Titel oder Ident "impressum" beziehungsweise
"oximpressum" und übersetze Titel und HTML-Inhalt ins Englische.
Speichere die Übersetzung unter der Sprache ``en``.

3. CMS-Seite aktualisieren und SEO pflegen

Suche die CMS-Seite mit dem Ident "summer-sale-2026" und aktualisiere
den HTML-Inhalt mit neuen Texten und einem aktuellen
Banner-Platzhalter. Passe SEO-Keywords und SEO-Description an. Zeige
mir vor dem Speichern die Änderungen.

Bilder-Upload

Bilder können über die ContentApi hochgeladen werden, wenn die beiden Einstellungen :guilabel:`Bild-Uploads über die ContentApi erlauben` und die gewünschten :guilabel:`Freigegebenen Bildziele` aktiv sind. Ohne Freigabe lehnt die API jeden Upload ab.

Achtung

Bilder werden ausschließlich über die dafür vorgesehenen Upload- Funktionen akzeptiert. Lokale Pfade, Base64-Daten oder externe Download-URLs werden abgelehnt.

Gültige Dateien und Limits

• Erlaubte Formate: JPEG, PNG und WebP.

• Maximale Dateigröße: Wert aus Maximale Größe je Bild in Bytes (Standard 2 MiB), begrenzt durch die PHP-Serverlimits.

• Maximale Abmessungen: 24 Megapixel insgesamt, längste Seite 8000 Pixel.

• Animierte Bilder (animierte PNG oder WebP) werden abgelehnt.

• Pro Vorgang wird genau eine Datei hochgeladen.

• Rate-Limit: Pro Administrator und IP gilt ein gleitendes 10-Minuten-Fenster mit maximal 30 Dateien oder 50 MiB.

Der Server normalisiert Bilder neu, wendet bei JPEG die EXIF- Ausrichtung an und speichert PNG/WebP mit Transparenz.

Master-Bilder für Artikel und Kategorien

Artikel-Masterbilder

• Sie können die aktuellen Artikelbilder auslesen und freie oder belegte Bild-Slots inklusive des aktuellen Schutzwerts sehen.

• Ein Masterbild lässt sich in den gewünschten Slot hochladen.

• Ein bereits belegter Slot kann nur ersetzt werden, wenn zuvor das aktuelle Bild gelesen und der passende Schutzwert mitgegeben wurde.

• Bilder von geerbten Artikeln können nicht direkt ersetzt werden.

Kategorie-Masterbilder

• Sie können die drei Kategoriebild-Typen thumb, icon und promo_icon auslesen.

• Für jeden Typ lässt sich ein Bild hochladen.

• Zum Ersetzen muss zuvor das aktuelle Bild gelesen und der passende Schutzwert mitgegeben werden.

• Bilder von geerbten Kategorien können nicht direkt ersetzt werden.

Inhaltsbilder für Artikel, Kategorien, CMS und Blog

Inhaltsbilder sind redaktionelle Bilder, die später in HTML-Inhalte (ein <img>-Snippet) eingesetzt werden. Sie können für Artikel, Kategorien, CMS-Seiten und Nachrichtenbeiträge hochgeladen werden. Das blog_media-Ziel ist nur verfügbar, wenn Nachrichtenbeiträge bearbeiten und Bild-Uploads über die ContentApi erlauben freigegeben sind.

Optional können Sie ein alt-Feld für den Alternativtext mitgeben. Die API liefert eine öffentliche URL und ein einsatzbereites HTML- Snippet, das der Client in long_description, content, den Nachrichten-Body oder featured_image einbettet.

Tipp

Die aktuellen Bild-Upload-Regeln (Ziele, maximale Größe, erlaubte Formate und weitere Regeln) können Sie über die API-Hilfe abfragen.

1. Masterbild für einen Artikel hochladen

Lies die aktuellen Artikelbilder für Artikel 21000. Lade das lokale
Bild "flasche_front.jpg" in den ersten freien Slot hoch. Falls der
Slot belegt ist, ersetze das bestehende Bild mit der aktuellen
Revision. Zeige mir vor dem Speichern, welche URL und welchen Dateinamen
die API zurückgibt.

2. Inhaltsbild in eine CMS-Seite einbetten

Lies die CMS-Seite "summer-sale-2026" und den aktuellen Inhalt samt
Schutzwert. Lade das lokale Bild "sommer-sale-banner.jpg" als
Inhaltsbild hoch. Füge das zurückgegebene HTML-Snippet an passender
Stelle in den bestehenden CMS-Inhalt ein und speichere den gesamten
Inhalt mit dem passenden Schutzwert zurück.

Nachrichtenbeiträge (Blog)

Die Nachrichten-Funktion setzt EcsDesk mit dem Nachrichten-Plugin voraus. Im Modul steuert Nachrichtenbeiträge bearbeiten den Schreibzugriff (Anlegen, Ändern, Artikel-Widgets). Beiträge können gelesen und durchsucht werden, auch wenn diese Checkbox deaktiviert ist.

Bemerkung

Nachrichtenbeiträge werden als Dateien im EcsDesk-Datenverzeichnis verwaltet. Beiträge lassen sich anlegen, lesen, suchen und ändern – nicht löschen.

Verfügbare Aktionen

• Suchen und Filtern von Beiträgen nach Suchbegriff, Status, Kategorie, Tag und Veröffentlichungszeitraum.

• Lesen einzelner Beiträge inklusive aller Metadaten und Inhalte.

• Anlegen neuer Beiträge.

• Ändern vorhandener Beiträge – dabei ist der Schutzwert aus dem vorherigen Lesen erforderlich.

• Kategorien und Tags können gelesen und beim Speichern verwendet werden.

Wichtige Regeln für Beiträge

• Status: draft (Entwurf), published (veröffentlicht), newsletter_only (nur Newsletter) oder archived (archiviert). Nur published erscheint im Webshop.

• Datum: Im Format YYYY-MM-DD. Ohne Angabe wird das aktuelle Datum verwendet.

• Slug: Wird aus dem Titel automatisch generiert, wenn keiner gesendet wird, und muss eindeutig sein.

• Kategorien: Müssen im EcsDesk-Nachrichten-Plugin bereits existieren. Beim Speichern wird die Liste komplett ersetzt.

• Tags: Freie Texte. Beim Speichern wird die Liste komplett ersetzt.

• Beitragsbild: Kann eine interne URL, ein relativer Pfad oder ein externes Bild sein. Pfad-Traversal und unsichere Protokolle werden abgelehnt.

• Artikel-Widgets: Aus einem aktiven, sichtbaren Artikel kann ein HTML-Widget erzeugt werden. Der Link enthält keine Session-Parameter. Mögliche Ausrichtungen: none, left, right; Breite 240–1200 Pixel (Standard 500), Höhe 0–1200 Pixel (Standard 0).

Newsletter-Platzhalter (EcsDesk)

Beiträge für den Newsletter (typisch Status newsletter_only) oder andere Newsletter-Inhalte im EcsDesk-Nachrichtenplugin verwenden keine Smarty- oder OXID-Shop-Template-Variablen wie {$...} oder [{ oxif ... }]. Diese werden beim Versand durch EcsDesk nicht ersetzt.

Erlaubt sind ausschließlich diese Platzhalter im HTML-Body:

• {{vorname}} – Vorname des Empfängers

• {{nachname}} – Nachname des Empfängers

• {{abmelden_link}} – personalisierter One-Click-Abmeldelink (URL)

Beispiel Anrede: Hallo {{vorname}} {{nachname}},

Beispiel Abmeldelink: <a href="{{abmelden_link}}">Newsletter abbestellen</a>

Diese Regel gilt nur für das EcsDesk-Nachrichtenplugin, nicht für Shop-CMS-Seiten oder Artikel-Langbeschreibungen.

1. Nachrichtenbeitrag mit Artikel-Widget anlegen

Erstelle einen Nachrichtenbeitrag mit dem Titel "Nachhaltig trinken"
und dem Status "draft". Suche den passenden Artikel für das Widget,
zum Beispiel "Premium Edelstahl-Trinkflasche", und erzeuge ein Widget
mit width=600. Lies die verfügbaren Nachrichten-Kategorien und weise
den Beitrag der Kategorie "Aktuelles" zu. Setze sinnvolle Tags, einen
Kurztext und SEO-Daten. Füge das Widget-HTML in den Beitrags-Body ein
und speichere den Entwurf.

2. Vorhandenen Nachrichtenbeitrag ändern

Suche den Beitrag "Nachhaltig trinken", lies ihn vollständig ein und
ändere den Status auf "published". Zeige mir vor dem Speichern, welche
Felder geändert werden.

Webshop-Cache leeren

Die ContentApi kann den Cache im konfigurierten Temp-Verzeichnis des OXID-Shops kontrolliert leeren, wenn im Modul Webshop-Cache leeren aktiviert ist. Dabei werden unter anderem kompilierte Templates sowie Sprach-, Inhalts-, Konfigurations- und SEO-Cachedateien entfernt. OXID erzeugt benötigte Cachedateien anschließend automatisch neu; der erste Seitenaufruf kann deshalb vorübergehend etwas länger dauern.

Die Aktion ist beispielsweise sinnvoll, wenn Änderungen an Templates, Übersetzungen oder der Shop-Konfiguration noch nicht sichtbar sind. Sie benötigt eine gültige Anmeldung an der ContentApi, aber keine weiteren Angaben.

Leere jetzt den Webshop-Cache über die ContentApi. Nenne mir danach die
Anzahl der gelöschten Dateien und Verzeichnisse sowie die Anzahl der
Fehler.

Die Rückmeldung unterscheidet zwischen gelöschten Dateien, gelöschten Verzeichnissen und Fehlern. Nur bei 0 Fehlern wurde jeder zum Löschen vorgesehene Eintrag erfolgreich entfernt.

Bemerkung

Betriebsnotwendige und geschützte Daten werden beim Leeren des Caches nicht entfernt.

Achtung

Vor dem Leeren prüft die ContentApi das konfigurierte Cacheverzeichnis. Ist es falsch konfiguriert oder nicht lesbar, muss die Agentur die Shop-Konfiguration beziehungsweise die Dateirechte prüfen.

Täglicher Arbeitsablauf

1. Öffnen Sie den KI-Client und den Verbindungs-Prompt.

2. Stellen Sie sicher, dass Sie mit dem richtigen Admin-Account arbeiten.

3. Formulieren Sie die Aufgabe klar: Artikel oder Variante, Kategorie, CMS-Seite, Bild oder Nachrichtenbeitrag.

4. Sie können der KI konkrete Nummern, Kategorien, Attribute oder Hersteller nennen, oder sie auffordern, passende Einträge selbst zu suchen und zuzuordnen.

5. Prüfen Sie die vorgeschlagenen Änderungen, bevor der KI-Client sie speichert.

6. Bei Änderungen an Langbeschreibungen oder CMS-Inhalten muss der Client vorher den aktuellen Inhalt inklusive Schutzwert lesen.

7. Bilder werden nur hochgeladen, wenn die Moduleinstellungen im Bereich Bild-Uploads dafür freigegeben sind.

8. Nachrichtenbeiträge können nur geschrieben werden, wenn EcsDesk mit Nachrichten-Plugin installiert ist und Nachrichtenbeiträge bearbeiten aktiv ist. Lesen bleibt möglich.

9. Öffnen Sie im OXID-Admin den betroffenen Datensatz, um das Ergebnis zu kontrollieren.

10. Bei Fehlern prüfen Sie zuerst das Token, die IP-Whitelist, die Einstellung Erlaubte API-Administratoren und bei Bildern auch die Ziel-Einstellung.

Status, Fehler und Protokolle

Erfolgreiche Änderungen stehen sofort in der OXID-Datenbank und sind im OXID-Admin sichtbar. Fehler der API werden in verständlichen Fehlermeldungen an den KI-Client zurückgegeben. Typische Situationen sind:

• Anfrage erfolgreich ausgeführt.

• Artikel, Kategorie, CMS-Seite oder Nachrichtenbeitrag wurde neu angelegt.

• Ungültige Daten oder unbekannte Felder übermittelt.

• Token fehlt, ist ungültig oder abgelaufen.

• Die IP ist nicht in der Whitelist.

• Artikel, Kategorie, CMS-Seite oder Nachrichtenbeitrag wurde nicht gefunden.

• Aufruf erfolgte über HTTP statt HTTPS.

• Zu viele fehlgeschlagene Loginversuche von dieser IP.

• Bild-Upload nicht freigegeben oder Ziel nicht in Freigegebene Bildziele enthalten.

• Schreibzugriff für den angefragten Bereich deaktiviert (HTTP 403).

• Bildformat, Dateigröße oder Bildabmessungen ungültig.

• Bilder-Upload-Limit (Anzahl oder Megabyte) vorübergehend überschritten.

• Der Schutzwert fehlt oder stimmt nicht mit dem aktuellen Inhalt überein (parallele Änderung).

• Nachrichten-Funktion nicht verfügbar, Schreibzugriff deaktiviert oder EcsDesk-Datenverzeichnis nicht erreichbar.

Bemerkung

Das Modul speichert keine eigene Protokolldatei. Halten Sie im Produktivbetrieb Artikeländerungen und API-Aufrufe im Shop-Monitoring fest.

Empfohlene Grundeinstellung

Zugang und Sicherheit

• JWT Secret: mindestens 64 zufällige Zeichen; nichts Teilen.

• Token-Gültigkeit: 3600 Sekunden (eine Stunde).

• HTTPS für die ContentApi erzwingen: immer aktiv.

• IP-Whitelist: im Produktivbetrieb befüllen.

• Erlaubte API-Administratoren: im Produktivbetrieb befüllen.

• Vertrauenswürdige Reverse Proxies: nur tatsächliche Proxies eintragen.

Schreibzugriff

• Schreib-Checkboxen nur für Bereiche aktivieren, die der KI-Client tatsächlich bearbeiten soll. Lesen bleibt unabhängig davon möglich.

• Artikel bearbeiten und Artikel-Langbeschreibungen bearbeiten getrennt steuerbar – z. B. nur Langbeschreibungen freigeben.

• Freigegebene Artikel-Zusatzfelder: erst freigeben, wenn eine Erweiterung oder ein anderes Modul eine wirklich benötigte Spalte einführt.

• Nachrichtenbeiträge bearbeiten: nur aktivieren, wenn EcsDesk mit Nachrichten-Plugin eingerichtet und geprüft ist.

• Webshop-Cache leeren: standardmäßig deaktiviert lassen; nur bei Bedarf kurz aktivieren.

Bild-Uploads

• Bild-Uploads über die ContentApi erlauben: nur aktivieren, wenn Bilder tatsächlich benötigt werden. Danach gezielt nur die benötigten Freigegebenen Bildziele eintragen.

• Maximale Größe je Bild in Bytes: auf sinnvolles Maximum setzen, das der Server mit upload_max_filesize und post_max_size unterstützt.

Sicherheits-Checkliste vor dem Live-Betrieb

• TLS ist am öffentlichen Webserver aktiv und HTTP wird nicht unverschlüsselt bearbeitet.

• HTTPS für die ContentApi erzwingen ist aktiv.

• JWT Secret ist mindestens 32 Zeichen lang und sicher hinterlegt.

• Erlaubte API-Administratoren sind ausdrücklich eingetragen.

• IP-Whitelist ist für feste Client- oder Proxy-IP-Adressen eingerichtet.

• Vertrauenswürdige Reverse Proxies sind korrekt konfiguriert.

• Der OXID-Debugmodus ist deaktiviert.

• Die Agentur hat die Rewrite-Regeln und die Weitergabe der Authentifizierungs-Informationen geprüft.

• Backups und Wiederherstellung von Artikel- und CMS-Daten wurden getestet.

• Bild-Uploads sind nur an den bewusst freigegebenen Zielen aktiv.

• upload_max_filesize und post_max_size des Servers sind auf den in Maximale Größe je Bild in Bytes gewählten Wert oder höher eingestellt.

• Das öffentliche Bildverzeichnis out/pictures/ ist für den PHP- Prozess beschreibbar, wenn Inhalts- oder Nachrichtenbilder hochgeladen werden sollen.

• EcsDesk mit Nachrichten-Plugin ist nur für den Nachrichtenbetrieb aktiviert.

Achtung

Das ContentApi ist keine redaktionelle Vorschau. Sobald es schreibt, wird der Datensatz in der Datenbank geändert. KI-generierte HTML-Inhalte sollten vor dem Speichern auf unerwünschte Skripte oder unsachgemäße Formatierungen geprüft werden.

Was das Modul nicht automatisch erledigt

Das ContentApi:

• legt keine Attribute, Hersteller oder Lieferanten an,

• lädt Bilder nur hoch, wenn Bild-Uploads über die ContentApi erlauben und das jeweilige Ziel explizit freigegeben sind,

• löscht keine Artikel, Kategorien, CMS-Seiten oder Nachrichtenbeiträge,

• bearbeitet Nachrichtenbeiträge nur, wenn EcsDesk mit Nachrichten- Plugin eingerichtet ist und Nachrichtenbeiträge bearbeiten aktiv ist,

• versendet keine Newsletter und archiviert keine Beiträge automatisch,

• erstellt keine verschachtelten Varianten, Staffelpreise, Auswahllisten oder Bestellungen,

• führt keine automatische HTML-Reinigung durch (Inhalte werden wie eingegeben gespeichert),

• recherchiert nicht selbstständig im Web (die KI muss Rechercheaufgaben übernehmen),

• speichert keine eigenen Protokolle über Artikel- und Kategorieänderungen,

• entscheidet nicht über steuerliche oder rechtliche Zulässigkeit von Preisangaben und Inhalten.

Bemerkung

Kategorien lassen sich hingegen über die API anlegen, lesen und ändern – einschließlich Kurz-/Langbeschreibung, SEO-Metas, Sortierung, Elternkategorie, externer Link und ergänzendem Hinzufügen von Artikeln ohne Entfernen bestehender Zuordnungen.

Prüfung vor dem Live-Betrieb

Testen Sie gemeinsam mit Ihrer Agentur:

• Anmeldung mit erlaubtem und unerlaubtem Admin-Account,

• Anmeldung von einer nicht freigegebenen IP,

• Anlegen, Lesen und Ändern eines Testartikels,

• Anlegen eines Vaterartikels mit mindestens zwei Varianten, Prüfen der Auswahlwerte sowie getrennte Preise und Bestände der Varianten,

• Anlegen einer Testkategorie auf oberster Ebene und als Unterkategorie,

• Lesen und Ändern einer bestehenden Testkategorie (Kurz-/Langbeschreibung, SEO, Sortierung, Elternkategorie),

• Kategoriesuche über exakten Titel oder OXID,

• Zuweisen von Kategorien, Attributen, Zubehör und Cross-Selling,

• Hinzufügen von Artikeln zu einer Kategorie, ohne andere Zuordnungen zu entfernen,

• Setzen und erneutes Lesen der Hauptkategorie eines Artikels sowie die Vererbung vom Vaterartikel an eine Variante,

• Mehrsprachige Titel und Langbeschreibungen,

• SEO-Keywords und SEO-Description für Artikel, Kategorien und CMS-Seiten,

• Anlegen und Übersetzen einer CMS-Seite,

• Artikelsuche über Artikelnummer, Titel, EAN und OXID,

• Verhalten bei ungültigem Token, falscher IP und HTTP statt HTTPS,

• ob geänderte Artikel, Kategorien und CMS-Seiten in der Storefront korrekt dargestellt werden.

• Bild-Upload an jedem freigegebenen Ziel (Artikel-Master, Kategorie- Master, Inhaltsbild, Nachrichtenbild).

• Ersetzen eines belegten Artikel- oder Kategorie-Masterbilds mit dem passenden Schutzwert.

• Hochladen und Einbetten eines Inhaltsbilds in Artikel- Langbeschreibung, CMS-Inhalt oder Nachrichten-Body.

• Revisionsschutz: Ändern von Langbeschreibungen und CMS-Inhalten nur mit dem Schutzwert aus dem vorherigen Lesen.

• Anlegen und Ändern eines Test-Nachrichtenbeitrags (nur wenn EcsDesk mit Nachrichten-Plugin eingerichtet ist).

• Artikel-Widget in einen Nachrichtenbeitrag einbetten.

• Entkoppeln eines Artikels von einer Kategorie ohne Löschen des Artikels.

• Leeren des Webshop-Caches und Kontrolle, dass keine Fehler gemeldet werden.

Verwenden Sie im Test nur dafür freigegebene Daten und löschen Sie Testartikel nach dem Test, bis der reguläre Arbeitsablauf steht.

Häufige Fehler und Lösungen

Login wird abgelehnt

• Prüfen Sie Admin-E-Mail und Passwort.

• Prüfen Sie, ob der Benutzer aktiv und Mall-Admin ist.

• Prüfen Sie, ob der Benutzer in Erlaubte API-Administratoren steht, falls diese Liste befüllt ist.

• Prüfen Sie, ob die IP-Whitelist greift.

• Stellen Sie sicher, dass das JWT Secret mindestens 32 Zeichen lang ist.

Login vorübergehend gesperrt

• Zu viele Fehlversuche von dieser IP innerhalb des Sperrzeitraums.

• Bitten Sie die Agentur, das Login-Rate-Limit zurückzusetzen, oder warten Sie das konfigurierte Sperrfenster ab.

API-Aufruf wegen fehlender Verschlüsselung abgelehnt

• Der Aufruf erfolgte über http:// statt https://. Verwenden Sie immer HTTPS. In einer lokalen Dev-Umgebung kann die Einstellung HTTPS für die ContentApi erzwingen deaktiviert werden.

Artikel lässt sich nicht anlegen

• Die Artikelnummer darf noch nicht vergeben sein.

• Pflichtfelder wie Artikelnummer und Titel müssen enthalten sein.

• Kategorien und Attribute müssen bereits im Shop existieren.

• Die gesendeten Daten müssen im gültigen Format und Inhaltstyp ankommen.

Variante lässt sich nicht anlegen

• Der Vaterartikel muss bereits existieren und eine Variantenbezeichnung besitzen.

• Jede Variante benötigt eine eigene, noch freie Artikelnummer und eine eindeutige Auswahl beim selben Vaterartikel.

• Eine Variante kann nicht als Vaterartikel für weitere Varianten verwendet werden.

Attribute oder Kategorien werden nicht gespeichert

• Kategorien und Attribute müssen im Shop vorhanden sein.

• Beim Ändern von Kategorien oder Attributen wird die jeweilige Liste immer komplett ersetzt; übergeben Sie alle gewünschten Einträge.

• Achten Sie auf das richtige Attributformat, wie es die API erwartet.

Hauptkategorie eines Artikels lässt sich nicht setzen

• Die gewünschte Kategorie muss dem Artikel bereits zugeordnet sein. Lassen Sie sie zuerst ergänzend über die Kategorie hinzufügen, damit andere Zuordnungen erhalten bleiben.

• Verwenden Sie die eindeutige Kategorie-OXID und nicht nur den Titel der Kategorie.

• Bei einer Variante muss die Hauptkategorie am Vaterartikel gesetzt werden; die Variante übernimmt sie automatisch.

Webshop-Cache lässt sich nicht vollständig leeren

• Prüfen Sie in der Rückmeldung die Anzahl unter errors. Ein Wert größer als 0 bedeutet, dass einzelne Dateien oder Verzeichnisse nicht entfernt werden konnten.

• Ist das konfigurierte Cacheverzeichnis nicht vorhanden, nicht lesbar oder nicht zulässig, muss die Agentur die Shop-Konfiguration und die Dateirechte prüfen.

• Bestimmte betriebsnotwendige Daten werden absichtlich nicht gelöscht.

SEO-URL hat sich geändert

• Die ContentApi ändert keine bestehende SEO-URL.

• Wenn noch keine SEO-URL existierte, legt OXIDs SeoEncoder ggf. eine technische an, die das Modul sofort wieder entfernt. SEO-Keywords und Description bleiben erhalten.

CMS-Ident wird als bereits vergeben abgelehnt

• Der Ident (oxloadid) muss eindeutig sein. Prüfen Sie, ob die Seite bereits existiert, oder wählen Sie einen anderen Ident.

Inhalt oder Langbeschreibung lässt sich nicht ändern

• Der Schutzwert fehlt oder ist veraltet. Der Client muss den Datensatz erneut lesen und den aktuellen Schutzwert senden.

• Bei mehrsprachigen Sprachblöcken muss der passende Sprach-Schutzwert verwendet werden.

• Der Inhalt wurde zwischenzeitlich von jemand anderem geändert.

Bild-Upload wird abgelehnt

• Bild-Uploads über die ContentApi erlauben ist nicht aktiv oder das Ziel ist nicht in Freigegebene Bildziele eingetragen.

• Das Bild ist kein JPEG, PNG oder WebP, ist animiert oder überschreitet die zulässige Dateigröße oder Pixelanzahl.

• upload_max_filesize oder post_max_size des Servers ist niedriger als die Modul-Einstellung.

• Der Bild-Slot ist belegt: Zum Ersetzen muss das aktuelle Bild zuvor gelesen und der passende Schutzwert gesendet werden.

• Das Rate-Limit (30 Dateien / 50 MiB in 10 Minuten) ist überschritten.

• Es wurde ein lokaler Pfad, eine URL oder Base64-Daten statt einer Multipart-Datei gesendet.

Nachrichtenbeitrag lässt sich nicht anlegen oder ändern

• Nachrichtenbeiträge bearbeiten ist nicht aktiv oder das EcsDesk-Datenverzeichnis ist nicht erreichbar.

• Der Titel fehlt oder der Slug ist bereits vergeben.

• Eine angegebene Kategorie existiert im EcsDesk-Nachrichten-Plugin noch nicht.

• Der Schutzwert beim Ändern fehlt oder stimmt nicht; der Beitrag wurde zwischenzeitlich geändert.

• Im Newsletter-Body wurden Smarty- oder Shop-Variablen statt der EcsDesk-Platzhalter {{vorname}}, {{nachname}} und {{abmelden_link}} verwendet.