Importer nie zgaduje intencji. Jeżeli w pliku nie widać, który wiersz jest wariantem, po czym rozpoznać istniejący produkt i co znaczy pusta komórka, każda z tych decyzji zostanie podjęta przypadkowo.
Katalog ma dublety, część wariantów została utworzona jako osobne produkty, a EAN-y skróciły się o początkowe zero.
Otwórz plik w edytorze tekstu, nie w arkuszu. Sprawdź kodowanie, separator, cudzysłowy i to, czy identyfikatory nie zmieniły się w liczby.
Wzór zawiera nagłówki z tabeli powyżej, jedną rodzinę wariantową i poprawnie zapisany EAN. Otwórz go w edytorze tekstu, żeby zobaczyć separator i cudzysłowy.
Pobierz przykładowy plik CSV (UTF-8)Najpierw ustal, co reprezentuje jeden wiersz
Najważniejsza decyzja brzmi: czy jeden wiersz opisuje produkt główny, wariant, czy niezależny produkt bez wariantów. Bez tej reguły nie da się jednoznacznie zinterpretować kolumn takich jak rozmiar, kolor, SKU, stan i cena.
Dla prostego katalogu jeden wiersz może oznaczać jeden produkt. Przy wariantach jeden wiersz powinien zwykle oznaczać jeden wariant, a osobna kolumna variant_group albo parent_sku łączyć go z rodziną produktu. Dzięki temu rozmiar M i L mogą mieć własne SKU, EAN i stany, ale pozostają jedną kartą produktu.
Nie mieszaj dwóch modeli w jednym pliku. Jeżeli część wierszy opisuje produkt nadrzędny, a część wariant, trzeba jasno rozróżnić ich typ, na przykład przez kolumnę record_type z wartościami parent i variant.
Minimalny zestaw kolumn
Nie istnieje jeden uniwersalny format dla wszystkich platform, ale bezpieczny plik roboczy powinien zawierać co najmniej poniższy zestaw. W praktyce dochodzą kolumny opisów, producenta, stawki VAT, ceny promocyjnej, wagi, parametrów, dodatkowych zdjęć i statusu publikacji.
Nie dodawaj jednak pól „na zapas”. Każda kolumna powinna mieć właściciela, regułę walidacji i docelowe pole w sklepie. Kolumna, której nikt nie mapuje, zwykle kończy jako źródło nieporozumień przy kolejnym imporcie.
| Kolumna | Przeznaczenie | Przykład |
|---|---|---|
sku | wewnętrzny identyfikator rekordu | TSHIRT-001-BLK-M |
ean | kod handlowy wariantu | 5901234567890 |
name | nazwa produktu | Koszulka techniczna |
price_gross | cena brutto | 129.90 |
stock | dostępna ilość | 14 |
category | docelowa kategoria lub ścieżka | Odzież > Koszulki |
variant_group | identyfikator rodziny wariantów | TSHIRT-001 |
color | wartość wariantu | Czarny |
size | wartość wariantu | M |
image_url | adres głównego zdjęcia | https://…/tshirt-black.jpg |
Separator, kodowanie i znaki specjalne
Najbezpieczniejszym kodowaniem dla polskich danych jest UTF-8. Dzięki temu nazwy, kategorie i opisy nie tracą znaków takich jak ą, ę, ł czy ż.
W polskich plikach często używa się średnika, ponieważ przecinek występuje w liczbach dziesiętnych. Integrator musi jednak wiedzieć, jaki separator przyjął plik. Nie należy zgadywać separatora po pierwszym wierszu, jeżeli wartości mogą zawierać przecinki lub średniki w opisach.
Jeżeli opis zawiera separator, pole powinno być poprawnie ujęte w cudzysłów. Nie usuwaj znaków z tekstu tylko po to, żeby plik „się otworzył”.
- separator kolumn: średnik albo przecinek
- separator dziesiętny: kropka albo przecinek
- znak otaczający tekst: zwykle cudzysłów
- sposób zapisu nowych linii w opisie
- kodowanie UTF-8, najlepiej opisane w specyfikacji importu
SKU i EAN muszą pozostać tekstem
Excel i inne arkusze potrafią automatycznie zamieniać długie identyfikatory na liczbę, zapis naukowy albo wartość bez początkowego zera. Dla danych produktowych jest to ryzyko, ponieważ 0123456789012 i 123456789012 nie są tym samym kodem.
Kolumny sku i ean traktuj jako tekst. Nie wykonuj na nich działań matematycznych. Szerzej o roli obu identyfikatorów piszemy w poradniku o polityce identyfikatorów w integracjach.
- czy żaden EAN nie ma zapisu typu
5,90123E+12 - czy nie zniknęły zera na początku
- czy SKU nie zostały skrócone
- czy nie ma spacji na początku lub końcu
- czy jeden identyfikator nie występuje w kilku rekordach bez uzasadnienia
Identyfikuje rekord w procesie firmy. Powinien być stabilny, bo zwykle służy do aktualizacji istniejącego produktu.
Identyfikuje jednostkę handlową. Przydaje się do matchingu z hurtownią i marketplace, ale nie zastępuje SKU.
Jak zapisać warianty
Warianty wymagają wspólnego identyfikatora rodziny. Każdy wariant ma własne SKU, a zwykle również własny EAN i stan. variant_group nie jest sprzedawanym rekordem — służy do zgrupowania wariantów w jedną kartę produktu.
- nie ma dwóch wariantów z tą samą kombinacją koloru i rozmiaru
- każdy wariant ma własne SKU
- grupa nie łączy przypadkowo różnych modeli
- wartości atrybutów są zapisane konsekwentnie:
Granatowy, a nie razgranat, raznavy
| sku | variant_group | color | size | stock |
|---|---|---|---|---|
TSHIRT-001-BLK-S | TSHIRT-001 | Czarny | S | 8 |
TSHIRT-001-BLK-M | TSHIRT-001 | Czarny | M | 14 |
TSHIRT-001-WHT-M | TSHIRT-001 | Biały | M | 3 |
Kategorie, zdjęcia i pola wielowartościowe
Kategorie w pliku powinny odpowiadać docelowej strukturze sklepu albo przejść przez mapowanie. Nie kopiuj bez kontroli drzewa kategorii z hurtowni. Nazwy techniczne dostawcy często nie odpowiadają sposobowi, w jaki klient szuka produktów.
Pola wielowartościowe, na przykład lista zdjęć lub tagów, muszą mieć osobny separator, który nie koliduje z separatorem CSV. Dobrym rozwiązaniem jest znak |, o ile nie występuje w danych.
- czy podajesz URL, nazwę pliku czy ścieżkę do archiwum
- które zdjęcie jest główne
- jak rozdzielane są dodatkowe zdjęcia
- co zrobić, gdy URL nie odpowiada albo plik jest uszkodzony
- czy zdjęcie dotyczy całej rodziny, czy konkretnego wariantu koloru
Nie używaj pustej wartości jako polecenia bez specyfikacji
Puste pole może znaczyć trzy różne rzeczy i każda z nich prowadzi do innego wyniku w katalogu.
Rekord istnieje, ale to pole ma zostać bez zmian. Najczęstsza intencja przy aktualizacji częściowej.
Wartość ma zostać usunięta. Groźne przy opisach, kategoriach, cenie i stanie.
Pole jest wymagane, więc rekord nie powinien zostać zapisany w ogóle.
Walidacja przed importem
Przed przekazaniem pliku do sklepu uruchom kontrolę, która sprawdzi kompletność i spójność danych. Pierwsze uruchomienie powinno być dry-runem: system analizuje plik i generuje raport, ale nie zapisuje produktów. Dopiero po akceptacji raportu można utworzyć lub zaktualizować katalog.
Tę część procesu realizujemy w ramach walidacji danych produktowych — z regułami, poziomami błędów i blokadą zapisu przy błędzie krytycznym.
- obowiązkowe kolumny i duplikaty SKU oraz EAN
- poprawność cen i stanów, puste nazwy
- nieznane kategorie i błędne grupy wariantowe
- brakujące zdjęcia i nieprawidłowe kodowanie
- liczba rekordów przed i po odrzuceniu błędów
Gotowy plik nie oznacza gotowego importu
Poprawny CSV rozwiązuje problem formatu, ale nadal trzeba ustalić mapowanie pól, politykę aktualizacji, backup, testową partię i raport po imporcie. Jeżeli plik ma aktualizować istniejący katalog, krytyczne jest ustalenie, po czym system rozpoznaje produkt oraz których pól nie wolno nadpisywać.
Cały proces importu — z backupem, dry-runem i raportem różnic — opisuje checklista importu produktów CSV/XML.
- próbka 20–50 rekordów
- walidacja i raport
- import na kopii lub do środowiska testowego
- kontrola wariantów, cen, stanów i zdjęć
- pełna partia i raport różnic po zapisie