PIM-VTEX-Integration: Produktdaten importieren und synchronisieren

Wie integrieren Sie ein PIM mit VTEX? Legen Sie zuerst fest, welches System welche Daten führt: Das PIM führt die Produktinhalte, das ERP Preise und Bestände, und VTEX steuert den Verkauf. Dann bilden Sie das Datenmodell des PIM auf den VTEX-Katalog ab und legen die Struktur in VTEX an: Kategorien, Marken, Spezifikationsgruppen und -felder. Erst danach senden Sie Produkte, SKUs, Bilder und die Zuordnung zu Handelsrichtlinien über die Catalog API. Preise und Bestände aus dem ERP laufen getrennt über die Pricing API und die Logistics API. Zum Schluss richten Sie die Synchronisation von Änderungen mit Queue, Wiederholungen und Fehlerbericht ein.

Im Folgenden beschreiben wir jeden Schritt auf Basis der VTEX-Dokumentation (Stand: 24. Oktober 2026). Wenn Sie noch prüfen, ob VTEX zu Ihrem Unternehmen passt, beginnen Sie mit unserer Seite VTEX: was es ist und wie Sie es mit Produktdaten versorgen. Dieser Artikel richtet sich an Teams, die sich für VTEX entschieden haben und die Anbindung an ihr PIM planen.

Wer führt was: ERP, PIM und VTEX

Eine Integration bleibt stabil, wenn jede Information genau einen Eigentümer hat. Lässt sich eine Beschreibung sowohl im PIM als auch im VTEX-Admin ändern, weiß nach ein paar Wochen niemand mehr, welche Version stimmt.

• ERP: Artikelnummern und EANs, Preise, Bestände, B2B-Kunden. Es sendet Preise und Bestände an VTEX und empfängt Bestellungen aus VTEX.
• PIM: Namen, Beschreibungen, technische Attribute, Varianten, Bilder, Dokumente, Übersetzungen und Kategoriezuordnung. Es sendet den Katalog an VTEX.
• VTEX: Kategoriebaum des Shops, Handelsrichtlinien, Aktionen, Suche, Warenkorb und Bestellungen.

Der Kategoriebaum des Shops muss den PIM-Baum nicht kopieren. Die VTEX-Dokumentation geht offen davon aus, dass eine Struktur aus ERP oder PIM nicht immer zu einem Onlineshop passt. Dann führen wir im PIM einen eigenen Baum für den VTEX-Kanal oder eine Mapping-Tabelle für Kategorien. Eine praktische Regel: Felder, die aus dem PIM kommen, werden im VTEX-Admin nicht bearbeitet, weil die nächste Synchronisation sie ohnehin überschreibt.

So ist der VTEX-Katalog aufgebaut

• Kategorien haben meist drei Ebenen: Departments, Kategorien und Unterkategorien. Eine Marke ist Pflicht und muss vor dem Produkt existieren.
• Ein Produkt hat mindestens eine SKU (Variante) und ist einer Marke und der spezifischsten Kategorie zugeordnet.
• Spezifikationen haben drei Ebenen: Gruppen, Felder und Werte. Ein Feld hat einen von acht Typen (darunter Text, Zahl, Combo, Radio, Checkbox und indexierter Text). Combo, Radio und Checkbox brauchen eine Werteliste. Gruppen und Felder gehören zu einer Kategorie und gelten auch für alle ihre Unterkategorien.
• SKU-Spezifikationen unterscheiden Varianten (zum Beispiel die Größe) und können nur Combo oder Radio sein.
• Bilder werden einer SKU als URL eines öffentlich lesbaren Bildes zugeordnet.
• Eine Handelsrichtlinie (in der API „Sales Channel“) legt fest, in welchem Kanal ein Produkt sichtbar ist, mit welchen Preisen und welcher Logistik.

PIM-Konzepte auf VTEX abbilden

Die Begriffe im PIM hängen vom System ab: Akeneo hat Familien und Produktmodelle, Ergonode Templates und Pimcore Objektklassen. Die Tabelle zeigt, wie wir sie auf VTEX übertragen.

PIM-VTEX-Integration Schritt für Schritt

Die Reihenfolge folgt den Abhängigkeiten im VTEX-Katalog: Sie können ein Produkt keiner Marke zuordnen, die es nicht gibt, und keine Spezifikation einem Feld, das noch nicht angelegt ist.

1. Identifikatoren abstimmen. Der Verknüpfungsschlüssel ist meist der Produktcode aus dem ERP, in VTEX als RefId gespeichert. Beim Anlegen eines Produkts gibt VTEX eine eigene ID zurück. VTEX empfiehlt, sie zu speichern. Wir führen sie im PIM, damit spätere Updates denselben Datensatz treffen.
2. Kategoriebaum anlegen: zuerst Departments, dann Kategorien, dann Unterkategorien.
3. Marken anlegen.
4. Spezifikationsgruppen anlegen, von den Departments abwärts. Gruppen einer übergeordneten Kategorie gelten für alle ihre Unterkategorien. Ein Feld, das nicht jede Unterkategorie nutzt, gehört deshalb nicht in die Gruppe der übergeordneten Kategorie.
5. Spezifikationsfelder und ihre Werte anlegen, dann die Felder aktivieren. Inaktive Felder funktionieren nicht.
6. Produkte senden, mit Kategorie und Marke, danach die Produktspezifikationen.
7. Produkte einer Handelsrichtlinie zuordnen. Jedes Produkt muss in der Haupt-Handelsrichtlinie (ID 1) sein, um im Shop sichtbar zu sein. Weitere Richtlinien stellen Produkte zum Beispiel für Marktplätze bereit.
8. SKUs senden, mit RefId oder EAN, danach die SKU-Spezifikationen. Legen Sie eine SKU nicht als aktiv an. VTEX empfiehlt, ActivateIfPossible einzuschalten, damit sich die SKU selbst aktiviert, sobald sie die Bedingungen erfüllt.
9. Bilder zu den SKUs hinzufügen. Ohne Bild wird eine SKU nicht aktiv.
10. Preise und Bestände aus dem ERP senden. Pricing API: ein Basispreis für jede SKU, optional ein Listenpreis und Festpreise für Preistabellen. Logistics API: zuerst die Lager, dann der Bestand jeder SKU in jedem Lager.
11. Übersetzungen senden, wenn der Shop mehrsprachig ist.
12. Synchronisation von Änderungen einschalten (siehe unten).

Varianten, Sprachen und Handelsrichtlinien

Varianten

Eine Variantenachse aus dem PIM wird in VTEX zu einer SKU-Spezifikation vom Typ Combo oder Radio. Die VTEX-Dokumentation warnt, dass SKU-Spezifikationen Pflicht sind: Fügen Sie einer Kategorie eine neue SKU-Spezifikation hinzu, muss jede SKU dieser Kategorie sie haben. Deshalb legen wir die Variantenachsen vor dem ersten Import fest, nicht währenddessen.

Sprachen

Den mehrsprachigen Katalog schaltet der VTEX-Support auf Anfrage frei. Übersetzungen laufen über die mehrsprachige Katalog-API, getrennt für jede Locale: Namen, Beschreibungen, Keywords und URLs von Produkten, Kategorien und Marken, SKU-Namen sowie Namen und Werte von Spezifikationen. Ist diese Funktion aktiv, lassen sich Katalogübersetzungen nicht zusätzlich über GraphQL verwalten. Fehlt eine Übersetzung, zeigt VTEX Intelligent Search den Inhalt in der Standardsprache des Shops. Deshalb prüfen wir die Vollständigkeit der Übersetzungen im PIM, bevor ein Produkt in den Kanal geht. Laut Dokumentation ist die Unterstützung für FastStore in einer geschlossenen Beta.

Handelsrichtlinien

Eine Handelsrichtlinie legt Sortiment, Preise und Logistik für einen Vertriebskanal fest. Ihr Gegenstück im PIM ist der Kanal: Wir führen im PIM eine Liste der Kanäle, in denen ein Produkt verkauft werden darf, und ordnen das Produkt daraus den VTEX-Richtlinien zu. Abweichende Preise für eine andere Richtlinie werden in der Pricing API als Festpreise für eine Preistabelle hinterlegt.

Synchronisation von Änderungen und Fehlerbehandlung

Der Erstimport passiert einmal, die Synchronisation läuft über Jahre. Unsere Regeln:

• Nur Änderungen senden. Das PIM weiß, was sich geändert hat: Akeneo hat die Event Platform, Pimcore stellt Daten über den Datahub bereit, Ergonode über seine GraphQL-API.
• Queue statt direkter Aufrufe. Das Standardlimit der Catalog API liegt bei 45.000 Anfragen pro Minute und Konto und 15.000 pro Minute und Endpoint. Die Pricing API akzeptiert 2.000 Schreibvorgänge pro Minute (33 pro Sekunde, mit einer Burst-Reserve von 500 Anfragen). Oberhalb des Limits gibt VTEX den Fehler 429 zurück. VTEX empfiehlt dann wachsende Pausen zwischen den Wiederholungen (Exponential Backoff) und eine Queue. Die Pricing API liefert einen Retry-After-Header mit der Wartezeit in Sekunden.
• Ein Timeout ist kein Fehlschlag. Laut VTEX-Importleitfaden sind Timeouts im Prozess zu erwarten, und der Integrationscode sollte Wiederholungen einplanen. Vor einer Wiederholung prüfen wir, ob das Produkt nicht doch angelegt wurde, damit wir es nicht doppelt anlegen.
• Ein Bericht darüber, was fehlgeschlagen ist und warum (zum Beispiel eine SKU ohne Bild oder ein fehlender Spezifikationswert), geht zurück ins PIM, an die Person, die die Daten korrigieren kann.
• Eine Prüfung in Gegenrichtung. VTEX meldet Änderungen an SKUs (Preis, Bestand, Daten, Aktivierung) über einen Affiliate-Endpoint oder die App Broadcaster in VTEX IO. So bestätigen wir, dass eine SKU wirklich aktiv geworden ist.

Migration eines großen Katalogs zu VTEX

• Tabellen nur für Korrekturen. Der Tabellenimport von VTEX verarbeitet bis zu 10.000 Zeilen pro Datei, der Export umfasst bis zu 300.000 Produkte. Die Vorlage darf nicht verändert werden, und importieren lässt sich nur eine Tabelle, die mit allen Feldern exportiert wurde. Für eine dauerhafte Integration und große Kataloge nutzen wir die API.
• Eine technische Kategorie. Ist der Ziel-Kategoriebaum noch nicht fertig, schlägt VTEX eine inaktive technische Kategorie vor (in der Dokumentation „Integration“ genannt), die alle Produkte aufnimmt. Danach werden sie in die richtigen Kategorien verschoben. Eine technische Marke funktioniert genauso.
• Ein Pilot mit einer Kategorie. Bevor wir den ganzen Katalog senden, fahren wir einen vollständigen Durchlauf mit einer Kategorie: Produkt, SKU, Bild, Preis, Bestand und Sichtbarkeit im Shop. Danach senden wir den Rest in Paketen.
• Daten ziehen einmal um, ins PIM. Beim Umstieg von Magento, Shopware oder einem individuellen Shop bereinigen wir die Daten im PIM und veröffentlichen sie von dort zu VTEX. Ein späterer Wechsel der Shopplattform bedeutet dann keine erneute Migration der Produktdaten.

Die separate Catalog API für das Seller Portal nutzen wir nicht für die Hauptintegration: Laut VTEX ist sie in der Beta, kann eingestellt werden und ist auf 100.000 Produkte pro Konto begrenzt.

Typische Fallstricke

1. Eine SKU ohne Bild oder ohne RefId und EAN bleibt inaktiv. Das PIM sollte die Veröffentlichung einer solchen Variante blockieren.
2. Eine Spezifikationsgruppe in einer anderen Kategorie als das Produkt. Die API antwortet mit 200 OK, aber die Spezifikation ist weder im Admin noch im Shop sichtbar.
3. Ein Feld in einer übergeordneten Kategorie erscheint in jeder Unterkategorie, und eine neue SKU-Spezifikation wird von jeder SKU der Kategorie verlangt.
4. Keine Haupt-Handelsrichtlinie: Das Produkt ist nicht sichtbar. Für die Sichtbarkeit braucht eine SKU außerdem einen Preis in der Richtlinie und Bestand.
5. Übersetzungen aus zwei Quellen: Die mehrsprachige API und Übersetzungen über GraphQL funktionieren nicht zusammen.
6. Manuelle Änderungen im VTEX-Admin an Feldern aus dem PIM verschwinden bei der nächsten Synchronisation.

Pimcore, Akeneo, Ergonode und VTEX: fertiger Konnektor oder API?

Fertige Konnektoren zwischen Pimcore, Akeneo oder Ergonode und VTEX haben wir nicht gefunden. Deshalb bauen wir die Integration über die API. Am 24. Oktober 2026 haben wir den VTEX App Store (keine Treffer für Akeneo, Pimcore, Ergonode oder „PIM“), den Akeneo App Store (keine Treffer für „VTEX“) und GitHub geprüft. Integrationsplattformen (iPaaS) wie Alumio beschreiben eine Verbindung von VTEX und Akeneo innerhalb ihrer eigenen Plattform. Das ist eine Option für Unternehmen, die bereits eine solche Plattform nutzen.

Auf der VTEX-Seite nutzt die Integration die Catalog API, die Pricing API und die Logistics API. Auf der PIM-Seite: den Datahub in Pimcore, die REST-API und die Event Platform in Akeneo und die GraphQL-API in Ergonode. Welches PIM passt, hängt vom Katalog und vom Team ab, nicht von der Shopplattform. Mehr dazu auf unserer Seite zur PIM-Implementierung und auf den Seiten zu Pimcore, Akeneo und Ergonode.

So arbeiten wir bei LemonMind

Wir arbeiten seit 2010 mit Produktdaten und Integrationen: mehr als 70 PIM- und E-Commerce-Implementierungen und ein Team aus mehr als 30 Experten und Beratern in Danzig. Wir sind Pimcore Platinum Partner und Ergonode-Partner, und wir implementieren auch Akeneo.

Wenn ein Unternehmen zu VTEX wechselt, übernehmen wir den Teil, der über die Katalogqualität entscheidet: das Datenmodell, das Mapping der Attribute auf Kategorien und Spezifikationen, die Katalogmigration und die Integration von PIM und ERP mit VTEX, einschließlich Fehlerberichten. Liegt das Problem bei Lieferantendateien in vielen Formaten, hilft openProd: unsere eigenständige KI-Plattform, die Lieferantendateien in den Katalog importiert.