Przejdź do treści

Jak przygotować plik CSV do importu produktów?

Dobry import zaczyna się przed kliknięciem „Wgraj plik”. CSV musi jednoznacznie opisywać produkt, wariant, cenę, stan, kategorię i zdjęcia. Jeden źle zapisany separator, EAN potraktowany jako liczba albo powtórzone SKU potrafią utworzyć duplikaty, zgubić warianty lub nadpisać istniejące dane.

Jeden wiersz = jeden wariant

wzor-importu-produktow-utf8.csvwzór pliku
skuvariant_groupcolorsize
TSHIRT-001-BLK-STSHIRT-001CzarnyS
TSHIRT-001-BLK-MTSHIRT-001CzarnyM
TSHIRT-001-WHT-MTSHIRT-001BiałyM
Każdy wariant ma własne SKU, EAN i stan; zaznaczona kolumna variant_group łączy warianty w jedną kartę produktu. Pełne wiersze i plik do pobrania – pod wstępem.
Plik jest specyfikacją, nie tylko tabelą

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.

Wzór pliku i pierwszy wybór

sku;ean;name;price_gross;stock;category;variant_group;color;size;image_url
TSHIRT-001-BLK-S;5901234567807;Koszulka techniczna;129.90;8;Odzież > Koszulki;TSHIRT-001;Czarny;S;https://example.com/images/tshirt-black.jpg
TSHIRT-001-BLK-M;5901234567814;Koszulka techniczna;129.90;14;Odzież > Koszulki;TSHIRT-001;Czarny;M;https://example.com/images/tshirt-black.jpg
TSHIRT-001-WHT-M;5901234567821;Koszulka techniczna;129.90;3;Odzież > Koszulki;TSHIRT-001;Biały;M;https://example.com/images/tshirt-white.jpg
Wiersze z pliku wzoru: jeden wiersz = jeden wariant, każdy z własnym SKU, EAN i stanem. Niebieskie – kolumna variant_group, która łączy warianty w jedną kartę produktu; żółte – EAN zapisany jako tekst.

Wzór zawiera nagłówki z tabeli kolumn poniż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)

Minimalny zestaw kolumn

sku, ean, name, price_gross, stock, category, variant_group, color, size, image_url – przeznaczenie i przykład

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. Gotowy proces dla tej platformy opisuje import produktów CSV/XML do Shopera.

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.

Minimalny zestaw kolumn pliku importu
KolumnaPrzeznaczeniePrzykład
skuwewnętrzny identyfikator rekorduTSHIRT-001-BLK-M
eankod handlowy wariantu5901234567890
namenazwa produktuKoszulka techniczna
price_grosscena brutto129.90
stockdostępna ilość14
categorydocelowa kategoria lub ścieżkaOdzież > Koszulki
variant_groupidentyfikator rodziny wariantówTSHIRT-001
colorwartość wariantuCzarny
sizewartość wariantuM
image_urladres głównego zdjęciahttps://…/tshirt-black.jpg
Wiersz = produktProsty katalog bez wariantów

Każdy produkt ma jeden rekord. Reguła i model mieszany – sekcja 01.

Wiersz = wariantRodzina z rozmiarami lub kolorami

Wspólny variant_group albo parent_sku, własne SKU, EAN i stan wariantu – sekcja 02.

Przed importem sprawdź

Jeden wiersz

co reprezentuje jeden wiersz: produkt, wariant czy rekord niezależny

Sekcja 01

Separatory

separator kolumn, separator dziesiętny i znak otaczający tekst

Sekcja 03

Kodowanie i identyfikatory

kodowanie UTF-8 oraz SKU i EAN przechowywane jako tekst

Sekcja 04

Pusta komórka

znaczenie pustej komórki: brak zmiany, wyczyszczenie czy błąd

Sekcja 05
Objaw po imporcie
  • Katalog ma dublety, część wariantów została utworzona jako osobne produkty, a EAN-y skróciły się o początkowe zero — albo stary rekord sprzed wariantów zostaje wariantem domyślnym i listing pokazuje 1,99 zł (patrz wariant domyślny w Shoperze po imporcie z BaseLinkera).
Pierwszy test
  • Otwórz plik w edytorze tekstu, nie w arkuszu.
  • Sprawdź kodowanie, separator, cudzysłowy i to, czy identyfikatory nie zmieniły się w liczby.
01

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.

W sklepie z ok. 22 tys. produktów i ok. 168 tys. wariantów sam eksport wariantów to ok. 168 tys. wierszy; pełny plik może mieć ich więcej, jeśli zawiera też produkty bez wariantów albo osobne wiersze produktów nadrzędnych – zależnie od ustalonego formatu. Taki plik trzeba dzielić na partie i importować z raportem po każdej.

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.

Duży katalog w jednym pliku

produktów w sklepie
ok. 22 tys.
wierszy w samym eksporcie wariantów
ok. 168 tys.
Taki plik trzeba dzielić na partie i importować z raportem po każdej.
02

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 raz granat, raz navy

Rodzina wariantowa w pliku

wzor-importu-produktow-utf8.csvwzór pliku
skuvariant_groupcolorsizestockWynik
TSHIRT-001-BLK-STSHIRT-001CzarnyS8wariant
TSHIRT-001-BLK-MTSHIRT-001CzarnyM14wariant
TSHIRT-001-WHT-MTSHIRT-001BiałyM3wariant
Te same trzy warianty co we wzorze na początku poradnika: wspólny variant_group, własne SKU i stan, żadna kombinacja koloru i rozmiaru się nie powtarza.
03

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ł”.

Specyfikacja pliku: co zapisać
UstawienieWartość
separator kolumnśrednik albo przecinek
separator dziesiętnykropka albo przecinek
znak otaczający tekstzwykle cudzysłów
nowe linie w opisiesposób zapisu nowych linii w opisie
kodowanieUTF-8, najlepiej opisane w specyfikacji importu
04

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. W plikach od producentów trafiliśmy na EAN „5710000000000” w każdym wierszu (błąd u źródła, nie Excela) oraz numery w postaci „1,28101E+11” po zapisie arkusza.

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.

Tekst

0123456789012

Po zamianie na liczbę

123456789012 albo zapis typu 5,90123E+12

  • 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
SKU

Identyfikuje rekord w procesie firmy. Powinien być stabilny, bo zwykle służy do aktualizacji istniejącego produktu.

EAN

Identyfikuje jednostkę handlową. Przydaje się do matchingu z hurtownią i marketplace, ale nie zastępuje SKU.

05

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.

sku;ean;name;price_gross;stock
TSHIRT-001-BLK-M;5901234567814;Koszulka techniczna;;14
Pusta komórka price_gross w pliku aktualizacji. Bez specyfikacji importu nie wiadomo, którą z trzech intencji oznacza.

Co znaczy pusta komórka price_gross?

  1. intencja 1Nie zmieniajRekord istnieje, ale to pole ma zostać bez zmian. Najczęstsza intencja przy aktualizacji częściowej.
  2. intencja 2WyczyśćWartość ma zostać usunięta. Groźne przy opisach, kategoriach, cenie i stanie.
  3. intencja 3Błąd rekorduPole jest wymagane, więc rekord nie powinien zostać zapisany w ogóle.
06

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.

pole wielowartościoweprzykład
sku;image_urlTSHIRT-001-BLK-M;https://…/tshirt-black.jpg|https://…/tshirt-white.jpgśrednik rozdziela kolumny, znak | rozdziela zdjęcia w jednej komórce
  • 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
07

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.

Pierwsze uruchomienie to dry-run

  1. bez zapisuAnaliza plikusystem generuje raport, ale nie zapisuje produktów
  2. decyzjaAkceptacja raportublokada zapisu przy błędzie krytycznym
  3. zapisKatalogutworzenie lub aktualizacja produktów

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
08

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.

  1. Próbka20–50 rekordów
  2. Walidacjai raport
  3. Import testowyna kopii lub do środowiska testowego
  4. Kontrolawariantów, cen, stanów i zdjęć
  5. Pełna partiai raport różnic po zapisie

FAQ: przygotowanie pliku CSV

Oba formaty mogą działać. Separator musi być jednoznacznie ustalony i nie może kolidować z wartościami w polach. W polskich plikach często stosuje się średnik, bo przecinek występuje w liczbach dziesiętnych.
Arkusz może potraktować go jak liczbę, usunąć zera na początku albo użyć zapisu naukowego. Kolumnę EAN należy importować i przechowywać jako tekst, a przed eksportem sprawdzić, czy żaden kod nie ma postaci typu 5,90123E+12.
Tak, każdy sprzedawany wariant (rozmiar, kolor, pojemność). Wyjątkiem są tylko atrybuty, które nie tworzą wariantu, np. materiał czy sezon. Wspólny identyfikator rodziny powinien znajdować się w oddzielnej kolumnie, na przykład variant_group, i nie służyć jako identyfikator sprzedawanego rekordu.
Nie powinno się tego zakładać. Puste pole może znaczyć „nie zmieniaj”, „wyczyść” albo „rekord jest błędny”. Znaczenie musi być określone dla każdej kolumny w specyfikacji importu.

Import tysięcy produktów bez poprawiania po fakcie

Sprawdzimy plik, zmapujemy kolumny, zrobimy import testowy i dopiero potem pełną partię z raportem różnic. Warianty, ceny i zdjęcia trafiają do sklepu po kontroli, a nie do ręcznej poprawki po imporcie.

Podobna realizacja10 018 nazw produktów zapisanych przez API w ok. 65 minSportina · Shoper