← Wróć do bloga
9 min czytania

Import produktów z CSV i XML do systemu sprzedaży — praktyczny poradnik

oms

Import produktów brzmi jak jednorazowa formalność: wrzucasz plik, klikasz „importuj“ i po sprawie. W praktyce to właśnie na tym etapie powstaje większość późniejszego bałaganu — zdublowane pozycje, rozjechane warianty, „krzaki“ zamiast polskich znaków i stany, które od początku się nie zgadzają. Dobry import to nie kwestia szczęścia, tylko przygotowania pliku i mapowania pól.

W tym poradniku przechodzimy przez cały proces po kolei: jak zbudować plik CSV lub XML, jak zmapować kolumny na pola systemu, jak nie utopić się w wariantach i kodowaniu oraz jak robić aktualizacje przyrostowe, żeby import nie był jednorazowym strzałem, tylko powtarzalnym procesem. Na końcu — najczęstsze błędy i jak ich uniknąć.

CSV czy XML — który format wybrać

Oba formaty świetnie nadają się do importu produktów, ale mają inne mocne strony:

  • CSV to płaska tabela: wiersz = produkt, kolumny = pola. Prosty, lekki, otwiera się w arkuszu, łatwo go ręcznie poprawić. Sprawdza się dla katalogów o prostej strukturze, gdzie każdy produkt ma ten sam zestaw pól.
  • XML to struktura zagnieżdżona: pozwala naturalnie opisać produkt z wieloma wariantami, wieloma zdjęciami czy cechami o zmiennej liczbie wartości. Bywa też formatem, w którym hurtownie udostępniają swoje feedy.

Zasada praktyczna: jeśli Twój katalog da się sensownie ułożyć w płaską tabelę — wybierz CSV, bo jest najłatwiejszy do kontroli. Jeśli masz rozbudowane warianty i cechy albo dostajesz gotowy feed od dostawcy — XML będzie wygodniejszy. Format ma znaczenie mniejsze niż jakość danych w środku, więc nie przywiązuj się do niego bardziej niż do porządku w kolumnach.

Przygotowanie pliku — fundament całego importu

Zanim cokolwiek zaimportujesz, uporządkuj źródło. To etap, który decyduje o powodzeniu:

  1. Jedna pozycja = jeden wiersz (lub jeden węzeł). Nie sklejaj dwóch produktów w jednej linii i nie rozbijaj jednego na kilka bez powodu.
  2. Nagłówki kolumn nazwij jednoznacznie — sku, nazwa, cena_brutto, stan, a nie kolumna1, cena, cena2. Jasne nagłówki to połowa sukcesu przy mapowaniu.
  3. Ujednolić format liczb — jeden separator dziesiętny (kropka lub przecinek, konsekwentnie), bez spacji jako separatora tysięcy, ceny w jednej walucie.
  4. Oczyść dane — usuń zbędne spacje na końcach, puste wiersze, znaki sterujące wklejone z innego systemu. Ceny i stany muszą być liczbami, nie tekstem („12,00 zł“ to tekst).
  5. Ustal, co jest kluczem — w 99% przypadków będzie to SKU (o tym niżej). To on decyduje, czy import utworzy nowy produkt, czy zaktualizuje istniejący.

Dobry plik źródłowy to taki, który sam siebie tłumaczy: patrzysz na nagłówki i wiesz, co gdzie jest. Jeśli musisz zgadywać, co znaczy pole_7, import odziedziczy ten sam problem.

Mapowanie pól — gdzie import naprawdę się rozstrzyga

Mapowanie to przypisanie kolumn z Twojego pliku do pól w systemie sprzedaży. To najważniejszy i najczęściej niedoceniany krok. Minimalny zestaw pól, który warto zmapować:

  • SKU — unikalny identyfikator (klucz importu),
  • nazwa produktu,
  • cena (jednoznacznie: brutto czy netto),
  • stan magazynowy (liczba sztuk),
  • kod EAN/GTIN (jeśli masz — bywa potrzebny na marketplace),
  • opcjonalnie: opis, kategoria, zdjęcia (URL-e), waga, wymiary.

Kilka zasad, które ratują przed bólem:

  • Nie mapuj „na czuja“ — sprawdź na 2–3 wierszach, czy cena trafia do ceny, a nie do stanu.
  • Zdecyduj o brutto vs netto raz i trzymaj się tego w całym pliku.
  • Puste pole to nie zawsze zero — ustal, czy brak stanu ma oznaczać „0 sztuk“, czy „nie ruszaj tej wartości“. To dwie zupełnie różne intencje.
  • Zapisz mapowanie jako szablon, jeśli system to umożliwia — kolejny import z tego samego źródła pójdzie wtedy w kilka sekund.

SKU i warianty — sedno porządku w katalogu

SKU (Stock Keeping Unit) to unikalny kod pojedynczej, sprzedawalnej pozycji. To on jest wspólnym kluczem, po którym system rozpoznaje produkt przy imporcie, aktualizacji i łączeniu stanów między kanałami. Dlatego SKU musi być:

  • unikalne — żadnych dwóch pozycji o tym samym kodzie,
  • stałe — raz nadane, nie zmieniaj go później (zmiana SKU = w oczach systemu nowy produkt),
  • spójne między kanałami — ten sam produkt ma to samo SKU w sklepie, w feedzie i w OMS.

Przy wariantach (rozmiar, kolor, pojemność) obowiązuje żelazna zasada: każdy wariant to osobna pozycja z własnym SKU i własnym stanem. Produkt „T-shirt“ nie ma stanu — mają go warianty „T-shirt / M / czarny“ i „T-shirt / L / biały“. W CSV warianty układasz zwykle jako osobne wiersze z odwołaniem do wspólnego produktu nadrzędnego; w XML jako zagnieżdżone węzły. Jeśli policzysz stan na poziomie produktu zamiast wariantu, rozmiar M zejdzie do zera, a oferta wciąż pokaże dostępność — i sprzedasz to, czego nie masz. Więcej o liczeniu stanów na właściwym poziomie piszemy w poradniku o prostym systemie magazynowym dla sklepu.

Kodowanie znaków — cichy zabójca polskich liter

Jeśli po imporcie widzisz „łóżko“ zamiast „łóżko“, to problem kodowania. Reguła jest jedna: zapisuj i importuj pliki w UTF-8.

  • Zapisując CSV z Excela, wybierz „CSV UTF-8“ — zwykły „CSV (rozdzielany przecinkami)“ często zapisuje w Windows-1250 i psuje polskie znaki.
  • W XML trzymaj <?xml version="1.0" encoding="UTF-8"?> i realnie zapisz plik w UTF-8, a nie tylko zadeklaruj.
  • Uważaj na BOM — niewidoczny znacznik na początku pliku potrafi popsuć pierwszy nagłówek kolumny. Jeśli pierwsza kolumna „nie łapie się“ przy mapowaniu, to często właśnie BOM.
  • Ustal separator CSV — przecinek to standard, ale w polskim Excelu bywa średnik. Jeśli wszystko wpada do jednej kolumny, sprawdź separator w pierwszej kolejności.

Kodowanie to najczęstsza pojedyncza przyczyna „brzydkiego“ importu, a zarazem najłatwiejsza do uniknięcia — wystarczy raz ustawić UTF-8 i się go trzymać.

Walidacja i test na próbce — zanim wpuścisz cały katalog

Nigdy nie importuj 5000 pozycji „w ciemno“. Sprawdź plik, zanim wejdzie do systemu na dobre:

  • Import próbny na 10–20 wierszach — obejrzyj wynik oczami, zanim puścisz całość.
  • Waliduj klucze — brak SKU, duplikaty SKU, puste nazwy to najczęstsze powody odrzucenia wiersza.
  • Sprawdź typy — cena i stan muszą być liczbami; „brak“, „—“ czy „12 zł“ wywalą import.
  • Policz wiersze — liczba pozycji w pliku powinna zgadzać się z liczbą zaimportowanych (minus świadomie pominięte).
  • Zajrzyj do logu importu — dobry system pokaże, które wiersze przeszły, które odrzucił i dlaczego. To Twoja pierwsza pomoc przy poprawkach.

Dziesięć minut na import próbki oszczędza godziny czyszczenia katalogu, w którym ceny wpadły do pola stanu na pięciu tysiącach pozycji.

Aktualizacje przyrostowe — import to proces, nie jednorazowy strzał

Katalog żyje: zmieniają się ceny, stany, dochodzą nowe produkty. Dlatego traktuj import jako powtarzalny proces, a nie jednorazowe wgranie. Klucz do tego to aktualizacja przyrostowa (upsert) oparta na SKU:

  • istnieje SKU → system aktualizuje istniejący produkt (np. tylko cenę i stan),
  • nowe SKU → system tworzy nowy produkt,
  • brak SKU w pliku → zwykle zostaje bez zmian (chyba że świadomie robisz pełną synchronizację).

Dobra praktyka to węższe pliki do częstych zmian: osobny, lekki feed „SKU + cena + stan“ puszczany często, i pełny plik z opisami/zdjęciami rzadziej. Dzięki temu codzienna aktualizacja stanów jest szybka i bezpieczna, a bogate dane produktowe podmieniasz tylko, gdy trzeba. Jeśli źródłem jest stały feed dostawcy, warto go odświeżać cyklicznie zamiast wgrywać ręcznie za każdym razem.

Najczęstsze błędy przy imporcie

  • Zmiana SKU między importami — system potraktuje pozycję jako nową i zrobi duplikat.
  • Stan liczony na produkcie zamiast na wariancie — prosta droga do nadsprzedaży.
  • Cena jako tekst („99,00 zł“) — import odrzuci wiersz albo wczyta zero.
  • Zły separator lub kodowanie — cały plik w jednej kolumnie albo „krzaki“ zamiast polskich liter.
  • Puste pole rozumiane jako zero — niechcący wyzerujesz stany albo ceny, których nie chciałeś ruszać.
  • Import całości bez testu na próbce — błąd mnoży się przez tysiące wierszy, zanim go zauważysz.

Jak z importem radzi sobie Sellaro

Sellaro to OMS (system zarządzania zamówieniami i produktami), który zbiera produkty i warianty ze wszystkich podpiętych kanałów do jednego, znormalizowanego widoku — z podziałem na stan dostępny, niski i wyczerpany, spięty wspólnym SKU. Gotowe moduły sklepowe to dziś PrestaShop, Sylius i WooCommerce, a integracje działają read-only — Sellaro czyta i normalizuje dane, nie zapisuje do sklepu. Allegro i kolejne kanały są na roadmapie, a brakującą integrację dokładamy gratis w ramach pakietu.

Sellaro jest API-first (klucze API, eksport CSV, wyszukiwarka), więc produkty mogą wpadać nie tylko z podpiętych sklepów, ale też programowo — a silnik automatyzacji (WHEN→IF→THEN) pozwoli ustawić np. alert e-mail/SMS przy niskim stanie. Platforma jest w aktywnym rozwoju i piszemy o tym uczciwie: część funkcji importu bogatych feedów rozbudowujemy na życzenie. Jeśli chcesz zrozumieć samą kategorię, zacznij od tekstu czym jest OMS dla e-commerce.

Najczęstsze pytania

Czy lepszy jest CSV czy XML do importu produktów?

Do prostych katalogów wygodniejszy jest CSV — płaska tabela, łatwa do kontroli w arkuszu. Gdy masz rozbudowane warianty i cechy albo dostajesz gotowy feed od dostawcy, naturalniejszy jest XML. Ważniejsza od formatu jest jakość danych i spójne SKU.

Dlaczego po imporcie mam „krzaki“ zamiast polskich znaków?

To problem kodowania. Zapisuj i importuj pliki w UTF-8 — w Excelu wybierz „CSV UTF-8“, a w XML zadbaj o realny zapis w UTF-8, nie tylko deklarację. Uważaj też na niewidoczny znacznik BOM na początku pliku.

Jak importować produkty z wariantami?

Każdy wariant traktuj jako osobną pozycję z własnym SKU i własnym stanem. W CSV układasz warianty zwykle jako osobne wiersze z odwołaniem do wspólnego produktu nadrzędnego, w XML jako zagnieżdżone węzły. Stan liczony na wariancie, nigdy na produkcie zbiorczym.

Jak aktualizować ceny i stany bez tworzenia duplikatów?

Użyj aktualizacji przyrostowej (upsert) po SKU: istniejące SKU aktualizuje produkt, nowe go tworzy. Nie zmieniaj raz nadanych SKU — ich zmiana sprawia, że system widzi nową pozycję i robi duplikat. Do częstych zmian puszczaj wąski plik „SKU + cena + stan“.

Podsumowanie

Dobry import produktów z CSV lub XML to nie kwestia jednego kliknięcia, tylko porządku: uporządkowany plik, świadome mapowanie pól, spójne i stałe SKU, warianty liczone na właściwym poziomie, plik w UTF-8 i walidacja na próbce przed wpuszczeniem całości. Traktuj import jako powtarzalny, przyrostowy proces — osobny lekki feed cen i stanów, pełne dane tylko gdy trzeba — a unikniesz duplikatów i rozjechanego katalogu.

Chcesz zbierać produkty ze wszystkich kanałów w jednym, znormalizowanym widoku spiętym wspólnym SKU? Zobacz, jak działa prosty system magazynowy dla sklepu, poznaj czym jest OMS dla e-commerce i policz swój koszt w Sellaro. Brakującą integrację dodamy gratis w ramach pakietu.