Przejdź do treści

Automatyzacja importu i eksportu CSV/XML/API dla e-commerce

Zespół co tydzień przepisuje pliki dostawców, ceny i stany między sklepem, hurtownią, ERP i marketplace? Zamieniamy to w import i eksport, który działa sam: sprawdza dane przed zapisem, pokazuje podgląd zmian i kończy się raportem.

Realizacja10 018 produktów zaktualizowanych przez API w ok. 65 min działania automatyzacjiSportina · Shoper
Jedno pole w podglądzie zmian: cena namiotu NT-300 przykład · dane demonstracyjne
  1. plik dostawcy · XML <cena>1.299,00</cena> kropka jako separator tysięcy, przecinek dziesiętny wczytane
  2. normalizacja 1299.00 PLN brutto jeden format liczb i walut dla wszystkich dostawców zgodne z regułą
  3. podgląd zmian (dry-run: przebieg bez zapisu) Cena: 1 349,00 zł → 1 299,00 zł wartość przed i po dla tego pola; pozostałe pola rekordu bez zmian do zapisu
  4. po zapisie W sklepie 1 299,00 zł, poprzednia wartość w kopii wpis w raporcie przebiegu i w logu operacji zapisane
Przykład na danych demonstracyjnych. Które pola wolno nadpisać i jak duża zmiana czeka na akceptację, ustalamy dla każdego procesu.

Plik raz czy proces cykliczny?

Ta strona dotyczy procesu łączącego kilka systemów: hurtownię, ERP, BaseLinkera, marketplace i sklep. Różnica nie polega na złożoności kodu, tylko na tym, co się dzieje, gdy coś pójdzie nie tak o trzeciej w nocy.

Jak często dane mają przechodzić między systemami?

  1. raz, uruchomienie ręcznePlik: import lub eksport jednorazowoUruchomienie ręczne. Brak pliku źródłowego widać od razu, błąd w połowie oznacza start od nowa, a zmiana struktury źródła – poprawkę doraźną.
    Jeżeli szukasz jednorazowego lub cyklicznego importu katalogu do konkretnej platformy, właściwym miejscem jest import produktów do Shopera z CSV/XML.
    Wzór pliku i macierz wariantów: struktura pliku niżej.
  2. w stałym rytmieProces cykliczny: utrzymywany pipelineHarmonogram, alert po przekroczeniu okna, wznowienie od miejsca przerwania, walidacja schematu zatrzymuje zapis, archiwum plików i logów, raport z każdego przebiegu.
    Jeśli chodzi głównie o produkty, ceny i dostępność od hurtowni i dostawców, zobacz integrację sklepu z hurtownią.
    Feedy do marketplace i porównywarek: ten sam pipeline niżej.

Skrypt uruchamiany raz a proces, który działa co dzień

porównanie: uruchomienie, brak pliku, błąd w połowie, zmiana struktury, historia, rozliczalność
Import jednorazowy a utrzymywany pipeline
AspektJednorazowoUtrzymywany pipeline
Uruchomienieręczneharmonogram
Brak pliku źródłowegowidać od razualert po przekroczeniu okna
Błąd w połowiestart od nowawznowienie od miejsca przerwania
Zmiana struktury źródłapoprawka doraźnawalidacja schematu zatrzymuje zapis
Historiabrakarchiwum plików i logów
Rozliczalnośćtrudnaraport z każdego przebiegu

Systemy i dane, których nie trzeba już przepisywać

Między którymi systemami i co przez ten proces najczęściej przepływa. Cztery ładunki, od których zwykle zaczynamy; feedy dla kanałów i raporty są w rozwinięciu pod tabelą. Każdy ładunek ma swój kierunek, format i rytm; architektura procesu jest ta sama, różni się mapa pól.

Ładunki importu i eksportu: zawartość, kierunek, format i rytm
ŁadunekCo zawieraSkąd → dokądFormatRytm
Katalogprodukty, warianty, kategorie, ceny, stany, zdjęcia i atrybutyhurtownia → sklepCSV, XML, APIdobowo
Stany i cenydostępność i cena każdego SKUERP → sklepAPI lub plikco kilka–kilkadziesiąt minut, zależnie od limitów API
Zamówieniapozycje, dane klienta, adresy, SKU, EAN i statusysklep → ERPCSV, XLSX, APIna zdarzenie
Statusystatus realizacji zamówieniaERP → sklepAPI lub plikna zdarzenie
Pozostałe ładunki (5): oferta do BaseLinkera, feed porównywarki, marketplace, plik dla partnera, raporty
Pozostałe ładunki eksportu: zawartość, kierunek, format i rytm
ŁadunekCo zawieraSkąd → dokądFormatRytm
Ofertaprodukty, ceny, stanysklep → BaseLinkerAPIprzy zmianie, na zdarzenie
Feed porównywarkioferta z mapą kategorii odbiorcysklep → porównywarka cenXMLdobowo
Oferta marketplaceceny i stanysklep → marketplaceAPI lub XMLprzy zmianie ceny/stanu
Plik dla partneraoferta albo stanysklep → hurtownia / partnerCSV na FTPharmonogram
Raportypodsumowania zmian, błędów, produktów pominiętych i wyjątkówsklep → arkusz / mailCSV / arkusztygodniowo

Jeżeli ten sam proces ma obsługiwać zamówienia partnerów, osobnym etapem projektujemy eksport zamówień B2B do ERP: z pozycjami, danymi klienta, statusem, logiem i formatem zgodnym z realną pracą handlowca.

Jeden przebieg od wejścia do raportu: błędy widać przed zapisem

Sześć etapów, przez które przechodzi każdy plik i każde wywołanie API. Import nie wykłada się na samym pliku CSV, XML czy API, tylko na wyjątkach: brakujących polach, innych nazwach kategorii, wariantach bez relacji, różnicach cen i stanach magazynowych z kilku źródeł.

Źródło → kontrola → eksport → raport

  1. pobranie · normalizacjaŹródłoPlik z serwera dostawcy, feed pod adresem albo odpowiedź API, sprowadzone do jednego wewnętrznego formatu.
    Przykład: <cena>1.299,00</cena> → 1299.00 PLN brutto
  2. odrzucenieKontrolaWalidacja schematu zatrzymuje zapis. Rekord odrzucony na walidacji nie trafia do sklepu ani ERP.
    Przykład: dry-run pokazuje, co zostanie zapisane, co pominięte i z jakiego powodu.
  3. zapis · ponowienieEksportPaczkami, z kontrolą tempa, ponowieniem i kluczem idempotencji. Zapis idzie tylko do pól objętych zakresem procesu.
    Przykład: Cena: 1 349,00 zł → 1 299,00 zł
  4. raport · archiwumRaportPodsumowanie przebiegu, log operacji i archiwizacja pliku źródłowego.
    Przykład: w sklepie 1 299,00 zł, poprzednia wartość w kopii.
Przykłady przy krokach: cena namiotu NT-300 z otwarcia strony, dane demonstracyjne.
Sześć etapów przebiegu: pobranie, normalizacja, walidacja, transformacja, zapis, raport i archiwum
  1. 01

    Pobranie

    Plik z serwera dostawcy, feed pod adresem albo odpowiedź API. Każde źródło ma określone okno czasowe i alert, gdy dane nie przyjdą.

  2. 02

    Normalizacja

    Kodowanie, separatory, formaty liczb i dat, waluty, jednostki, nazwy kolumn. Dane różnych dostawców sprowadzamy do jednego wewnętrznego formatu.

  3. 03

    Walidacja

    Pola wymagane, typy, zakresy i słowniki. Wynik dzieli rekordy na poprawne, wymagające decyzji i odrzucone.

    Blokada przy błędnym pliku Zmiana struktury źródła: walidacja schematu zatrzymuje zapis. Rekord odrzucony na walidacji nie trafia do sklepu ani ERP.

  4. 04

    Transformacja

    Mapowanie na model docelowy: SKU, EAN, nazwy, kategorie, warianty, atrybuty, ceny, stany, jednostki sprzedaży. Każde pole ma jasną regułę przekształcenia; tu powstaje właściwy ładunek zapisu.

    Próbka: raport przed zapisem (dry-run) Przed pierwszym zapisem i po każdej zmianie reguł proces pokazuje, co zostanie zapisane, co pominięte i z jakiego powodu: nowe rekordy, aktualizacje, pominięcia, błędne EAN/SKU, konflikty wariantów i wartości, których nie wolno opublikować automatycznie.

  5. 05

    Zapis

    Paczkami, z kontrolą tempa, ponowieniem i kluczem idempotencji (unikalny identyfikator operacji — ponowienie nie tworzy duplikatu). Np. BaseLinker przyjmuje 100 zapytań/min, a Shoper zwraca w nagłówkach licznik operacji i tempo jego zwalniania (według dokumentacji domyślnie 10 i 2/s, w praktyce trzeba je odczytywać z nagłówków) — tempo zapisu wynika z tych limitów, nie z naszego kodu. Zapis idzie tylko do pól objętych zakresem procesu.

  6. 06

    Raport i archiwum

    Podsumowanie przebiegu, log operacji i archiwizacja pliku źródłowego — żeby dało się odtworzyć, co dokładnie przyszło danego dnia.

    Historia wersji Log i archiwum pliku pozwalają odtworzyć każdy przebieg.

Co walidacja zatrzymuje przed zapisem: duplikaty i błędne klucze, niespójna struktura katalogu, ceny, stany i skutki operacyjne
  • Duplikaty i błędne klucze powtórzone SKU, puste EAN-y, kolizje identyfikatorów i rekordy, które mogłyby nadpisać dobry produkt złym wariantem
  • Niespójna struktura katalogu kategorie, warianty parent-child, atrybuty i mapowania pól — żeby import nie tworzył pustych listingów ani produktów bez właściwej relacji
  • Ceny, stany i skutki operacyjne zakresy cen, spadki stanów, brakujące źródła oraz rekordy odstające od reguł, zanim zmiana trafi do sprzedaży lub raportu dla zespołu

Jak uruchamiamy import, żeby sklep sprzedawał bez przerwy

Efekt: import lub eksport, który da się sprawdzić przed zapisem

  • Mniej ręcznego przepisywania i formatowania plików.
  • Spójny format między sklepem, hurtownią i ERP.
  • Lepsza kontrola błędów przed publikacją.
  • Możliwość rozwijania procesu o AI i API.
  1. Źródło i celUstalamy skąd dane wychodzą, dokąd trafiają i które pola są krytyczne.
  2. Format pośredniTworzymy format pośredni: jeden sposób opisu produktu, zamówienia lub stanu, zanim dane trafią do kolejnego systemu.
  3. WalidacjaBlokujemy błędy przed zapisem lub eksportem.
  4. Dry-runPokazujemy podgląd operacji i raport.
  5. AutomatyzacjaUruchamiamy proces cykliczny albo skrypt do kontrolowanego użycia.

Eksport oferty do marketplace i porównywarek to też pipeline

Kanał zewnętrzny nie przyjmuje katalogu sklepu w takiej formie, w jakiej on istnieje. Wymaga własnego zestawu pól, własnej kategoryzacji i własnej definicji dostępności. Feed generowany „na żywo” z bazy sklepu wymaga poprawki w kodzie przy każdej zmianie wymagań odbiorcy.

Ten sam mechanizm obsługuje feed do porównywarki, plik dla hurtowni i eksport oferty do BaseLinkera (odbiorcy, formaty i rytm są w rozwinięciu tabeli przepływów wyżej). Różni się mapa pól, nie architektura procesu.

Co trzeba przetworzyć

feed wychodzący · pola kanału
PoleCo przetwarzamy
kategoriamapowanie kategorii na drzewo odbiorcy, nie na własne nazwy,
identyfikatoryidentyfikatory: GTIN/EAN, SKU i kod producenta w formacie wymaganym przez kanał,
cenyceny: brutto, waluta, cena promocyjna i jednostkowa jako osobne pola,
dostępnośćdostępność: dla porównywarek próg usuwający pozycję, dla Merchant Center status out_of_stock zamiast usuwania,
wariantywarianty: czy kanał chce jedną ofertę z opcjami, czy osobne pozycje,
zdjęciazdjęcia: stabilne URL-e o wymaganym minimalnym rozmiarze,
walidacjawalidacja przed publikacją: pozycja bez wymaganego pola nie trafia do pliku.

Struktura pliku, od której zaczyna się każdy import

Zanim ustalimy harmonogram i logi, musi być zgoda co do tego, co reprezentuje jeden wiersz. Te dwa pliki są punktem wyjścia rozmowy — możesz je wypełnić własnymi danymi zamiast opisywać strukturę słowami.

wzor-importu-produktow-utf8.csvpierwsze wiersze wzoru
sku;ean;name;price_gross;stock;category;variant_group;color;size;image_urlnagłówki kolumnTSHIRT-001-BLK-S;5901234567807;Koszulka techniczna;129.90;8;Odzież > Koszulki;TSHIRT-001;Czarny;S;…jeden wiersz to jeden wariant
Pierwsze wiersze wzoru importu (plik do pobrania niżej): jeden wiersz to jeden wariant, rodzina w kolumnie variant_group

Wzór importu produktów (UTF-8)

Nagłówki kolumn, rodzina wariantowa i EAN zapisany jako tekst — czyli minimalny kontrakt danych wejściowych.

Pobierz wzór CSV

Macierz kontroli wariantów

Sprawdzenia, które w utrzymywanym procesie uruchamiamy automatycznie przy każdym przebiegu.

Pobierz macierz wariantów

Integracja z hurtownią

Porównanie API, XML i CSV jako źródła danych: aktualność stanów, obsługa błędów i koszt utrzymania.

Otwórz poradnik

Gdzie najczęściej powstaje chaos integracyjny?

sześć miejsc, w których ręczna wymiana danych się wykłada
Ręczne przeklejanie plikówZespół traci czas na powtarzalne eksporty, formatowanie i poprawianie arkuszy.
Każdy system ma inny formatSklep, hurtownia, ERP i marketplace wymagają innych nazw pól, kodowania i struktury.
Brak kontroli zmianNie wiadomo, co zmieniło się od ostatniego importu: cena, stan, opis, zdjęcie czy kategoria.
Eksport zamówień jest ręcznyZamówienia trzeba przepisywać do ERP albo wysyłać w arkuszach bez jednego standardu.
Integracja nie ma logówGdy proces się wyłoży, nikt nie wie na którym rekordzie i z jakiego powodu.
Pliki są za duże dla ręcznej pracyPrzy tysiącach produktów Excel staje się narzędziem podglądu, nie bezpiecznym systemem procesu.

Importy i eksporty — pytania

Nie ma tu Twojego pytania? Napisz

Często tak, jeśli proces jest batchowy. API jest lepsze przy częstych aktualizacjach i komunikacji dwukierunkowej.
Tak. Zamówienia można eksportować do CSV/XLSX/API w formacie wymaganym przez firmę lub ERP.
Docelowo tak, jeśli ma być produkcyjna. Na MVP można zacząć lokalnie, żeby sprawdzić reguły i format.
Tak, np. o opisy, klasyfikację, mapowanie kategorii albo kontrolę jakości danych.
Tempo wyznacza limit systemu docelowego: BaseLinker przyjmuje ok. 100 zapytań na minutę, a Shoper zwraca w nagłówkach licznik operacji (X-Shop-Api-Limit, według dokumentacji domyślnie 10) i tempo jego zwalniania (X-Shop-Api-Bandwidth, domyślnie 2 na sekundę), a po przekroczeniu odpowiada 429 z Retry-After. Limit liczony jest osobno dla każdej aplikacji, a wartości bywają inne niż domyślne: w sklepie sprawdzanym w październiku 2026 Bandwidth wynosił 10. Dlatego zapis idzie paczkami sterowanymi tymi nagłówkami, a wysyłane są tylko rekordy, które się zmieniły.

Opisz, co dziś przepisujecie między systemami ręcznie

Nie musisz mieć gotowej specyfikacji. Wystarczy przykładowy plik, link do źródła danych albo opis ręcznego procesu, który dziś zabiera czas zespołu.

Z czym najczęściej spina się ten proces

Integracje API

Architektura wymiany: REST, webhooki, kolejki, retry i źródło prawdy.

Integracje API

Import Shoper CSV/XML

Ten sam pipeline zawężony do katalogu jednego sklepu na Shoperze.

Import Shoper CSV/XML

Eksport zamówień B2B

Zamówienie jako dokument wychodzący do ERP, nie jako plik katalogu.

Eksport zamówień B2B

Walidacja danych

Reguły i progi błędów, które decydują, co wolno zapisać automatycznie.

Walidacja danych

Dane produktowe e-commerce

Model danych, do którego pipeline musi doprowadzić każde źródło.

Dane produktowe e-commerce