Import Export CSV i XML dla PrestaShop: kompletny przewodnik

DF CSV & XML Pro to uniwersalny silnik importu i eksportu dla PrestaShop 8 i 9. Łączy dowolny plik CSV lub XML z Twoim sklepem dzięki wizualnemu mapowaniu kolumn, zapisuje każdą konfigurację w profilu wielokrotnego użytku i potrafi automatycznie pobierać strumienie od dostawców z FTP, SFTP lub adresu URL. Ten przewodnik obejmuje instalację, tworzenie profili, oczekiwane formaty kolumn, harmonogram cron, dzienniki i rozwiązywanie problemów.

Instalacja

Przejdź do Moduły > Menedżer modułów > Dodaj moduł, wyślij plik dfcsvpro.zip, a następnie kliknij Zainstaluj. Po instalacji zakładka DF CSV Pro pojawia się w sekcji Ustawienia zaawansowane.

Tworzenie profilu

Profil opisuje kompletną operację: kierunek (import lub eksport), encję, format, źródło, mapowanie kolumn, opcje i harmonogram. Uruchamia się go jednym kliknięciem albo automatycznie przez cron. Kliknij Nowy profil: kreator przeprowadzi Cię przez cztery kroki.

1. Ogólne

Wybierz kierunek (import / eksport), encję, format (CSV lub XML) i docelowy język. Dla CSV ustaw separator (albo zostaw wykrywanie automatyczne), kodowanie (UTF-8, ISO-8859-1 lub Windows-1252), liczbę wierszy do pominięcia przed nagłówkiem oraz separator wielu wartości (domyślnie przecinek). Dla XML możesz wskazać węzeł elementu albo pozwolić modułowi go wykryć.

Encje dostępne przy imporcie: produkty, odmiany, kategorie, klienci, stany magazynowe i ceny. Przy eksporcie: produkty, kategorie, klienci, zamówienia.

2. Źródło

Wskaż, skąd pochodzi plik (import) albo gdzie zapisać wynik (eksport): ręczne wgranie, URL (HTTP/HTTPS), FTP, SFTP albo ścieżka lokalna. Przy FTP i SFTP podaj host, port, użytkownika i hasło, a następnie użyj przycisku Testuj połączenie, aby zweryfikować dane przed zapisem.

3. Wizualne mapowanie

Wczytaj przykładowy plik (albo pobierz go ze zdalnego źródła): moduł wykrywa kolumny, pokazuje podgląd pierwszych wierszy i automatycznie przypisuje każdą kolumnę do właściwego pola PrestaShop dzięki rozpoznawaniu francusko-angielskiemu (référence/SKU, prix/price, quantité/stock, EAN/gencod, TVA/VAT i tak dalej). Popraw przypisania w tabeli; każda kolumna pozostawiona jako „niezmapowana” jest po prostu pomijana.

4. Opcje i harmonogram

Określ zachowanie importu: tworzenie brakujących elementów, aktualizacja istniejących, tworzenie kategorii w locie, pobieranie zdjęć z adresów URL, zastępowanie lub zachowywanie istniejących zdjęć przy aktualizacji oraz rozmiar partii (wiersze przetwarzane w jednym wywołaniu AJAX). Opcjonalnie włącz harmonogram i wybierz częstotliwość (godzinowa, dzienna albo tygodniowa). Zapisz: profil pojawi się na liście, gotowy do uruchomienia lub zaplanowania.

Formaty kolumn

Moduł rozumie formaty biznesowe PrestaShop. Oto konwencje oczekiwane w Twoich plikach:

Odmiany

Kolumna atrybutów ma format Grupa:Wartość|Grupa:Wartość. Brakujące grupy i wartości atrybutów są tworzone automatycznie, a odmiana jest identyfikowana przez swój dokładny zestaw atrybutów, więc ponowne uruchomienie importu nie tworzy duplikatu. Produkt nadrzędny jest odnajdywany po referencji lub ID, zależnie od klucza dopasowania.

Cechy

Użyj formatu Nazwa:Wartość|Nazwa:Wartość. Każda cecha i jej wartość są tworzone, jeśli jeszcze nie istnieją.

Kategorie, zdjęcia i tagi

Te pola przyjmują wiele wartości rozdzielonych separatorem wielu wartości zdefiniowanym w profilu. W kategoriach możesz mieszać nazwy i ID; pierwsze wymienione zdjęcie służy jako główne.

Źródła zdalne i bezpieczeństwo

Przy imporcie moduł pobiera plik z adresu URL (HTTP/HTTPS, w razie potrzeby z uwierzytelnianiem basic), serwera FTP (tryb pasywny lub aktywny), serwera SFTP albo ze ścieżki lokalnej ograniczonej do katalogu sklepu. Przy eksporcie może umieścić wygenerowany plik na FTP/SFTP albo w katalogu lokalnym, lub udostępnić go do pobrania.

Hasła FTP i SFTP są szyfrowane w bazie danych (AES-256-CBC, klucz wyprowadzony z klucza szyfrowania Twojego sklepu) i nigdy nie są zwracane do przeglądarki w postaci jawnej.

Import partiami i wznawianie

Importy ręczne odbywają się kolejnymi partiami w AJAX, z paskiem postępu i licznikami w czasie rzeczywistym (OK / błędy / razem). Po każdej partii zapamiętywana jest dokładna pozycja: plik liczący kilkadziesiąt tysięcy wierszy importuje się bez wywołania timeoutu PHP, nawet na hostingu współdzielonym. W trybie cron przetwarzanie przebiega synchronicznie aż do ostatniego wiersza.

Eksport

Utwórz profil eksportu, wybierając encję (produkty, kategorie, klienci, zamówienia), format (CSV lub XML) i pola do uwzględnienia. Wygenerowany plik jest udostępniany do natychmiastowego pobrania i (lub) automatycznie umieszczany w skonfigurowanym miejscu docelowym. Eksporty są generowane partiami, aby zachować wydajność przy dużych wolumenach.

Harmonogram (cron)

Aby zautomatyzować profil, włącz jego harmonogram (krok 4), a następnie wywołuj adres URL crona modułu w regularnych odstępach. Przy każdym wywołaniu uruchamiane są wyłącznie profile, których częstotliwość upłynęła.

*/15 * * * * curl -s "https://twoj-sklep.pl/index.php?fc=module&module=dfcsvpro&controller=cron&token=TWOJ_TOKEN" > /dev/null

Dokładny adres URL i token znajdziesz w zakładce Scheduling / Cron modułu, wraz z przyciskiem do wygenerowania nowego tokenu. Dwa opcjonalne parametry:

• &id_profile=N: uruchamia wyłącznie wskazany profil.
• &force=1: pomija sprawdzenie częstotliwości i uruchamia profil natychmiast.

Dzienniki i alerty e-mail

Każde uruchomienie trafia do dziennika wraz ze statusem, licznikami i szczegółami błędów wiersz po wierszu (pierwsze 200). Zakładka Logi pokazuje historię i pozwala przejrzeć błędy danego importu. Gdy tylko import zakończy się niepowodzeniem lub zawiera błędne wiersze, na adres skonfigurowany w ustawieniach wysyłany jest automatycznie alert e-mail (szablon francuski lub angielski).

Ustawienia

W zakładce Ustawienia włączasz lub wyłączasz alerty e-mail, ustawiasz adres odbiorcy, domyślny rozmiar partii oraz czas przechowywania dzienników (starsze wpisy są usuwane automatycznie). Tymczasowe pliki importu i eksportu są czyszczone po 48 godzinach.

Format XML

Przy imporcie XML powtarzający się węzeł elementu jest wykrywany automatycznie (albo wskazany w profilu). Elementy są spłaszczane: zagnieżdżone węzły stają się kolumnami rodzic/dziecko, atrybuty stają się @atrybut, a powtórzone elementy otrzymują sufiksy nazwa#1, nazwa#2. Tak spłaszczone kolumny mapujesz następnie tak samo jak w CSV.

Zgodność i uwagi techniczne

• Zgodny z PrestaShop 8.0 do 9.x, PHP 7.4 do 8.3, tryb wielosklepowy.
• CSV: automatyczne wykrywanie separatora, obsługa BOM, konwersja kodowań ISO-8859-1 i Windows-1252.
• Klienci importowani z hasłem haszowanym w bcrypt i przypisywani do grupy po nazwie.
• Brak override rdzenia; legacy AJAX korzysta z konwencji PS9.

Rozwiązywanie problemów

Interfejs modułu pozostaje pusty albo listy rozwijane się nie wypełniają. Wyczyść pamięć podręczną PrestaShop, a następnie wymuś przeładowanie przeglądarki (Ctrl+Shift+R). Jeśli aktywny jest menedżer pamięci podręcznej lub CCC, wygeneruj zasoby ponownie.

SFTP kończy się niepowodzeniem. Sprawdź, czy rozszerzenie PHP ssh2 jest zainstalowane na serwerze; w przeciwnym razie użyj FTP lub adresu URL.

Cron się nie uruchamia. Sprawdź token, upewnij się, że sklep nie jest w trybie konserwacji, oraz że profil ma włączony harmonogram i automatyczne źródło (profili z ręcznym wgraniem nie da się zaplanować).

Część wierszy jest błędna. Otwórz szczegóły dziennika: każdy błąd wskazuje numer wiersza i przyczynę (brak kolumny klucza, nieprawidłowa wartość i tak dalej).