Przejdź do treści

Import produktów do Shopera z CSV i XML

Plik od hurtowni trafia do Shopera bez ręcznego sprzątania po imporcie. Sprawdzamy SKU, EAN, warianty i stany, zanim cokolwiek zapiszemy, a błędne wiersze dostajesz w raporcie.

Realizacja10 018 nazw produktów zapisanych przez API w ok. 65 minSportina · Shoper
wzor-importu-produktow-utf8.csvfragment wzoru
sku;ean;name;price_gross;stock;category;variant_group;color;size;image_urlnagłówki kolumn, separator „;”, UTF-8TSHIRT-001-BLK-S;5901234567807;Koszulka techniczna;129.90;8;Odzież > Koszulki;TSHIRT-001;Czarny;S;https://example.com/images/tshirt-black.jpgTSHIRT-001-BLK-M;5901234567814;Koszulka techniczna;129.90;14;Odzież > Koszulki;TSHIRT-001;Czarny;M;https://example.com/images/tshirt-black.jpgten wiersz prowadzimy niżej przez cztery kroki importuTSHIRT-001-WHT-M;5901234567821;Koszulka techniczna;129.90;3;Odzież > Koszulki;TSHIRT-001;Biały;M;https://example.com/images/tshirt-white.jpgten sam variant_group: jedna rodzina wariantowa

Pliki do pobrania

Dwa pliki, których używamy na starcie każdego importu. Wypełnij je własnymi danymi i przyślij zamiast opisu. Pierwsza odpowiedź będzie konkretna: co da się zaimportować bez zmian, które kolumny wymagają normalizacji i które wiersze odrzuci walidacja.

  • Wzór importu produktów (UTF-8)Nagłówki kolumn, jedna rodzina wariantowa, EAN zapisany jako tekst z zerem wiodącym i separator, który nie rozjeżdża się po otwarciu w arkuszu.
    Pobierz wzór CSV
  • Macierz kontroli wariantówSprawdzenia dla rozmiarów, kolorów i rodzin: klucz grupowania, kompletność kombinacji, duplikaty SKU, braki EAN.
    Pobierz macierz wariantów

Co reprezentuje jeden wiersz, jakie kodowanie i separator ustawić oraz jak nie zgubić zera wiodącego w EAN-ie: instrukcja przygotowania pliku. Dalej w temacie: checklista importu produktów.

Nowy katalog, aktualizacja czy stały cykl?

Od tej decyzji zależy, które pola wolno nadpisać, jak ważny jest klucz produktu i kto pilnuje importu po pierwszym przebiegu.

Nowy katalog, aktualizacja i stały cykl: co zmieniamy, co zostaje na miejscu, klucz i utrzymanie
AspektNowy katalogAktualizacjaStały cykl
CelBudujemy katalog albo przenosimy go z innego sklepu.Zmieniamy wybrane dane bez psucia reszty – zwykle cenę i stan.Ceny i stany przychodzą regularnie.
Co zmieniamyWypełniamy wszystkie pola, w tym opisy i SEO.tylko uzgodnione pola (zwykle cena i stan)ceny i stany z każdego kolejnego pliku
Co zostaje na miejscuPrzy eksporcie z innego sklepu ID i URL-e nie przenoszą się wprost.Opisy i SEO są chronione przed nadpisaniem.opisy i SEO chronione przed nadpisaniem; reguła dla produktów usuniętych u dostawcy (ukryj czy wyzeruj stan)
Klucz produktuważnyKlucz jest krytyczny: bez niego nadpiszesz nie ten produkt.krytyczny — bez niego nadpiszesz nie ten produkt
Wiersz bez dopasowaniaWiersz bez odpowiednika w sklepie staje się nowym produktem według uzgodnionego wzoru.Wiersz, który nie pasuje do żadnego produktu, pasuje do kilku albo ma sprzeczne SKU i EAN, trafia do wyjątków z powodem.trafia do wyjątków z powodem, jak przy aktualizacji
Utrzymaniezwykle jednorazowojednorazowo albo cyklicznieharmonogram, alerty, archiwum plików. Do cyklu nadają się CSV o stałej strukturze, XML i API hurtowni; Excel raczej nie. Proces na stałe: Shoper API.

Źródła danych: CSV, XML, Excel, API, eksport z innego sklepu

typowe zastosowanie, na co uważać i czy nadaje się do cyklu

Format źródła wpływa nie tyle na sam import, ile na sposób jego utrzymania: co zrobić, gdy plik nie przyjdzie, gdy zmieni się kolumna albo gdy dostawca usunie produkt bez uprzedzenia.

Porównanie źródeł danych produktowych
ŹródłoTypowe zastosowanieNa co uważaćNadaje się do cyklu
CSV od dostawcypierwsze zasilenie katalogukodowanie, separator, cudzysłowy w opisachtak, przy stałej strukturze
XML / feed hurtowniwarianty i zagnieżdżone atrybutyzmiany schematu bez zapowiedzitak
Excel (XLSX)dane przygotowane ręcznieformaty liczb, daty, scalone komórkiraczej nie
API hurtownistany i ceny w ciągu dnialimity zapytań, paginacja, autoryzacjatak
Eksport z innego sklepumigracja kataloguID i URL-e nie przenoszą się wprostjednorazowo

Jeżeli import ma działać regularnie z hurtownią, warto wcześniej porównać API, XML i CSV jako źródła danych, bo każdy format inaczej wpływa na aktualność stanów, błędy i utrzymanie procesu. Gdy produkty, ceny i dostępność mają na stałe przychodzić od hurtowni albo innych dostawców, zobacz integrację sklepu z hurtownią.

Cztery kroki: próbka, kopia, import i kontrola

Zamiast ręcznie szukać problemów w panelu po imporcie, dostajesz raport przed publikacją i listę zmian po niej. Pełny wsad trafia do sklepu dopiero po akceptacji próbki.

Jeden wiersz ze wzoru przez cztery kroki: TSHIRT-001-BLK-M

przykład · wzór CSV
  1. bez zapisuPróbkaKolumny wiersza zmapowane na pola Shopera (sku → SKU, ean → EAN, variant_group → rodzina), walidacja i raport błędów, bez zapisu do sklepu.
  2. przed zapisemKopiaPoprzednie wartości pól, które import zmienia, pobrane i zarchiwizowane przez API.
  3. partiamiImportPo akceptacji próbki wiersz trafia do sklepu w partii i razem z TSHIRT-001-BLK-S oraz TSHIRT-001-WHT-M tworzy jeden produkt z wariantami.
  4. po zapisieKontrolaOdczyt kontrolny ze sklepu przez API i wynik wiersza w raporcie: utworzony, zaktualizowany, połączony, pominięty albo odrzucony.

Kontrola po imporcie: klient widzi właściwą cenę, wariant i zdjęcie

Komunikat „import zakończony” mówi tylko, że plik przeszedł. O tym, czy klient zobaczy właściwą cenę, wariant i zdjęcie, decyduje kontrola po zapisie. Robimy ją na danych ze sklepu, nie na pliku, który wysłaliśmy. Po imporcie katalog nadaje się do sprzedaży, SEO i kolejnych aktualizacji.

Rozliczenie rekordów

Każdy rekord źródłowy ma przypisany wynik przetwarzania: utworzony, zaktualizowany, połączony w produkt z wariantami, pominięty albo odrzucony, z powodem; osobno uzgadniamy liczbę produktów i wariantów w sklepie, bo kilka wierszy pliku może tworzyć jeden produkt.

Odczyt kontrolny

Zapisane pola odczytujemy ze sklepu przez API i porównujemy z planem, zamiast zakładać, że zapis się udał.

Karty na żywo

Losowa próba kart plus przypadki graniczne: produkty z wieloma wariantami, ceny po przeliczeniu, galerie, filtry na listingu.

Kontrola po czasie

Kolejny odczyt po dniach albo tygodniach pokazuje, czy następny import albo integracja nie cofnęły poprawki.

1. Próbka: źródło, mapa pól i walidacja pole po polu

dane wejściowe, walidacja, pole docelowe i możliwy błąd

Analiza źródła i mapa pól. Plik od dostawcy, ERP, hurtowni lub eksport z obecnego sklepu i opis struktury danych. Ustalamy, które kolumny trafiają do konkretnych pól Shopera i które dane wymagają normalizacji przed importem.

Próbka bez zapisu i raport błędów. Mały zakres produktów z raportem, bez zapisu do sklepu, a potem testowy import: kategorie, warianty, zdjęcia, filtry, SEO i karta produktu. Raport to lista produktów do poprawy i decyzji do podjęcia.

Najważniejszy etap to wychwycenie błędów, nie kliknięcie importu. Raport rozdziela produkty gotowe, wymagające poprawy i takie, których nie wolno aktualizować automatycznie. Każdy wiersz tabeli to jedno pole: skąd przychodzi, jak jest sprawdzane, gdzie ląduje i co się dzieje, gdy nie przejdzie kontroli.

Mapowanie pól: dane wejściowe, walidacja, dane docelowe i możliwy błąd
Dane wejścioweWalidacjaDane doceloweMożliwy błąd
kod dostawcyniepusty, unikalny w plikuSKU produktuduplikat nadpisze inny produkt
kod kreskowy8, 12, 13 lub 14 cyfr i suma kontrolnaEANbłędny EAN psuje feedy i marketplace
nazwadługość, brak kodów w nazwienazwa produktunazwa techniczna zamiast handlowej
cena nettoliczba, separator, walutacena brutto wg stawki VATprzecinek jako separator tysięcy
stanliczba całkowita, nieujemnastan magazynowytekst „dostępny” zamiast liczby
ścieżka kategoriiistnieje w mapie kategoriikategoria sklepunowa gałąź tworzona przypadkiem
rozmiar / kolorwartość ze słownikawariant produktu„XL” i „xl” jako dwa warianty
URL zdjęciaodpowiedź 200, typ plikugaleria produktupusta galeria po imporcie
opisdozwolony HTML, brak skryptówopis produkturozjechany layout karty

2–3. Kopia i publikacja partiami

archiwum zmienianych pól i lista zmienionych produktów z każdego przebiegu

Po akceptacji, z kontrolą po pierwszej paczce. Przed zapisem pobieramy i archiwizujemy przez API poprzednie wartości zmienianych pól. Każdy przebieg ma listę zmienionych produktów, więc te pola w danej partii da się przywrócić bez ruszania reszty katalogu.

4. Raport końcowy i aktualizacje

zapisane, pominięte, odrzucone i dalszy tryb pracy

Zapisane, pominięte, odrzucone i dlaczego. Dalej pełny wsad albo cykliczny proces aktualizacji cen, stanów i danych.

Cena na liście wyższa niż na karcie po imporcie z BaseLinkera

Import przeszedł bez błędów, a klient widział na liście złą cenę. Ten przypadek pokazuje, po co są dwa osobne kroki: kontrola po zapisie i kontrola po czasie.

Ta sama kurtka: lista produktów i karta

schemat, nie zrzut

Lista produktów

569,99 zł

cena wiersza zbiorczego, który był wariantem domyślnym

Karta produktu

499,99 zł

tyle kosztowało siedem z dziewięciu rozmiarów

Schemat przypadku z wdrożenia: sklep Shoper, import z BaseLinkera. Kwoty z ustalenia obok.
Sklep Shoper · import z BaseLinkerawdrożenie

Kurtka pokazywała na liście 569,99 zł, choć siedem z dziewięciu rozmiarów kosztowało 499,99 zł

Przyczyna
domyślnym wariantem był wiersz zbiorczy, a nie dostępny rozmiar
Zmiana
flaga domyślnego wariantu przestawiona na najtańszy dostępny rozmiar
Wynik
produktów z zawyżoną ceną na liście: 103 → 4 (pełna kontrola 20 653 aktywnych produktów po naprawie w połowie września 2026)
Stałe zabezpieczenie
import z BaseLinkera przywraca flagę wariantu domyślnego na droższym rekordzie (zrzut katalogu 15.10.2026, miesiąc po naprawie: 177 produktów z zawyżoną ceną na liście), dlatego od połowy października 2026 korekta działa co noc, z kopią stanu i odczytem kontrolnym
Szczegóły: wariant domyślny Shopera po imporcie z BaseLinkera.
Sprawdźmy Twój import Wyślij próbkę pliku: wskażemy wiersze, które dałyby złą cenę albo wariant.

Od czego zależy wycena importu

Nie liczba produktów jest głównym czynnikiem. Dwadzieścia tysięcy czystych rekordów bywa prostsze niż dwa tysiące z chaotycznymi wariantami. Ten sam model danych utrzymujemy w sklepie z ok. 22 tys. produktów i ok. 168 tys. wariantów.

produktów
ok. 22 tys.
wariantów w tym samym modelu danych
ok. 168 tys.

Jakość źródła

jeden spójny plik czy kilka niekompatybilnych eksportów

Warianty

czy da się wskazać regułę grupowania, czy trzeba ją zbudować

Kategorie

gotowa mapa czy mapowanie od zera

Zdjęcia

dostępne pod URL-em czy do pobrania i przetworzenia

Tryb pracy

jednorazowy import czy utrzymywany proces z harmonogramem

Stan katalogu

pusty sklep czy aktualizacja działającej oferty

Problemy i zakres przed wgraniem produktów

Przed importem warto sprawdzić klucze i warianty w pliku: SKU czy EAN jako klucz produktu i walidacja wariantów przed importem. Walidacja pole po polu jest przy kroku „Próbka” wyżej.

Dlaczego import do Shopera często kończy się bałaganem w katalogu

klucz, warianty, kategorie, atrybuty, zdjęcia, walidacja przed publikacją

To, że plik przechodzi przez importer, nie znaczy, że sklep będzie działał poprawnie. Najdroższe błędy wychodzą później: w filtrach, wariantach, opisach, kategoriach, stanach i ręcznym poprawianiu produktów po publikacji.

Brak stabilnego kluczabez jasno ustalonego SKU lub innego identyfikatora sklep nie wie, czy produkt utworzyć, zaktualizować, pominąć czy zgłosić jako konflikt
Warianty rozbijają produktyrozmiary, kolory i modele przychodzą jako osobne wiersze; bez grupowania karta produktu staje się listą duplikatów
Kategorie dostawcy nie pasująstruktura z hurtowni rzadko odpowiada strukturze sklepu; bez mapowania import tworzy przypadkowe ścieżki i słabe SEO
Atrybuty nie działają w filtrachten sam parametr ma kilka nazw lub formatów, więc klient nie przefiltruje oferty, a listing traci wartość sprzedażową
Zdjęcia nie trafiają do produktówlinki wygasają, nazwy plików się nie zgadzają, kolejność galerii jest przypadkowa albo zdjęcia wariantów mieszają się między produktami
Brak walidacji przed publikacjąprodukty bez ceny, stanu, EAN-u, zdjęcia, kategorii albo opisu trafiają do sklepu i dopiero wtedy zaczyna się ręczne gaszenie pożarów

Ta strona dotyczy katalogu w konkretnym sklepie na Shoperze. Jeżeli szukasz procesu, który cyklicznie przenosi dane między hurtownią, ERP-em, BaseLinkerem i sklepem, właściwym miejscem jest automatyzacja importu i eksportu CSV/XML/API.

Co przygotowujemy przed wgraniem produktów

analiza pliku, mapowanie, warianty, kategorie, atrybuty, zdjęcia, aktualizacje cykliczne

Ten sam model danych pozwala później aktualizować ceny, stany, opisy, zdjęcia i kategorie bez przepisywania sklepu ręcznie, a także podłączyć Shoper API, ERP, BaseLinkera albo opisy AI.

Analiza plikukolumny, kodowanie, separatory, duplikaty, puste pola, formaty liczb, walut i identyfikatorów
Mapowanie pól Shoperanazwa, SKU, EAN, cena, stan, producent, kategoria, opis, zdjęcia i cechy
Warianty i rodzinyreguły grupowania po modelu, kolorze, rozmiarze, kolekcji lub innym kluczu biznesowym
Kategorie i ścieżkikategorie dostawcy zmapowane na strukturę sklepu, żeby katalog wspierał UX, SEO i dalszą rozbudowę oferty
Atrybuty i filtrynormalizacja rozmiarów, kolorów, materiału, sezonu, marki, przeznaczenia i parametrów technicznych
Zdjęcia i galerieźródła zdjęć, kolejność, dostępność plików, miniatury i przypisanie zdjęć do wariantów
Aktualizacje cyklicznepóźniejsze aktualizacje stanów, cen i opisów bez ręcznej pracy zespołu

Rekordy o tym samym kluczu rodziny łączymy w jeden produkt z wariantami, zamiast tworzyć osobne karty dla każdego rozmiaru. Na etapie próbki pokazujemy mapowanie kolumn tak jak w przykładzie u góry strony: SKU, EAN, model, kolor, rozmiar, stock, cena, kategoria i zdjęcia. Rekordy kompletne idą do importu, a braki w wariantach, cenach albo relacjach parent-child trafiają do review (ręcznego przeglądu) zamiast psuć katalog.

Dopasowanie do produktów, które już są w sklepie. Klucz dobieramy do danych źródłowych: zwykle kod produktu (SKU), a gdy dostawca go nie podaje albo podaje inny niż sklep – EAN lub kod producenta.

Przy aktualizacji wiersz, który nie pasuje do żadnego produktu, pasuje do kilku albo ma sprzeczne SKU i EAN, trafia do wyjątków z powodem i czeka na wyjaśnienie, zamiast nadpisać przypadkowy produkt. Przy nowym katalogu brak odpowiednika w sklepie jest normalny: taki wiersz staje się nowym produktem według uzgodnionego wzoru.

Import do Shopera — pytania

Nie ma tu Twojego pytania? Napisz

Tak, ale plik zwykle trzeba najpierw dopasować do struktury sklepu: SKU, EAN, wariantów, kategorii, atrybutów, zdjęć, cen i stanów. Bez tego import może technicznie przejść, ale zostawić bałagan w katalogu.
To dwie osobne decyzje. Cel: import może tworzyć nowe produkty albo aktualizować te, które już są w sklepie (wtedy najważniejszy jest stabilny klucz, żeby nie nadpisać złego produktu). Częstotliwość: każdy z nich może być jednorazowy albo powtarzany według harmonogramu, np. codzienna aktualizacja cen i stanów.
Tak, jeżeli w danych da się wskazać regułę grupowania, na przykład model, kolor, rozmiar, kod rodziny lub inny wspólny identyfikator. Takie mapowanie trzeba przetestować przed pełnym importem.
Tak, ale trzeba sprawdzić dostępność URL-i lub plików, kolejność galerii, zdjęcia wariantów i sytuacje, w których dostawca nie udostępnia kompletu grafik.
Tak. Raport jest kluczowy, bo pokazuje produkty bez wymaganych danych, konflikty SKU, błędne warianty, braki zdjęć i rekordy, których nie powinno się publikować automatycznie.
Tak. Dobrze przygotowane mapowanie danych ułatwia późniejsze integracje API, aktualizacje stanów i cen, eksport zamówień, automatyzacje opisów oraz synchronizację z ERP lub BaseLinkerem.

Masz plik CSV/XML i nie chcesz ręcznie sprzątać produktów po imporcie?

Wyślij przykładowy plik (wystarczy kilkadziesiąt wierszy) i napisz: skąd są dane, ile jest produktów, czy mają warianty i czy to nowy katalog, czy aktualizacja istniejącego. Odpowiemy, co da się zaimportować bez zmian, a co poprawimy przed zapisem, żeby zespół nie sprzątał produktów w panelu.