Integracja PIM z VTEX: jak przenieść i synchronizować dane produktowe

Najpierw ustal, który system jest właścicielem jakich danych: PIM treści produktu, ERP ceny i stany, a VTEX sprzedaż. Potem odwzoruj model danych z PIM na katalog VTEX i załóż w VTEX strukturę: kategorie, marki, grupy i pola specyfikacji. Dopiero wtedy wysyłaj przez Catalog API produkty, SKU, zdjęcia i przypisania do polityki handlowej. Ceny i stany z ERP idą osobno, przez Pricing API i Logistics API. Na koniec uruchom synchronizację zmian z kolejką, ponawianiem i raportem błędów.

Poniżej opisujemy każdy krok na podstawie dokumentacji VTEX (stan na 24.10.2026). Jeśli dopiero sprawdzasz, czy VTEX pasuje do Twojej firmy, zacznij od strony VTEX w Polsce: wdrożenie, integracje i migracja. Ten artykuł jest dla zespołów, które wybrały VTEX i planują połączenie z PIM.

• Kategorie mają zwykle trzy poziomy: departamenty, kategorie i podkategorie. Marka jest obowiązkowa i musi istnieć przed produktem.
• Produkt ma co najmniej jedno SKU (wariant) i jest przypisany do marki oraz najbardziej szczegółowej kategorii.
• Specyfikacje mają trzy warstwy: grupy, pola i wartości. Pole ma jeden z ośmiu typów (m.in. tekst, liczba, combo, radio, checkbox, tekst indeksowany); combo, radio i checkbox wymagają listy wartości. Grupy i pola należą do kategorii i obowiązują też we wszystkich jej podkategoriach.
• Specyfikacje SKU odróżniają warianty (np. rozmiar) i mogą być tylko typu combo lub radio.
• Zdjęcia przypisuje się do SKU jako adres URL obrazu dostępnego do odczytu.
• Polityka handlowa (trade policy, w API: sales channel) decyduje, w którym kanale produkt jest widoczny, z jakimi cenami i logistyką.

Kolejność wynika z zależności w katalogu VTEX: nie przypiszesz produktu do marki, której nie ma, ani specyfikacji do pola, którego nie założono.

1. Ustal identyfikatory. Klucz łączący to zwykle kod produktu z ERP, zapisany w VTEX jako RefId. VTEX po utworzeniu produktu zwraca własne ID; VTEX zaleca je zapisać, więc trzymamy je w PIM i kolejne aktualizacje trafiają w ten sam rekord.
2. Załóż drzewo kategorii: najpierw departamenty, potem kategorie, na końcu podkategorie.
3. Załóż marki.
4. Załóż grupy specyfikacji, od departamentów w dół. Grupy z kategorii nadrzędnej przechodzą na wszystkie podkategorie, więc pole, którego nie używają wszystkie podkategorie, nie powinno być w grupie rodzica.
5. Załóż pola specyfikacji i ich wartości, a potem aktywuj pola. Nieaktywne pola nie działają.
6. Wyślij produkty z kategorią i marką, a potem specyfikacje produktów.
7. Przypisz produkty do polityki handlowej. Każdy produkt musi być przypisany do głównej polityki (ID 1), żeby był widoczny w sklepie. Kolejne polityki udostępniają produkty np. marketplace'om.
8. Wyślij SKU z RefId lub EAN, a potem specyfikacje SKU. Przy tworzeniu nie ustawiaj SKU jako aktywnego; VTEX zaleca włączyć , wtedy SKU aktywuje się samo, gdy spełni warunki.
9. Dodaj zdjęcia do SKU. Bez zdjęcia SKU się nie aktywuje.
10. Wyślij ceny i stany z ERP. Pricing API: cena bazowa dla każdego SKU, opcjonalnie cena katalogowa i ceny stałe dla tabel cen. Logistics API: najpierw magazyny, potem stan każdego SKU w każdym magazynie.
11. Wyślij tłumaczenia, jeśli sklep działa w kilku językach.
12. Włącz synchronizację zmian (opisujemy ją niżej).

Pierwszy import robi się raz, a synchronizacja działa latami. Nasze zasady:

• Wysyłamy tylko zmiany. PIM wie, co się zmieniło: Akeneo ma platformę zdarzeń (Event Platform), Pimcore udostępnia dane przez Datahub, Ergonode przez API GraphQL.
• Kolejka zamiast bezpośrednich wywołań. Domyślny limit Catalog API to 45 000 zapytań na minutę na konto i 15 000 na minutę na endpoint. Pricing API przyjmuje 2000 zapisów na minutę (33 na sekundę, z zapasem 500 zapytań). Po przekroczeniu limitu VTEX zwraca błąd 429. VTEX zaleca wtedy coraz dłuższe przerwy między ponowieniami (exponential backoff) i kolejkę, a Pricing API podaje w nagłówku , ile sekund czekać.
• Timeout to nie awaria. VTEX pisze w przewodniku importu, że timeout jest przewidziany w procesie i kod integracji powinien zakładać ponowienia. Przed ponowieniem sprawdzamy, czy produkt jednak nie powstał, żeby go nie zdublować.
• Raport: co nie przeszło i dlaczego (np. SKU bez zdjęcia, brak wartości specyfikacji) wraca do PIM, do osoby, która może poprawić dane.
• Kontrola w drugą stronę. VTEX powiadamia o zmianach SKU (cena, stan, dane, aktywność) przez endpoint afiliata albo aplikację Broadcaster w VTEX IO. Tak sprawdzamy, czy SKU faktycznie się aktywowało.

1. SKU bez zdjęcia albo bez RefId i EAN zostaje nieaktywne. PIM powinien blokować publikację takiego wariantu.
2. Grupa specyfikacji w innej kategorii niż produkt. API zwraca 200 OK, ale specyfikacji nie widać ani w panelu, ani w sklepie.
3. Pole w kategorii nadrzędnej pojawia się we wszystkich podkategoriach, a nowa specyfikacja SKU jest wymagana od wszystkich SKU kategorii.
4. Brak głównej polityki handlowej: produkt nie jest widoczny. Do widoczności SKU potrzebuje też ceny w polityce i stanu.
5. Tłumaczenia z dwóch źródeł: API wielojęzyczne i tłumaczenia przez GraphQL nie działają razem.
6. Ręczne poprawki w panelu VTEX pól z PIM znikają przy następnej synchronizacji.

Zajmujemy się danymi produktowymi i integracjami od 2008 roku. Mamy za sobą ponad 70 wdrożeń PIM i e-commerce, a nasz zespół to 30+ specjalistów w Gdańsku. Jesteśmy Platynowym Partnerem Pimcore i partnerem Ergonode, wdrażamy też Akeneo.

W projekcie VTEX odpowiadamy za część, od której zależy jakość katalogu: model danych, mapowanie atrybutów na kategorie i specyfikacje, migrację katalogu oraz integrację PIM i ERP z VTEX razem z raportowaniem błędów. Jeśli kłopotem są pliki od dostawców w różnych formatach, pomaga openProd, nasza osobna platforma, która z pomocą AI importuje pliki dostawców do katalogu.