Import i eksport produktów w PrestaShop: metody CSV, XML i API

Wprowadzanie produktów do PrestaShop i późniejsze wyciąganie ich z systemu to mało efektowne zaplecze techniczne, od którego prędzej czy później zależy każdy katalog: migracja z innej platformy, nocny plik danych od dostawcy, który zmienia 4000 cen naraz, ERP zarządzający stanami magazynowymi i wymagający, aby PrestaShop je odzwierciedlał. PrestaShop daje do tego trzy naprawdę różne narzędzia — wbudowany importer CSV, Webservice API oraz SQL Manager do eksportu — a najdroższy błąd sprzedawców polega na sięgnięciu po niewłaściwe. Uruchomienie sklepu z 200 produktami i nocna synchronizacja 40 000 SKU to nie jest to samo zadanie, a narzędzie idealne do jednego scenariusza w drugim po cichu zawiedzie. Ten przewodnik dotyczy konkretnie danych produktów: katalogu, kombinacji, zdjęć, stanów magazynowych i cen, w obie strony. (Jeśli faktycznie potrzebujesz wyciągać z PrestaShop dane zamówień i faktur — do księgowości albo uzgodnień — to jest inna ścieżka eksportu, opisana w artykule Eksport CSV zamówień i faktur.)

Ostatnia aktualizacja: czerwiec 2026.

Wbudowany importer CSV: od niego zaczyna prawie każdy

PrestaShop ma natywny importer w sekcji Parametry zaawansowane → Import (AdminImportController). Przyjmuje pliki CSV dla produktów, kombinacji, kategorii, klientów, adresów, marek (producentów), dostawców, aliasów oraz — tam, gdzie dana wersja je udostępnia — sklepów; najpierw wybierasz typ encji, potem przesyłasz plik. Dla katalogu poniżej kilku tysięcy produktów, bez wymagania cyklicznej synchronizacji, to właściwa odpowiedź i możesz pominąć sekcję o API. Korzyść jest realna: ładujesz cały sklep z arkusza kalkulacyjnego, z poziomu zaplecza, bez programisty i bez jednej linii kodu.

Zasady formatu CSV, które powodują najwięcej awarii

Importer jest bezlitosny dla błędów formatu, a źle przygotowany plik to najczęstszy powód, dla którego import „nie działa”. Dopilnuj tych rzeczy, zanim cokolwiek prześlesz:

• Kodowanie: UTF-8 bez BOM. Jeśli plik powstał w Excelu, użyj Zapisz jako → CSV UTF-8 — zwykłe „CSV” zapisuje dane jako Windows-1252 i zamienia każdy znak z akcentem w krzaki (é staje się é). Jeśli plik ma już BOM, usuń go: sed -i '1s/^\xEF\xBB\xBF//' file.csv.
• Separator: domyślnie średnik (;). Można go zmienić na ekranie importu, ale nie przełączaj na przecinek, jeśli opisy zawierają przecinki — a zawierają je zawsze.
• Kwalifikator tekstu: podwójny cudzysłów ("). Obejmij nim każde pole, które zawiera separator albo znak nowej linii.
• Końce linii: najbezpieczniejszy jest Unix LF; CRLF jest akceptowany, ale czasem wstrzykuje pozorne puste wiersze, które importują się jako puste produkty.
• Wiersz nagłówka: nazwy kolumn albo odpowiadają nazwom pól PrestaShop, albo mapujesz je ręcznie na następnym ekranie. Importer zapamiętuje nazwane mapowanie, więc cykliczny plik od dostawcy trzeba zmapować tylko raz.

Minimalny plik produktu:

ID;Active;Name;Categories;Price (tax excl.);Tax rules ID;Reference;Quantity;Description

Ustawienie, które decyduje: aktualizacja czy duplikat

To jest rzecz, która gryzie ludzi przy drugim imporcie. Importer ma dwa tryby, które wyglądają prawie identycznie, ale działają odwrotnie. Domyślnie tworzy wiersze. Aby aktualizował istniejące produkty zamiast je klonować, musisz zaznaczyć „Użyj referencji produktu jako klucza” (albo podać prawdziwą kolumnę ID i zaznaczyć odpowiednik użycia ID jako klucza). Pomiń to podczas aktualizacji cen, a nie zaktualizujesz 4000 produktów — utworzysz 4000 duplikatów i podwoisz katalog. Co to oznacza w praktyce? Cykliczny plik od dostawcy musi mieć stabilną Reference (albo ID) w każdym wierszu, a to pole wyboru musi być włączone za każdym razem.

Kombinacje: importowane osobno, a kolejność ma znaczenie

Kombinacje (warianty) są osobną encją — najpierw importujesz produkty nadrzędne, a potem uruchamiasz drugi import z wybraną encją Kombinacje. Każdy wiersz odwołuje się do produktu nadrzędnego przez ID albo referencję i zawiera grupę atrybutów, wartość, wpływ na cenę, ilość, EAN13 oraz referencję kombinacji:

Product ID;Attribute (Name:Type:Position);Value (Value:Position);Reference;Supplier reference;EAN13;Impact on price;Quantity

Klasyczna pułapka: PrestaShop automatycznie tworzy grupy atrybutów i wartości, których wcześniej nie widział, a dopasowanie odbywa się po dokładnym ciągu znaków. „Size”, „size” i „SIZE” staną się trzema osobnymi grupami atrybutów, a lista wyboru rozmiaru zamieni się w bałagan. Ujednolić wielkość liter i pisownię trzeba w pliku przed importem, nie po nim.

Zdjęcia z URL-i — i dlaczego w tym miejscu serwer potrafi paść

Zdjęcia możesz uzupełnić, wpisując w kolumnie zdjęć listę URL-i rozdzielonych przecinkami; pierwsze stanie się zdjęciem głównym. Problemy zaczynają się przez sam mechanizm, bo każdy URL uruchamia synchroniczne pobranie w trakcie żądania importu:

• Lawina pobrań: 5000 produktów × 3 zdjęcia = 15 000 pobrań HTTP w jednym zadaniu importu. Import uruchomiony z poziomu przeglądarki przekroczy limit czasu dużo wcześniej, niż dojdzie do końca. Niezawodny schemat to dwa przebiegi: najpierw import produktów bez zdjęć, potem drugi przebieg, w mniejszych paczkach, tylko dla zdjęć.
• Mnożenie miniaturek: każde zaimportowane zdjęcie jest regenerowane do każdego formatu zdefiniowanego w Wygląd → Ustawienia obrazów. Osiem formatów oznacza osiem operacji zmiany rozmiaru na jedno zdjęcie. Przed dużym importem zdjęć tymczasowo usuń nieużywane formaty, a na końcu wygeneruj miniatury raz.
• „Usuń wszystkie zdjęcia przed importem”: ta opcja usuwa wszystkie istniejące zdjęcia dopasowanych produktów — również te dodane ręcznie — zanim wczyta nowy zestaw. To właściwe narzędzie do czystej resynchronizacji i katastrofa, jeśli nie taki był zamiar.

Jak sprawić, żeby duże importy przetrwały: limity czasu, pamięć i CLI

Importer uruchamiany z poziomu przeglądarki radzi sobie komfortowo z około 5000 produktów. Powyżej tej granicy przestajesz walczyć z formatem CSV, a zaczynasz z PHP i serwerem WWW:

• Czas wykonania: standardowe max_execution_time równe 30 sekund jest beznadziejne przy dużym pliku. Podnieś je do 600+ w php.ini (albo per import przez worker), inaczej nie skończysz nawet jednej paczki.
• Pamięć: plik CSV o wielkości 50 MB z około 20 000 produktów potrzebuje 256 MB+ pamięci PHP; ustaw memory_limit na 512M, żeby mieć zapas.
• Dziel na paczki: podziel dane na pliki po 1000–2000 wierszy. Jeśli wiersz 7400 się wysypie, uruchamiasz ponownie jedną paczkę, nie całe 40 000.
• Wyłącz indeksowanie na czas importu: w Parametry sklepu → Wyszukiwanie wyłącz „Indeksuj produkty przy zapisie” i nie regeneruj zdjęć w połowie importu. Przeindeksuj wszystko raz, na końcu. Przy dużych katalogach to największa pojedyncza oszczędność czasu — indeksowanie każdego wiersza odpowiada za większość czasu zegarowego.
• Przenieś duże zadania poza żądanie WWW: rdzeń PrestaShop nie zawiera wbudowanej komendy konsolowej prestashop:import, więc przy jednorazowej migracji 10 000+ produktów praktyczne rozwiązania to agresywne paczkowanie (pliki po 1000–2000 wierszy), podniesienie limitów serwera opisanych niżej albo uruchomienie ładowania przez wyspecjalizowany moduł importu lub skrypt API z wiersza poleceń — cokolwiek, co działa poza serwerem WWW i nie uderza w limit czasu żądania.

Wyciąganie danych produktów: opcje eksportu w PrestaShop

Eksport to słabsza strona platformy i warto powiedzieć to uczciwie. Natywna strona Import służy do importów oraz plików przykładowych — nie jest pełnym narzędziem eksportu produktów. Najbliżej wbudowanego rozwiązania w zapleczu jest przycisk Eksport na samej liście produktów, ale zwraca on tylko podstawowe pola widoczne na liście — bez kombinacji, bez cen specyficznych, bez stanów z podziałem na magazyny. Do realnej pracy są dwie lepsze drogi.

SQL Manager: koń roboczy eksportu

Parametry zaawansowane → Baza danych → SQL Manager pozwala napisać zapytanie odczytujące dane i pobrać wynik jako CSV. To najszybszy sposób, żeby dostać dokładnie te kolumny, których potrzebujesz. Aby wyeksportować każdy produkt z jego aktualnym stanem magazynowym:

SELECT p.id_product, pl.name, p.reference, p.price, sa.quantity FROM ps_product p JOIN ps_product_lang pl ON p.id_product = pl.id_product AND pl.id_lang = 1 JOIN ps_stock_available sa ON p.id_product = sa.id_product AND sa.id_product_attribute = 0;

(Zamień ps_ na rzeczywisty prefiks swoich tabel.) To świetnie łączy się z importerem przy masowych edycjach: eksport do CSV, zmiana cen albo stanów w arkuszu, ponowny import z włączoną referencją jako kluczem. Haczyk polega na tym, że SQL Manager jest tylko do odczytu i działa ręcznie — to znakomite narzędzie ad hoc, ale kiepska automatyzacja, bo ktoś musi je kliknąć.

Gdy eksport ma być cyklicznym plikiem danych

Codzienne pliki cenowe, pliki danych dla marketplace'ów i Google Shopping, nocne przekazanie danych do zewnętrznego systemu — to wymaga pliku generowanego według harmonogramu, a nie człowieka w SQL Managerze. To obszar dla modułu: generatora, który buduje wielojęzyczny plik produktów (a dla wykrywalności dba też o to, żeby mapa witryny nadążała za żywym katalogiem) przez cron, dzięki czemu plik jest świeży bez dotykania zaplecza. Jeśli właściwym zadaniem jest generowanie pliku danych, przejrzyj moduły eksportu i plików produktowych na mypresta.rocks — korzyść polega na pliku, który jest zawsze aktualny, i administratorze, który nie musi pamiętać o jego uruchamianiu.

XML i Webservice API: do integracji, nie do migracji

XML to lingua franca plików B2B, ERP-ów i marketplace'ów, a kluczowy fakt jest taki: importer CSV w PrestaShop w ogóle nie czyta XML. Masz dwie uczciwe opcje, a każda pasuje do innego celu.

Opcja 1 — konwersja XML do CSV

Jeśli dostawca przekazuje Ci plik XML, a Ty chcesz jednorazowo wprowadzić go do katalogu, przekształć go do układu CSV wymaganego przez PrestaShop za pomocą arkusza XSLT, krótkiego skryptu w Pythonie (xml.etree.ElementTree obsłuży większość płaskich plików od dostawców w znacznie mniej niż 50 liniach) albo narzędzia danych takiego jak Talend lub Akeneo. Potem podaj wynik natywnemu importerowi. Prosto, bez włączania API, idealnie do jednorazowego załadowania.

Opcja 2 — bezpośrednia komunikacja z Webservice API

Przy ciągłej, dwukierunkowej synchronizacji właściwą warstwą jest Webservice API. To interfejs w stylu REST z pełnym CRUD dla produktów, kombinacji, kategorii, stanów magazynowych, klientów i zamówień. Klasyczny (legacy) Webservice jest zorientowany przede wszystkim na XML — to na tym formacie warto budować rozwiązania dla obsługiwanych wersji; JSON zwykle nie jest dostępny w legacy webservice, więc jeśli konkretnie potrzebujesz JSON, sprawdź, czy Twoja wersja PrestaShop zawiera nowsze Symfony-based Admin API. Włącz go w Parametry zaawansowane → Webservice, następnie utwórz klucz i przyznaj mu tylko te zasoby oraz czasowniki, których potrzebuje — nigdy nie dawaj kluczowi pełnego dostępu do wszystkich zasobów. Produkt utworzysz żądaniem POST do https://yourstore.com/api/products z treścią XML; aktualizujesz przez PUT z ID produktu w URL-u; odpowiedź zwraca encję z jej nowym ID.

Trzy realia, które trzeba uwzględnić, zanim zaczniesz na tym budować:

• Jedna encja na żądanie. Nie ma endpointu masowego — 10 000 produktów to 10 000 wywołań. W rdzeniu legacy webservice nie ma wbudowanego limitowania liczby żądań API, ale hosting, warstwa bezpieczeństwa/WAF albo własny Apache (mod_evasive) czy Nginx (limit_req) mogą przyciąć nagły ruch, więc rozstaw wywołania co około 100–200 ms, a import 10k stanie się zaplanowanym oknem około 30 minut, nie niespodzianką.
• Zdjęcia się przesyła, a nie pobiera. Wyślij plik metodą POST do /api/images/products/{id}, a PrestaShop zapisze go bezpośrednio — to znacznie bardziej niezawodne niż podejście CSV z pobieraniem po URL-u, bo nic nie zależy od tego, czy serwer pobierze zdalny URL w połowie importu.
• Zbuduj logikę ponawiania. API odpowiada kodami HTTP (201 created, 200 updated, 404 not found, 500 server error). Loguj każdą odpowiedź i ponawiaj 500 — przy tysiącach wywołań kilka może chwilowo się nie udać, a synchronizacja, której nie da się wznowić, nie zasługuje na zaufanie.

Błędy, które naprawdę zobaczysz — i ich naprawa

• „Property X is empty”: wymagane pole (nazwa, cena, kategoria) jest puste. Sprawdź, czy każda wymagana kolumna ma wartość w każdym wierszu.
• „The category does not exist”: odwołujesz się do ID kategorii, którego nie ma. Najpierw zaimportuj kategorie albo użyj nazw kategorii — importer akceptuje oba warianty i utworzy brakujące.
• Ceny po imporcie są błędne: importer czyta ceny bez podatku. Jeśli plik zawiera ceny brutto, najpierw podziel je przez (1 + stawka) albo zmapuj właściwą regułę podatkową.
• Znaki z akcentami zamieniły się w śmieci: plik nie jest w UTF-8. Przekonwertuj go: iconv -f Windows-1252 -t UTF-8 input.csv > output.csv.
• Import „zadziałał”, ale produkty są niewidoczne: sprawdź Active=1, przypisaną prawdziwą kategorię, poprawne powiązanie ze sklepem w multistore oraz to, czy indeks produktów został odbudowany.
• Duplikaty po ponownym imporcie: zapomniałeś o „Użyj referencji produktu jako klucza” (albo ID jako kluczu). To aktualizuje zamiast klonować — zobacz ostrzeżenie wyżej.

Wybór właściwej metody

Dopasuj narzędzie do zadania, nie do przyzwyczajenia:

Najczęściej zadawane pytania

Mój drugi import utworzył duplikaty zamiast aktualizować produkty. Co pominąłem?

Pole wyboru „Użyj referencji produktu jako klucza” (albo odpowiednik z ID jako kluczem). Domyślnie importer tworzy wiersze, więc uruchomienie aktualizacji cen bez zaznaczenia tego pola klonuje każdy produkt zamiast go zaktualizować. Upewnij się, że każdy wiersz ma stabilną Reference albo ID, i zaznacz opcję klucza przy każdym cyklicznym uruchomieniu.

Dlaczego po imporcie wszystkie znaki z akcentami zamieniły się w śmieci?

Plik nie jest w UTF-8. Zwykły zapis „CSV” w Excelu używa Windows-1252, co psuje znaki diakrytyczne — zamiast tego użyj Zapisz jako → CSV UTF-8 i usuń początkowy BOM, jeśli występuje. Sekcja artykułu o kodowaniu pokazuje dokładnie, jak wyglądają uszkodzone znaki, oraz jednoliniową komendę iconv, która konwertuje plik Windows-1252 z powrotem do czystego UTF-8.

Czy wbudowany importer może czytać plik XML?

Nie — importer CSV w ogóle nie czyta XML. Przy jednorazowym ładowaniu najpierw przekształć XML do układu CSV wymaganego przez PrestaShop (arkusz XSLT albo krótki skrypt xml.etree.ElementTree obsłuży większość płaskich plików od dostawców). Przy ciągłej synchronizacji dwukierunkowej użyj bezpośrednio Webservice API zamiast za każdym razem konwertować pliki.

Mój import dużego katalogu ciągle przekracza limit czasu. Jak go doprowadzić do końca?

Importer uruchamiany z poziomu przeglądarki radzi sobie komfortowo z około 5000 produktów. Powyżej tej granicy podziel dane na paczki po 1000–2000 wierszy, podnieś max_execution_time (do 600+) i memory_limit (do 512M), a na czas importu wyłącz „Indeksuj produkty przy zapisie” — indeksowanie każdego wiersza odpowiada za większość czasu zegarowego. Rdzeń PrestaShop nie zawiera komendy konsolowej prestashop:import, więc przy migracji 10 000+ produktów uruchom ładowanie przez moduł importu albo skrypt API działający poza żądaniem WWW.

Jak masowo edytować ceny albo stany bez ponownego importu całego katalogu?

Zrób pełną pętlę przez SQL Manager: wyeksportuj potrzebne kolumny do CSV, zmień je w arkuszu, a potem zaimportuj ponownie z włączoną referencją jako kluczem, żeby aktualizować zamiast klonować. Przy częstych zmianach cen nasze moduły masowej aktualizacji cen i plików produktowych robią to z poziomu zaplecza według harmonogramu, więc nie musisz ręcznie uruchamiać SQL Managera ani za każdym razem pamiętać o polu klucza.

Gdzie import/eksport łączy się z resztą operacji

Import i eksport rzadko żyją osobno — zwykle są jednym ruchem w większym procesie katalogowym albo magazynowym. Kilka powiązanych tematów, które warto znać:

• Stany magazynowe przez CSV. Masowa aktualizacja ilości to po prostu import dwóch kolumn z kluczem po referencji. Ale głębsze pytanie — jaki powinien być poziom tych liczb i kiedy uzupełniać zapasy — to osobna dyscyplina: zobacz kiedy ponownie zamawiać towar.
• Wyrastanie z arkusza kalkulacyjnego. Jeśli bez przerwy przerzucasz pliki CSV tam i z powrotem tylko po to, żeby utrzymać porządek w stanach, zwykle oznacza to, że czas na prawdziwe narzędzie magazynowe — artykuł kiedy arkusze przestają wystarczać opisuje ten moment przejścia.
• Eksport zamówień i faktur. Inna encja, inna ścieżka — wyciąganie danych zamówień do księgowości opisuje artykuł Eksport CSV zamówień i faktur.

Dane produktów to praca, której nikt nie celebruje, ale od której zależą wszyscy: czyste importy oznaczają poprawne oferty, właściwe ceny i stany magazynowe zgodne z rzeczywistością. Zasada stojąca za wszystkimi trzema metodami jest taka sama — utrzymuj stabilny klucz przy każdym produkcie, wybieraj narzędzie pasujące do skali zadania i nigdy nie uruchamiaj importu drugi raz bez wiedzy, czy tworzy, czy aktualizuje. Jeśli tak naprawdę chodzi Ci o cykliczne generowanie plików danych albo planowane przekazywanie danych produktowych, moduły eksportu i map witryny na mypresta.rocks są zbudowane dokładnie do tego — plik pozostaje aktualny bez konieczności pamiętania o kliknięciu przycisku.