Import XML do PrestaShop bez duplikatów: identyfikatory i zasady aktualizacji

Import XML bez duplikatów zaczyna się od stałego, jednoznacznego identyfikatora oraz zapisanej relacji między rekordem dostawcy a produktem w PrestaShop. Przed pierwszym uruchomieniem ustal, co importer może tworzyć, które pola aktualizuje i co oznacza brak produktu w kolejnym pliku. Sam poprawny XML nie daje odpowiedzi na te pytania.

Poradnik jest przeznaczony dla sklepów planujących import z hurtowni lub innego systemu. Dwa małe pliki demonstracyjne pokazują, jak odróżnić nowy produkt, zmianę danych i brak rekordu. Nie są feedem rzeczywistego dostawcy ani uniwersalnym formatem obsługiwanym przez każdy importer.

1. Wybierz system odpowiedzialny za każde pole

Najpierw zdecyduj, skąd pochodzi prawidłowa cena, stan, nazwa i opis. Często hurtownia odpowiada za dostępność oraz cenę zakupu, a sklep utrzymuje własny opis i cenę sprzedaży wyliczaną według reguły. Jeśli importer nadpisze wszystkie pola przy każdej aktualizacji, może usunąć pracę redakcyjną wykonaną w sklepie.

Przy wielu dostawcach doprecyzuj również, czy oferują ten sam towar, czy oddzielne oferty. Obsługa wielu źródeł nie oznacza automatycznie sumowania stanów, wybierania najniższej ceny ani przełączania dostawcy. Taka reguła wymaga zaprojektowania, a następnie potwierdzenia w konkretnym rozwiązaniu.

2. Nie myl ID dostawcy z ID produktu w sklepie

Rekord A-100 w XML może odpowiadać produktowi 501 w PrestaShop. Te numery nie muszą być identyczne. Importer powinien znać ich powiązanie i wykorzystać je przy kolejnym odczycie. Tworzenie nowej karty przy każdej zmianie nazwy jest błędem modelu identyfikacji.

Identyfikator musi być stabilny w czasie oraz jednoznaczny w wybranym zakresie. Jeżeli dwie hurtownie używają numeru 100, bezpieczne powiązanie powinno uwzględniać źródło, a nie wyłącznie tę liczbę. Nie zakładaj też, że EAN zawsze jest dostępny i unikalny: w pliku mogą istnieć braki, błędy lub powtórzenia wymagające wyjaśnienia.

Przed pierwszym dopasowaniem do istniejącego katalogu przygotuj raport brakujących i powtarzających się kluczy. Nie wybieraj automatycznie „pierwszego znalezionego” produktu, jeżeli istnieją dwie karty z tym samym indeksem.

3. Produkt i wariant potrzebują odrębnych zasad

Jedna karta produktu może mieć kilka kombinacji, każdą z własnym stanem, indeksem, zdjęciem lub wpływem na cenę. Ustal, czy rekord XML opisuje całą kartę, czy pojedynczy wariant. Jeśli dostawca przesyła osobne rozmiary jako osobne rekordy, ich połączenie w jedną kartę wymaga reguły grupowania.

Sprawdź również znaczenie ceny wariantu: może być pełną ceną albo różnicą względem produktu bazowego. Użycie różnicy jako ceny końcowej daje nieprawidłowy wynik. Podobna ostrożność dotyczy zestawów atrybutów — zmiana nazwy koloru nie powinna bez decyzji tworzyć kolejnego wariantu.

Jeśli importer synchronizuje pełny zestaw kombinacji, ustal, czy warianty nieobecne w pliku mają zostać zachowane, wyłączone czy usunięte. Jest to szczególnie ważne, gdy część wariantów sklep utrzymuje samodzielnie.

4. Dwie wersje XML i oczekiwany wynik

Poniższa struktura została przygotowana wyłącznie do demonstracji. Ceny są cenami wejściowymi netto w PLN. W przykładzie nie tworzymy wariantów; każdy rekord odpowiada jednej karcie produktu. Parser lub adapter konkretnego importera musi zostać dopasowany do rzeczywistej struktury źródła.

Pierwszy pełny plik

<catalog source="demo" currency="PLN" price_type="net" complete="true">
  <product supplier_id="A-100">
    <reference>DEMO-BUTELKA</reference>
    <name>Butelka oliwkowa</name>
    <price>50.00</price>
    <quantity>12</quantity>
  </product>
  <product supplier_id="A-200">
    <reference>DEMO-KUBEK</reference>
    <name>Kubek kremowy</name>
    <price>20.00</price>
    <quantity>8</quantity>
  </product>
</catalog>

Kolejny pełny plik

<catalog source="demo" currency="PLN" price_type="net" complete="true">
  <product supplier_id="A-100">
    <reference>DEMO-BUTELKA</reference>
    <name>Butelka oliwkowa</name>
    <price>55.00</price>
    <quantity>0</quantity>
  </product>
  <product supplier_id="A-300">
    <reference>DEMO-KOC</reference>
    <name>Koc beżowy</name>
    <price>40.00</price>
    <quantity>5</quantity>
  </product>
</catalog>

Atrybut complete="true" jest częścią naszego przykładu, nie standardową gwarancją kompletności XML. W rzeczywistym wdrożeniu trzeba ustalić, jak dostawca potwierdza kompletność i jak importer ją rozpoznaje.

To są oczekiwane wyniki scenariusza, nie wynik uruchomionego importu. Numery produktów w sklepie są przykładowe. Dwa powyższe pliki mają schemat poglądowy <catalog>; nie są plikami wejściowymi przykładowego adaptera modułu.

Ponowne przetworzenie tego samego poprawnego pliku nie powinno tworzyć następnej butelki ani następnego koca. Porównanie po drugim uruchomieniu jest prostym kryterium odbioru dopasowania. Dla importera pomijającego niezmienione rekordy prawidłowym wynikiem może być także ich pominięcie.

Osobna próba mapowania w kodzie modułu 2.0.5

27 września sprawdziliśmy w pamięci metodę SampleAdapter::mapProduct() na trzech małych plikach XML, na PHP 7.0 i 8.1. Ten adapter oczekuje struktury <offers><offer id="..."> oraz pól nazwa, cena_netto i stan_magazynowy. Różni się to od poglądowego schematu <catalog> powyżej. Nie wykonaliśmy pobrania URL ani importu do bazy sklepu.

Pobierz dane i zapisane wyniki próby mapowania (ZIP, 4,4 kB): trzy pliki XML, wyniki PHP 7.0 i 8.1 oraz instrukcja porównania. To materiały z opisanej próby z 27.09.2026, udostępnione 28.09.2026. Paczka nie zawiera modułu ani konfiguracji do pełnego importu. Wynik 19,99 → 19 dokumentuje błąd formatu ceny, a nie prawidłową cenę.

Granica próby: to wynik mapowania pól, a nie dowód utworzenia albo aktualizacji kart, obsługi wariantów czy braku duplikatów po ponownym imporcie. SampleAdapter jest wyłączony z wyboru w panelu i sam oznaczony jako przykład niewłaściwy do produkcji. Nie uruchamiaj pełnego importu krótkiej próbki na istniejącym źródle: reguła dla produktów nieobecnych w pliku może zmienić stan katalogu. Pełen odbiór wymaga odizolowanej kopii sklepu, potwierdzenia kompletności feedu i porównania kart przed oraz po przebiegu.

5. Brak rekordu to nie zawsze brak towaru

Produkt może zniknąć z pełnego katalogu, ale może też nie wystąpić w pliku zawierającym wyłącznie zmiany. Pusty plik, błąd logowania, częściowe pobranie lub nieukończony import to jeszcze inne sytuacje. Nie powinny automatycznie prowadzić do wyłączenia całego asortymentu.

Przed wykonaniem operacji dla brakujących produktów potwierdź poprawne pobranie, odczyt i zakończenie właściwego typu importu. Ustal też zakres: tylko karty powiązane z tym źródłem. Zniknięcie rekordu hurtowni A nie powinno samoczynnie modyfikować ręcznie dodanego produktu lub oferty hurtowni B.

W przykładzie pozostawiamy brakujący kubek do kontroli, aby pokazać różnicę między brakiem informacji a jawnym stanem zero. To wybrana zasada demonstracji, nie ustawienie właściwe dla każdego sklepu. Dla produkcji decyzję trzeba powiązać z charakterem źródła i ryzykiem sprzedaży niedostępnego towaru.

6. Pełny import a szybka aktualizacja

W kodzie Import hurtownia Pro / pdxmlimport 2.0.4 pełny import i szybka aktualizacja mają różny zakres. Pełna ścieżka może tworzyć produkty i aktualizować dane obsługiwane przez adapter zgodnie z konfiguracją. Szybka aktualizacja dotyczy cen i ilości produktów bazowych już powiązanych ze źródłem; nie jest ścieżką tworzenia nowych kart ani aktualizacji stanów poszczególnych kombinacji.

Nie zakładaj, że przełączniki nadpisywania nazw i opisów kontrolują każdą operację modułu. Przed harmonogramem wskaż dokładną akcję, źródło i zakres. Zmiana reguły cenowej może także wymagać ponownego przetworzenia danych mimo niezmienionego XML.

Jeżeli potrzebujesz wyłącznie aktualizacji istniejących kart z CSV, zobacz oddzielne poradniki o cenach i o stanach. Wybór formatu powinien wynikać z danych i operacji, które rzeczywiście trzeba wykonywać.

7. Harmonogram dopiero po kontroli wyniku

Pierwszą próbę wykonaj na małym, reprezentatywnym zestawie obejmującym nowy produkt, produkt już powiązany, brak identyfikatora, kolizję i warianty. Porównaj liczbę dodanych, zmienionych, pominiętych i błędnych rekordów. Otwórz karty produktów i sprawdź cenę sprzedaży, stan, zdjęcia oraz mapowanie kategorii.

Dopiero potem ustaw kolejność pobierania i przetwarzania partii oraz częstotliwość CRON. Harmonogram powinien uwzględniać publikację pliku przez dostawcę i rzeczywisty czas importu. Ustal, kto reaguje na błąd oraz jak rozpoznaje nieukończony przebieg. Samo uruchomienie adresu CRON nie jest dowodem aktualizacji całego katalogu.

Prześlij próbkę struktury XML bez danych poufnych i opisz zasady aktualizacji. Po sprawdzeniu pól oraz wariantów można ustalić zakres importu i eksportu danych PrestaShop. Jeśli istniejący adapter obsługuje tę strukturę, sprawdź Import hurtownia Pro; inny układ danych wymaga dopasowania i próby na kopii sklepu.

Import katalogu nie oznacza automatycznie wysyłania zamówień do hurtowni, rezerwacji towaru ani dwukierunkowej synchronizacji. Te potrzeby należy osobno umieścić w zakresie integracji.

Weryfikacja pierwotnego tekstu: 13 września 2026 w kodzie pdxmlimport 2.0.4. Osobna próba mapowania: 27 września 2026 w lokalnym kodzie 2.0.5 na PHP 7.0 i 8.1, bez importu do sklepu. Pliki XML i numery produktów są demonstracyjne; nie zawierają danych ani struktury chronionego feedu hurtowni.

8. Jak sprawdzać pobranie próbki i wynik importu

Udostępniona paczka z próbą mapowania XML ma 4458 bajtów i SHA-256 6530346c85c22fc0665533dc8f76e82aaa86019fde6a73c437f66f362b483f3b. To pozwala porównać, czy pobrany plik jest tym samym materiałem, który opisuje artykuł. Sama zgodność pliku ZIP nadal nie oznacza, że wykonano import w sklepie.

03.10.2026 wykonano techniczny test publicznego pobrania tego ZIP-u. Plik został pobrany, a zdarzenie pomiarowe miało odpowiedź HTTP 204, ale odczyty GA4 w tym samym etapie nadal nie pokazały raportowego content_download ani file_download. Wniosek praktyczny: przy odbiorze rozdzielaj dostępność pliku, transport zdarzenia, raport analityczny i faktyczny wynik importu. Nie traktuj jednego z tych etapów jako dowodu pozostałych.