Import i eksport danych w Magento 2

Magento ma natywne narzędzia do masowego importu i eksportu danych - Products, Customers, Stock Sources, Customer Addresses, Advanced Pricing, Tax Rates. Wszystko przez CSV. Ten poradnik pokazuje, jak ich używać i kiedy sięgnąć po moduły zewnętrzne.

System > Import - natywny import

Ścieżka: System > Data Transfer > Import

Wybór encji

Encje (Entity Type), które można importować:

Encja	Opis
Products	Produkty - wszystkie typy (simple, configurable, virtual, ...).
Customers and Addresses (single file)	Klienci wraz z adresami w jednym CSV.
Customers Main File	Klienci (bez adresów).
Customer Addresses	Adresy klientów.
Customer Finances	Saldo klienta (Commerce).
Advanced Pricing	Ceny tieryczne, ceny per Customer Group.
Stock Sources (MSI)	Stany magazynowe per source (MSI).
Tax Rates	Stawki podatkowe.

Import Behavior

Kluczowa decyzja przy każdym imporcie:

Behavior	Działanie
Add/Update	Dodaje nowe, aktualizuje istniejące po kluczu (SKU / email).
Replace	Usuwa istniejące i tworzy od nowa. Niebezpieczne dla produkcji.
Delete	Usuwa rekordy wymienione w CSV.
Custom Action	Tylko dla niektórych encji - pozwala wybrać sposób per kolumna.

Replace = usuwa dane: Behavior Replace dla produktów usuwa wszystkie dane produktu (zdjęcia, opisy, atrybuty) i tworzy go od nowa z CSV. Powiązania z kategoriami, atrybutami i opcjami giną.

W praktyce na produkcji używaj Add/Update - to bezpieczna opcja.

Pełny flow importu

System > Data Transfer > Import.
Wybierz Entity Type (np. Products).
Wybierz Import Behavior (zwykle Add/Update).
Validation Strategy - wybierz Stop on Error lub Skip Error Entries.
Allowed Errors Count - ile błędów może wystąpić zanim Magento przerwie (domyślnie 10).
Field separator - , (przecinek).
Multiple value separator - , (dla wielowartościowych pól).
Empty attribute value constant - __EMPTY__VALUE__ (tekstowa wartość oznaczająca "wyczyść atrybut").
Fields enclosure - " (cudzysłów).
Wgraj plik CSV (uwaga: limit serwera, zwykle upload_max_filesize).
Kliknij Check Data - Magento waliduje plik bez wprowadzania zmian.
Jeśli walidacja przeszła → Import.

Walidacja

Check Data zwraca raport:

Checked rows: X, Checked entities: Y, Invalid rows: Z, Total errors: N
Lista konkretnych błędów z numerem wiersza i kolumny.

Najczęstsze błędy:

"SKU is empty" - brakuje kluczowej kolumny.
"Invalid value for attribute" - wartość nie pasuje do typu atrybutu.
"Attribute not found" - kolumna w CSV której Magento nie zna.
"Encoding" - plik nie jest UTF-8.

System > Export - natywny eksport

Ścieżka: System > Data Transfer > Export

Wybór encji

Te same encje co przy imporcie. Eksport zwraca CSV z aktualnym stanem bazy.

Filtr eksportu

W formularzu eksportu możesz filtrować dane:

Per Store View (np. eksport tylko sklepu PL).
Per Attribute Set (np. tylko produkty z AS "Clothes").
Per Status (Enabled / Disabled).
Custom filters - można odznaczyć kolumny których nie chcesz eksportować.

Kliknij Continue - Magento wygeneruje CSV i zaproponuje pobranie.

Małe vs duże eksporty: Natywny eksport działa synchronicznie - przy 100k+ SKU może timeoutować w przeglądarce. Dla bardzo dużych eksportów użyj:

ecomhouse-exporter - asynchroniczny eksport przez consumery.

CLI: niektóre encje można eksportować bezpośrednio z bazy (SELECT ... INTO OUTFILE).

Format CSV - kluczowe zasady

Encoding

Zawsze UTF-8 bez BOM. Excel domyślnie zapisuje UTF-8 z BOM, co psuje pierwszą kolumnę.

Konwersja Excel → UTF-8 bez BOM:

LibreOffice Calc - Save As → CSV → Edit Filter Settings → Character Set: UTF-8 → uncheck "Add BOM".
Python: pandas.read_csv(...).to_csv(out, encoding="utf-8").
VS Code - Save with Encoding → UTF-8 (without BOM).

Separator

Magento natywnie używa przecinka. Niektóre kolumny (multiselect) używają wewnętrznego separatora - domyślnie przecinka, ale można zmienić w formularzu importu na | żeby uniknąć konfliktów.

Pola wielowartościowe

Multiselect / multi-store-view → wartości oddzielone separatorem multi-value:

sku,categories
PROD-001,"Default Category,Electronics,Smartphones"

Cudzysłów

Jeśli wartość zawiera przecinek, otocz ją cudzysłowem:

sku,description
PROD-001,"Telefon, smartfon, gadget"

Pusta wartość vs wyczyść atrybut

Pusta kolumna w CSV → Magento ignoruje to pole, atrybut zostaje bez zmian.
Wartość __EMPTY__VALUE__ → Magento wyczyści atrybut.

Sample files

Magento dostarcza wzory CSV dla każdej encji:

System > Data Transfer > Import > Download Sample File (przycisk po wyborze Entity Type).

Wzór zawiera:

Wszystkie obsługiwane kolumny.
Przykładowe wartości.
Komentarze (gdzie są wskazówki).

Zawsze zaczynaj od wzoru - nie buduj CSV od zera.

Typowe scenariusze

Scenariusz 1: Import 5000 nowych produktów

Pobierz sample file dla Products.
Wypełnij dane (SKU, name, price, attribute_set_code, type_id, etc).
Validation Strategy = Skip Error Entries.
Check Data → poprawiaj błędy iteracyjnie aż walidacja przejdzie czysto.
Import.

Reindex + cache flush:

bin/magento indexer:reindex
bin/magento cache:flush

Scenariusz 2: Update cen 50000 produktów

Natywny import - Behavior = Add/Update, CSV tylko z kolumnami sku i price.

Dla bardzo dużych zmian (>100k SKU) - patrz ecomhouse-qtyfastupdate (specjalizowany dla qty, podobnie można zrobić dla price).

Scenariusz 3: Migracja klientów ze starego sklepu

Eksport ze starego sklepu → CSV.
Customers and Addresses (single file) w Magento - najwygodniejsze.
Wymagane kolumny: email, _website, firstname, lastname.
Behavior = Add/Update.

Hasła klientów: Magento nie umie zaimportować zahashowanych haseł ze starego systemu (różne algorytmy). Po imporcie klienci muszą zresetować hasło (link "Forgot Password") przy pierwszym logowaniu.

Można importować klientów z password_hash natywnym Magento (bcrypt) - ale wtedy musisz wcześniej rehashować całą bazę.

Scenariusz 4: Eksport produktów do hurtowni / marketplace

System > Data Transfer > Export > Products.
Zaznacz kolumny które chcesz eksportować.
Filtr per attribute_set_code jeśli chcesz tylko określoną grupę.
Continue → pobierz CSV.

Dla cyklicznych eksportów (raz dziennie) - patrz ecomhouse-exporter.

Scenariusz 5: Import setek plików CSV

Natywny import obsługuje jeden plik na raz. Dla wielu plików:

ecomhouse-importqueue - masowy import wszystkich CSV z katalogu przez CLI.

Najczęstsze problemy

"File is large. Allowed file size is X MB"

Limit upload_max_filesize PHP. Edycja php.ini:

upload_max_filesize = 256M
post_max_size = 256M
memory_limit = 1024M
max_execution_time = 1800
max_input_time = 1800

Restart PHP-FPM. Lub: importuj plik CLI zamiast przez panel (omija limity HTTP).

"Invalid value in 'attribute_set_code' field"

Wartość w CSV musi pasować do dokładnej nazwy Attribute Set (case-sensitive). Sprawdź dostępne:

Stores > Attributes > Attribute Set - kolumna Name (nie ID).

Pola Page Builder / opis HTML rozsypują się po imporcie

Problem z encodingiem cudzysłowów / przecinków w HTML. Zalecane:

Otaczaj wartości cudzysłowem.
Cudzysłowy w wartości escapuj podwojeniem: ""tekst"".
Zachowaj całość HTML w jednym wierszu (bez \n) - niektóre wersje Excel rozdzielają wieloliniowe komórki.

"Url key for specified store already exists"

Dwa produkty mają ten sam url_key. Magento nie pozwala. Rozwiązania:

Wymuś unikalność w CSV (np. dodać SKU do url_key).
Lub: w Stores > Configuration > Catalog > Catalog > Search Engine Optimization > Use Categories Path for Product URLs = Yes.

Wszystkie wiersze pomijane mimo czystej walidacji

Sprawdź encoding (UTF-8 bez BOM) i separator (, nie ;).

Import trwa godzinami i nie kończy się

Set indexers to schedule mode przed importem:
```
bin/magento indexer:set-mode schedule
```

Wyłącz Catalog Search reindex w trakcie:

bin/magento indexer:set-mode schedule catalogsearch_fulltext

Rozważ podział pliku na mniejsze (5000-10000 wierszy / plik) + ecomhouse-importqueue.

CLI alternatywa

Natywny Magento ma CLI dla importu (Magento 2.4+):

bin/magento import:products /path/to/products.csv

Ograniczone do produktów, ale szybsze i bez limitów HTTP.

Powiązane

Cache i indeksery - po dużych importach reindex jest kluczowy
Magento Cron - async imports / queue consumers