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 · Shopersku;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 wariantowaPliki 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.
| Aspekt | Nowy katalog | Aktualizacja | Stały cykl |
|---|---|---|---|
| Cel | Budujemy katalog albo przenosimy go z innego sklepu. | Zmieniamy wybrane dane bez psucia reszty – zwykle cenę i stan. | Ceny i stany przychodzą regularnie. |
| Co zmieniamy | Wypeł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 miejscu | Przy 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 produktu | ważny | Klucz jest krytyczny: bez niego nadpiszesz nie ten produkt. | krytyczny — bez niego nadpiszesz nie ten produkt |
| Wiersz bez dopasowania | Wiersz 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 |
| Utrzymanie | zwykle jednorazowo | jednorazowo albo cyklicznie | harmonogram, 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.
| Źródło | Typowe zastosowanie | Na co uważać | Nadaje się do cyklu |
|---|---|---|---|
| CSV od dostawcy | pierwsze zasilenie katalogu | kodowanie, separator, cudzysłowy w opisach | tak, przy stałej strukturze |
| XML / feed hurtowni | warianty i zagnieżdżone atrybuty | zmiany schematu bez zapowiedzi | tak |
| Excel (XLSX) | dane przygotowane ręcznie | formaty liczb, daty, scalone komórki | raczej nie |
| API hurtowni | stany i ceny w ciągu dnia | limity zapytań, paginacja, autoryzacja | tak |
| Eksport z innego sklepu | migracja katalogu | ID i URL-e nie przenoszą się wprost | jednorazowo |
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- PróbkaKolumny wiersza zmapowane na pola Shopera (sku → SKU, ean → EAN, variant_group → rodzina), walidacja i raport błędów, bez zapisu do sklepu.
- KopiaPoprzednie wartości pól, które import zmienia, pobrane i zarchiwizowane przez API.
- ImportPo 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.
- KontrolaOdczyt 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.
| Dane wejściowe | Walidacja | Dane docelowe | Możliwy błąd |
|---|---|---|---|
| kod dostawcy | niepusty, unikalny w pliku | SKU produktu | duplikat nadpisze inny produkt |
| kod kreskowy | 8, 12, 13 lub 14 cyfr i suma kontrolna | EAN | błędny EAN psuje feedy i marketplace |
| nazwa | długość, brak kodów w nazwie | nazwa produktu | nazwa techniczna zamiast handlowej |
| cena netto | liczba, separator, waluta | cena brutto wg stawki VAT | przecinek jako separator tysięcy |
| stan | liczba całkowita, nieujemna | stan magazynowy | tekst „dostępny” zamiast liczby |
| ścieżka kategorii | istnieje w mapie kategorii | kategoria sklepu | nowa gałąź tworzona przypadkiem |
| rozmiar / kolor | wartość ze słownika | wariant produktu | „XL” i „xl” jako dwa warianty |
| URL zdjęcia | odpowiedź 200, typ pliku | galeria produktu | pusta galeria po imporcie |
| opis | dozwolony HTML, brak skryptów | opis produktu | rozjechany 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 zrzutLista 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
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
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.
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.
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.
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.