Integracja PIM z VTEX: jak importować i synchronizować dane produktowe

Jak zintegrować PIM z VTEX? Najpierw trzeba ustalić, który system odpowiada za które dane: PIM za treści produktowe, ERP za ceny i stany, a VTEX za sprzedaż. Potem należy zmapować model danych PIM na katalog VTEX i utworzyć w VTEX strukturę: kategorie, marki, grupy i pola specyfikacji. Dopiero wtedy produkty, SKU, zdjęcia i przypisania do polityk handlowych trafiają do VTEX przez Catalog API. Ceny i stany z ERP idą osobno, przez Pricing API i Logistics API. Na koniec uruchamia się synchronizację zmian z kolejką, ponowieniami i raportem błędów.

Poniżej opisujemy każdy krok na podstawie dokumentacji VTEX (stan na 24 października 2026). Jeśli firma dopiero sprawdza, czy VTEX do niej pasuje, warto zacząć od naszej strony VTEX: czym jest i jak zasilić go danymi produktowymi. Ten artykuł jest dla zespołów, które wybrały już VTEX i planują połączenie z PIM.

Kto za co odpowiada: ERP, PIM i VTEX

Integracja pozostaje stabilna, gdy każda informacja ma jednego właściciela. Jeśli opis można zmienić zarówno w PIM, jak i w panelu VTEX, po kilku tygodniach nikt nie wie, która wersja jest prawdziwa.

• ERP: indeksy i kody EAN, ceny, stany magazynowe, klienci B2B. Wysyła ceny i stany do VTEX i odbiera z VTEX zamówienia.
• PIM: nazwy, opisy, atrybuty techniczne, warianty, zdjęcia, dokumenty, tłumaczenia i przypisanie do kategorii. Wysyła katalog do VTEX.
• VTEX: drzewo kategorii sklepu, polityki handlowe, promocje, wyszukiwarka, koszyk i zamówienia.

Drzewo kategorii sklepu nie musi kopiować drzewa z PIM. Dokumentacja VTEX wprost zakłada, że struktura z ERP lub PIM może nie pasować do sklepu internetowego. Wtedy w PIM utrzymujemy osobne drzewo dla kanału VTEX albo tabelę mapowania kategorii. Praktyczna zasada: pól, które pochodzą z PIM, nie edytuje się w panelu VTEX, bo następna synchronizacja i tak je nadpisze.

Jak zbudowany jest katalog VTEX

• Kategorie mają zwykle trzy poziomy: działy, 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 do najbardziej szczegółowej kategorii.
• Specyfikacje mają trzy warstwy: grupy, pola i wartości. Pole ma jeden z ośmiu typów (m.in. text, number, combo, radio, checkbox i indexed text); 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 publicznie dostępnego obrazu.
• Polityka handlowa (w API: sales channel) decyduje, w którym kanale produkt jest widoczny, z jakimi cenami i logistyką.

Mapowanie pojęć PIM na VTEX

Nazewnictwo w PIM zależy od systemu: Akeneo ma rodziny i modele produktów, Ergonode szablony, a Pimcore klasy obiektów. Tabela pokazuje, jak przekładamy je na VTEX.

Integracja PIM z VTEX krok po kroku

Kolejność wynika z zależności w katalogu VTEX: nie da się przypisać produktu do marki, która nie istnieje, ani specyfikacji do pola, którego jeszcze nie utworzono.

1. Uzgodnienie identyfikatorów. Kluczem łączącym jest zwykle kod produktu z ERP, zapisany w VTEX jako RefId. Przy tworzeniu produktu VTEX zwraca własne ID; VTEX zaleca jego zapisanie, więc przechowujemy je w PIM, a kolejne aktualizacje trafiają do tego samego rekordu.
2. Utworzenie drzewa kategorii: najpierw działy, potem kategorie, na końcu podkategorie.
3. Utworzenie marek.
4. Utworzenie grup specyfikacji, od działów w dół. Grupy z kategorii nadrzędnej przechodzą na wszystkie jej podkategorie, więc pole, którego nie używa każda podkategoria, nie powinno trafiać do grupy kategorii nadrzędnej.
5. Utworzenie pól specyfikacji i ich wartości, a potem aktywacja pól. Nieaktywne pola nie działają.
6. Wysłanie produktów z kategorią i marką, a potem specyfikacji produktów.
7. Przypisanie produktów do polityki handlowej. Każdy produkt musi być w głównej polityce handlowej (ID 1), żeby był widoczny w sklepie. Kolejne polityki udostępniają produkty np. marketplace'om.
8. Wysłanie SKU z RefId lub EAN, a potem specyfikacji SKU. SKU nie tworzy się jako aktywnego; VTEX zaleca włączenie ActivateIfPossible, dzięki czemu SKU aktywuje się samo, gdy spełni warunki.
9. Dodanie zdjęć do SKU. Bez zdjęcia SKU się nie aktywuje.
10. Wysłanie cen i stanów 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. Wysłanie tłumaczeń, jeśli sklep działa w kilku językach.
12. Włączenie synchronizacji zmian (opisanej niżej).

Warianty, języki i polityki handlowe

Warianty

Oś wariantu z PIM staje się w VTEX specyfikacją SKU typu combo lub radio. Dokumentacja VTEX ostrzega, że specyfikacje SKU są obowiązkowe: po dodaniu nowej specyfikacji SKU do kategorii musi ją mieć każde SKU w tej kategorii. Dlatego osie wariantów ustalamy przed pierwszym importem, a nie w jego trakcie.

Języki

Wielojęzyczny katalog włącza na wniosek wsparcie VTEX. Tłumaczenia wysyła się przez wielojęzyczne API katalogu, osobno dla każdego locale: nazwy, opisy, słowa kluczowe i adresy URL produktów, kategorii i marek, nazwy SKU oraz nazwy i wartości specyfikacji. Po włączeniu tej funkcji tłumaczeniami katalogu nie można już zarządzać równolegle przez GraphQL. Gdy brakuje tłumaczenia, VTEX Intelligent Search pokazuje treść w domyślnym języku sklepu, dlatego kompletność tłumaczeń sprawdzamy w PIM, zanim produkt trafi do kanału. Według dokumentacji obsługa FastStore jest w zamkniętej becie.

Polityki handlowe

Polityka handlowa określa asortyment, ceny i logistykę dla kanału sprzedaży. Jej odpowiednikiem w PIM jest kanał: w PIM prowadzimy listę kanałów, w których produkt może być sprzedawany, i na jej podstawie przypisujemy produkt do polityk VTEX. Inne ceny dla kolejnej polityki ustawia się w Pricing API jako ceny stałe dla tabeli cen.

Synchronizacja zmian i obsługa błędów

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

• Wysyłamy tylko zmiany. PIM wie, co się zmieniło: Akeneo ma Event Platform, Pimcore udostępnia dane przez Datahub, a Ergonode przez GraphQL API.
• 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 na skok do 500 zapytań). Powyżej limitu VTEX zwraca błąd 429. VTEX zaleca wtedy rosnące przerwy między ponowieniami (exponential backoff) i kolejkę, a Pricing API zwraca nagłówek Retry-After z liczbą sekund oczekiwania.
• Timeout to nie awaria. Przewodnik importu VTEX mówi, że timeout jest w tym procesie spodziewany, a kod integracji powinien przewidywać ponowienia. Przed ponowieniem sprawdzamy, czy produkt jednak nie powstał, żeby go nie zdublować.
• Raport, co się nie udało i dlaczego (np. SKU bez zdjęcia albo 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, aktywacja) przez endpoint afilianta albo aplikację Broadcaster w VTEX IO. Tak potwierdzamy, że SKU faktycznie się aktywowało.

Migracja dużego katalogu do VTEX

• Arkusze tylko do poprawek. Import z arkusza w VTEX przyjmuje do 10 000 wierszy na plik, a eksport obejmuje do 300 000 produktów. Szablonu nie wolno zmieniać, a zaimportować można tylko arkusz wyeksportowany ze wszystkimi polami. Przy trwałej integracji i dużych katalogach korzystamy z API.
• Kategoria techniczna. Gdy docelowe drzewo kategorii nie jest gotowe, VTEX proponuje nieaktywną kategorię techniczną (w dokumentacji „Integration”), która przyjmuje wszystkie produkty. Później przenosi się je do właściwych kategorii. Tak samo działa marka techniczna.
• Pilotaż na jednej kategorii. Zanim wyślemy cały katalog, przechodzimy pełny cykl na jednej kategorii: produkt, SKU, zdjęcie, cena, stan i widoczność w sklepie. Potem wysyłamy resztę partiami.
• Dane przenosimy raz, do PIM. Przy przejściu z Magento, Shopware czy sklepu na zamówienie czyścimy dane w PIM i stamtąd publikujemy je do VTEX. Kolejna zmiana platformy sklepu nie oznacza wtedy kolejnej migracji danych produktowych.

Do głównej integracji nie używamy osobnego Seller Portal Catalog API: według VTEX jest w fazie beta, może zostać wycofane i ma limit 100 000 produktów na konto.

Typowe pułapki

1. SKU bez zdjęcia albo bez RefId i EAN pozostaje nieaktywne. PIM powinien blokować publikację takiego wariantu.
2. Grupa specyfikacji w innej kategorii niż produkt. API zwraca 200 OK, ale specyfikacja nie jest widoczna ani w panelu, ani w sklepie.
3. Pole w kategorii nadrzędnej pojawia się w każdej podkategorii, a nowa specyfikacja SKU jest wymagana od każdego SKU w kategorii.
4. Brak głównej polityki handlowej: produkt nie jest widoczny. Żeby SKU było widoczne, potrzebuje też ceny w polityce i stanu magazynowego.
5. Tłumaczenia z dwóch źródeł: wielojęzyczne API i tłumaczenia przez GraphQL nie działają razem.
6. Ręczne zmiany w panelu VTEX w polach pochodzących z PIM znikają przy następnej synchronizacji.

Pimcore, Akeneo, Ergonode i VTEX: gotowy konektor czy API?

Nie znaleźliśmy gotowych konektorów między Pimcore, Akeneo czy Ergonode a VTEX, dlatego integrację budujemy przez API. 24 października 2026 sprawdziliśmy VTEX App Store (brak wyników dla Akeneo, Pimcore, Ergonode i „PIM”), Akeneo App Store (brak wyników dla „VTEX”) i GitHub. Platformy integracyjne (iPaaS), takie jak Alumio, opisują połączenie VTEX z Akeneo w ramach własnej platformy. To opcja dla firm, które już z takiej platformy korzystają.

Po stronie VTEX integracja korzysta z Catalog API, Pricing API i Logistics API. Po stronie PIM: z Datahub w Pimcore, REST API i Event Platform w Akeneo oraz GraphQL API w Ergonode. Wybór PIM zależy od katalogu i zespołu, a nie od platformy sklepu. Więcej na stronie wdrożenia PIM oraz na stronach o Pimcore, Akeneo i Ergonode.

Jak pracujemy w LemonMind

Działamy od 2010 roku i zajmujemy się danymi produktowymi i integracjami: ponad 70 wdrożeń PIM i eCommerce, zespół ponad 30 ekspertów i konsultantów w Gdańsku. Jesteśmy Pimcore Platinum Partner i partnerem Ergonode, wdrażamy też Akeneo.

Gdy firma przechodzi na VTEX, bierzemy na siebie część, która decyduje o jakości 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 problemem są pliki od dostawców w wielu formatach, pomaga openProd: nasza osobna platforma AI, która importuje pliki dostawców do katalogu.