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 CSVZespół 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 · ShoperTa 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?
| Aspekt | Jednorazowo | Utrzymywany pipeline |
|---|---|---|
| Uruchomienie | ręczne | harmonogram |
| Brak pliku źródłowego | widać od razu | alert po przekroczeniu okna |
| Błąd w połowie | start od nowa | wznowienie od miejsca przerwania |
| Zmiana struktury źródła | poprawka doraźna | walidacja schematu zatrzymuje zapis |
| Historia | brak | archiwum plików i logów |
| Rozliczalność | trudna | raport z każdego przebiegu |
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.
| Ładunek | Co zawiera | Skąd → dokąd | Format | Rytm |
|---|---|---|---|---|
| Katalog | produkty, warianty, kategorie, ceny, stany, zdjęcia i atrybuty | hurtownia → sklep | CSV, XML, API | dobowo |
| Stany i ceny | dostępność i cena każdego SKU | ERP → sklep | API lub plik | co kilka–kilkadziesiąt minut, zależnie od limitów API |
| Zamówienia | pozycje, dane klienta, adresy, SKU, EAN i statusy | sklep → ERP | CSV, XLSX, API | na zdarzenie |
| Statusy | status realizacji zamówienia | ERP → sklep | API lub plik | na zdarzenie |
| Ładunek | Co zawiera | Skąd → dokąd | Format | Rytm |
|---|---|---|---|---|
| Oferta | produkty, ceny, stany | sklep → BaseLinker | API | przy zmianie, na zdarzenie |
| Feed porównywarki | oferta z mapą kategorii odbiorcy | sklep → porównywarka cen | XML | dobowo |
| Oferta marketplace | ceny i stany | sklep → marketplace | API lub XML | przy zmianie ceny/stanu |
| Plik dla partnera | oferta albo stany | sklep → hurtownia / partner | CSV na FTP | harmonogram |
| Raporty | podsumowania zmian, błędów, produktów pominiętych i wyjątków | sklep → arkusz / mail | CSV / arkusz | tygodniowo |
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.
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
<cena>1.299,00</cena> → 1299.00 PLN bruttoPlik 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ą.
Kodowanie, separatory, formaty liczb i dat, waluty, jednostki, nazwy kolumn. Dane różnych dostawców sprowadzamy do jednego wewnętrznego formatu.
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.
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.
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.
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.
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ć
| Pole | Co przetwarzamy |
|---|---|
| kategoria | mapowanie kategorii na drzewo odbiorcy, nie na własne nazwy, |
| identyfikatory | identyfikatory: GTIN/EAN, SKU i kod producenta w formacie wymaganym przez kanał, |
| ceny | ceny: 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, |
| warianty | warianty: czy kanał chce jedną ofertę z opcjami, czy osobne pozycje, |
| zdjęcia | zdjęcia: stabilne URL-e o wymaganym minimalnym rozmiarze, |
| walidacja | walidacja przed publikacją: pozycja bez wymaganego pola nie trafia do pliku. |
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.
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 wariantvariant_groupNagłówki kolumn, rodzina wariantowa i EAN zapisany jako tekst — czyli minimalny kontrakt danych wejściowych.
Pobierz wzór CSVSprawdzenia, które w utrzymywanym procesie uruchamiamy automatycznie przy każdym przebiegu.
Pobierz macierz wariantówPorównanie API, XML i CSV jako źródła danych: aktualność stanów, obsługa błędów i koszt utrzymania.
Otwórz poradnikNie 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
Ten sam pipeline zawężony do katalogu jednego sklepu na Shoperze.
Import Shoper CSV/XMLZamówienie jako dokument wychodzący do ERP, nie jako plik katalogu.
Eksport zamówień B2BReguły i progi błędów, które decydują, co wolno zapisać automatycznie.
Walidacja danychModel danych, do którego pipeline musi doprowadzić każde źródło.
Dane produktowe e-commerce