Blog · Integracje · IdoSell

Stany magazynowe z hurtowni — feed XML, CSV, API

Hurtownia udostępnia dane w XML, CSV lub przez REST API. Każdy format ma inne kompromisy — wydajnościowe, operacyjne, integracyjne. Pokazujemy głębiej, gdzie który się sprawdza, jakie problemy generuje i który wybrać dla sklepu IdoSell.

CZAS CZYTANIA: ~11 MIN · POZIOM: TECHNICZNO-OPERACYJNY

Wybór formatu feedu hurtowni wydaje się drobiazgiem technicznym — a w praktyce jest jedną z ważniejszych decyzji przy integracji sklepu z dostawcami. XML potrafi być plikiem 200 MB, który parsuje się 10 minut. CSV bez BOM-a rozjeżdża wszystkie polskie znaki. REST API brzmi świetnie, ale nie każda hurtownia go ma, a te które mają — czasem gorzej niż XML. Ten wpis pokazuje konkretnie, co realnie działa, co zawodzi, i jak wybrać sensownie w kontekście sklepu IdoSell.

Co to jest feed hurtowni

Feed to strumień danych dostarczany przez hurtownię, opisujący jej asortyment i stany magazynowe. Sklep pobiera feed, parsuje, aktualizuje własne dane (produkty, stany, ceny). W IdoSell feed może być używany na kilka sposobów:

Aktualizacja stanów magazynowych — najczęstsze zastosowanie. Codziennie lub kilka razy dziennie sklep pobiera aktualne stany, żeby nie sprzedawać czegoś, czego hurtownia już nie ma

Aktualizacja cen zakupu — hurtownia zmienia ceny, sklep pobiera nowe i przelicza ceny sprzedaży (opisane w wpisie o automatycznej aktualizacji cen)

Import nowych produktów — hurtownia dodała asortyment, sklep pobiera i decyduje, co włączyć do oferty

Zdjęcia i opisy produktów — niektóre hurtownie w feedzie udostępniają też URL do zdjęć i opisy produktów

Format feedu w dużej mierze determinuje, jak łatwo Ci będzie z tym pracować. Trzy dominujące opcje na polskim rynku: XML, CSV, REST API.

XML — dominujący format w PL

XML to najczęstszy format feedu polskich hurtowni B2B (Invena, Oltens, Candellux i wiele innych). Powód historyczny: XML powstał w epoce, gdy definiowano polskie standardy e-commerce (BaseLinker, Comarch, IdoSell natywnie). Praktycznie każda hurtownia z portfolio 5+ lat na rynku ma XML.

Typowa struktura feedu XML

Feed hurtowni XML zawiera zwykle listę produktów, każdy z zestawem atrybutów: kod producenta, EAN, nazwa, kategorię, stan magazynowy, cenę zakupu, jednostka miary, zdjęcia (URL). W zależności od hurtowni — dodatkowe pola: parametry techniczne, warianty, akcesoria powiązane. Struktura jest hierarchiczna, dobrze pasuje do produktów z wariantami.

Plusy XML

Standard w PL — IdoSell natywnie obsługuje najpopularniejsze schematy XML, wsparcie dostawców i integratorów

Struktura hierarchiczna — dobrze modeluje produkty z wariantami, zagnieżdżone kategorie, atrybuty

Walidacja przez XSD — hurtownia może udostępniać schemat, dzięki czemu wiadomo, czego się spodziewać

Dojrzały ekosystem narzędzi — biblioteki do parsowania w każdym języku, sprawdzone od lat

Minusy XML

Rozmiar plików — full feed z 50 000 produktami potrafi mieć 200-500 MB. Pobieranie kilka minut, parsowanie kolejne kilka minut

Pełny feed za każdym razem — hurtownie zwykle nie oferują delty (tylko zmiany od ostatniego pobrania). Za każdym razem parsujesz wszystko

Verbose format — dużo boilerplate (znaczniki otwierające i zamykające), niska gęstość informacji

Niejednolite schematy — każda hurtownia ma własną strukturę. Integracja z 5 hurtowniami to 5 różnych parserów

Praktyczne wskazówki przy parsowaniu XML

Dla dużych feedów używaj streamingowego parsera (SAX/StAX zamiast DOM) — nie ładuje całego XML do pamięci naraz, tylko przetwarza element po elemencie. Różnica: DOM na feedzie 300 MB może wymagać 2-3 GB RAM. Streaming — 50-100 MB. Dla PHP: XMLReader. Dla Node: sax-js. Dla Pythona: iterparse z lxml.

CSV — prosty, ale zdradliwy

CSV to format płaski (tabelaryczny), gdzie każdy wiersz to produkt, każda kolumna to pole (nazwa, cena, stan, EAN). Popularny wśród mniejszych hurtowni, tam gdzie nie ma potrzeby modelować skomplikowanych struktur. Wydawałoby się „najprostszy" — w praktyce najbardziej zdradliwy przy parsowaniu.

Plusy CSV

Lekki — 50 000 produktów w CSV to 20-40 MB, znacznie mniej niż XML

Szybkie parsowanie — nawet naiwna implementacja radzi sobie z dużym plikiem w sekundach

Łatwość edycji — można ręcznie sprawdzić lub zmienić dane w Excelu, Google Sheets, dowolnym edytorze tekstu

Prosta struktura — łatwo napisać własny parser od zera

Minusy CSV — czyli dlaczego bywa koszmarem

Brak standardu — separator to przecinek? Średnik? Tab? Cudzysłów dookoła pól? Escapowanie? Każda hurtownia ma własne konwencje

Encoding — polskie znaki w Windows-1250, UTF-8, ISO-8859-2? Bez BOM-a nie wiadomo, aż zobaczysz „krzaki" w zaimportowanych opisach

Warianty produktów — CSV to płaska tabela, warianty produktu (rozmiar, kolor) trudno tu naturalnie zapisać. Zwykle każdy wariant to osobny wiersz — trudniej powiązać z produktem-rodzicem

Zagubione dane w opisach — cudzysłów wewnątrz opisu bez escapowania, znak nowej linii wewnątrz pola, przecinek w cenie „1,999.00" — każdy z tych przypadków rozjeżdża naiwny parser

Praktyczne wskazówki przy CSV

Używaj sprawdzonych bibliotek CSV (nie splituj po przecinku!). Ustaw explicitly separator, terminator wiersza, escape character, encoding. Testuj na kilku wierszach z podejrzanymi danymi (opisy z cudzysłowami, ceny z przecinkiem w tysiącu). Sprawdź, czy hurtownia dostarcza BOM w UTF-8 — bez niego niektóre parsery domyślnie zakładają Windows-1252.

REST API — nowoczesne rozwiązanie

REST API to interfejs, przez który sklep aktywnie pyta hurtownię o dane („daj mi stany produktów X, Y, Z", „daj mi wszystko co się zmieniło od godziny 12:00"). Odpowiedź zwykle w JSON. Coraz częściej spotykane w nowszych hurtowniach, choć wciąż mniejszość polskiego rynku.

Plusy REST API

Delta sync — możesz zapytać tylko o zmiany od ostatniego pobrania. Nie musisz parsować 500 MB, żeby znaleźć zmiany dla 30 produktów

Real-time — możesz odpytać w dowolnej chwili, nie musisz czekać na kolejny cykl feedu

Selektywne pobieranie — możesz zapytać tylko o produkty z konkretnej kategorii, tylko o zmiany cen, tylko o określone SKU

Standardy branżowe — HTTP + JSON to standardowy stack, każdy developer pracował z tym

Webhooki — niektóre hurtownie oferują webhooki (hurtownia aktywnie powiadamia sklep o zmianach), co eliminuje potrzebę pollingu

Minusy REST API

Nie każda hurtownia ma — starsze i średnie hurtownie w PL dalej głównie XML. Wybór ograniczony

Rate limity — API zwykle ma limity zapytań (typowo kilka na sekundę), przy 5000 produktach dobierasz się do granicy

Wymagana autoryzacja — klucz API, token, OAuth. Konfiguracja trudniejsza niż „ściągnij plik z FTP"

Dokumentacja bywa uboga — mniej sprawdzone integracje, więcej edge cases do samodzielnego wykrycia

Praktyczne wskazówki przy REST API

Cache'uj dane po stronie sklepu (nie odpytuj API za każdym razem, gdy tylko potrzebujesz stanu produktu — pytaj co np. 15 minut i trzymaj lokalnie). Buduj integrację z retry + exponential backoff (podobnie jak przy synchronizacji zamówień). Respektuj header Retry-After. Zawsze idempotentnie: powtórne zapytanie o ten sam stan nie może skutkować podwójną aktualizacją.

Porównanie XML vs CSV vs API

Krótkie zestawienie dla różnych kryteriów oceny:

Rozmiar i wydajność

Zwycięzca: API (delta sync — pobierasz tylko zmiany). CSV wygrywa z XML przy pełnym feedie (mniejszy rozmiar), ale oba w praktyce są w tym samym rzędzie wielkości (dziesiątki megabajtów).

Częstotliwość aktualizacji

Zwycięzca: API (real-time, dowolna chwila). XML/CSV to okresowe pliki (typowo co 2-6 godzin, czasem raz dziennie). Jeśli sprzedajesz produkty wysokorotacyjne z ryzykiem oversoldu, API daje przewagę.

Łatwość integracji na start

Zwycięzca: XML — IdoSell natywnie obsługuje popularne schematy, konfigurujesz w panelu, gotowe. CSV wymaga zwykle własnego parsera. API — konfiguracja tokenu, mapowanie endpointów, obsługa błędów.

Skomplikowane produkty (warianty)

Zwycięzca: XML (hierarchiczna struktura) lub API (JSON zagnieżdżony). CSV jest słaby — warianty trzeba dublować wiersze i sklejać po ID rodzica.

Stabilność w czasie

Zwycięzca: XML — struktura zmienia się rzadko, integracje działają latami bez ingerencji. API bardziej dynamiczne — hurtownia może zmienić strukturę odpowiedzi.

Koszt utrzymania

Zwycięzca: XML natywne — jeśli IdoSell ma gotową integrację z Twoją hurtownią, zerowy koszt utrzymania. Custom XML, CSV, API — koszt monitoringu i drobnych poprawek podobny.

Sposób dostarczenia — osobny wymiar

Format danych (XML/CSV/JSON) to jedno, sposób dostarczenia to drugie. Ten sam XML może być dostarczony na cztery sposoby, każdy z innymi konsekwencjami:

FTP / SFTP

Klasyka. Hurtownia wrzuca plik na serwer FTP, Ty pobierasz. Prosty, sprawdzony, ale ma minusy: wymaga cyklicznego sprawdzania (nie wiesz automatycznie, kiedy nowy plik jest gotowy), nie ma standardu, jak sygnalizować „ten plik jest kompletny" (czasem hurtownia zapisuje w trakcie uploadu, ty pobierasz niekompletny plik). Rozwiązanie: hurtownia dołącza plik .lock albo .ready jako sygnał gotowości.

HTTP GET (bezpośredni URL)

Hurtownia udostępnia URL, pod którym zawsze jest aktualny feed. Prosto, bez autoryzacji lub z prostym HTTP Basic. Zalety: brak infrastruktury FTP, łatwiejsze do zautomatyzowania. Minus: hurtownia potrzebuje generować pliki na żądanie, co przy dużych feedach przeciąża serwer.

REST API endpoint

Aktywne odpytywanie hurtowni. Wysyłasz zapytanie z parametrami, dostajesz JSON w odpowiedzi. Największa elastyczność, ale wymaga autoryzacji i zarządzania sesją.

Webhook (hurtownia inicjuje)

Najbardziej zaawansowany model — hurtownia po zmianie stanu wysyła powiadomienie do Twojego endpointu. Real-time, bez pollingu, minimalne obciążenie. Ale: mało hurtowni to oferuje, wymaga publicznego endpointu HTTPS, weryfikacji tokenu (podobnie jak przy synchronizacji zamówień).

Kodowanie i encoding — źródło większości bugów

Polskie znaki to najczęstsze źródło problemów przy parsowaniu feedów. „Zamówienie na piĂłro" zamiast „Zamówienie na pióro" — klasyczny efekt złego encodingu. Trzy realne scenariusze:

UTF-8 bez BOM

Nowoczesny standard, największa uniwersalność. Ale bez BOM (Byte Order Mark) niektóre parsery domyślnie zakładają inne kodowanie. Objaw: „ó" wyświetla się jako „Ăł". Rozwiązanie: eksplicytnie wskazać UTF-8 w konfiguracji parsera.

Windows-1250 (CP1250)

Legacy standard z Windows, wciąż spotykany w starszych systemach hurtowniczych. Polskie znaki zakodowane inaczej niż w UTF-8. Objaw: „ł" pojawia się jako „¯". Rozwiązanie: rozpoznawać i konwertować do UTF-8 przed dalszym przetwarzaniem.

Mieszany encoding w tym samym feedzie

Najgorszy scenariusz: feed w UTF-8, ale kilka wierszy w Windows-1250 (bo importowane były z innego źródła). Parser widzi „krzaki" tylko w niektórych produktach. Diagnoza trudna — feed „prawie działa". Rozwiązanie: automatyczne wykrywanie encodingu per wiersz (biblioteki jak chardet dla Pythona), potem konwersja.

Praktyczna wskazówka

Zawsze na etapie integracji z nową hurtownią: zapisz kilka próbek feedu, otwórz w edytorze wspierającym encoding (VSCode, Notepad++), sprawdź BOM, sprawdź jak wyświetlają się polskie znaki. 30 minut ręcznej weryfikacji oszczędza tygodnie diagnozy „skąd te krzaki".

Częstotliwość aktualizacji feedu

To parametr, na który nie masz wpływu — decyduje hurtownia. Ale warto go znać, bo determinuje, jak często warto pobierać:

Feed aktualizowany raz dziennie

Najczęściej rano (04:00-08:00). Pobieranie częściej niż raz dziennie nie ma sensu — dostaniesz te same dane. Konfiguruj cron na 1-2h po wygenerowaniu feedu, żeby mieć aktualne dane, ale nie trafić w moment generowania.

Feed aktualizowany co 2-6 godzin

Środkowy standard branży. Pobieraj z tą samą częstotliwością — sensownie 15-30 min po każdym cyklu hurtowni.

Feed aktualizowany co 15-30 minut lub real-time (API)

Nowoczesne hurtownie, głównie te z REST API. Dla sklepów z produktami wysokorotacyjnymi (elektronika, niszowe produkty ograniczonej dostępności) — bezcenne. Dla produktów wolnorotacyjnych — overkill, zwiększa koszty bez proporcjonalnego zysku.

Nie synchronizuj częściej niż hurtownia generuje

Częsty błąd początkujących: pobieranie feedu co godzinę, gdy hurtownia generuje go raz dziennie. Efekt: 24 razy dziennie pobierasz i parsujesz ten sam plik. Marnowana infrastruktura, zbędne obciążenie hurtowni. Ustaw cron na częstotliwość dopasowaną do faktycznej częstotliwości źródła. Więcej o tym w wpisie o synchronizacji stanów z hurtowniami.

Częste błędy w feedach hurtowni

Realne przypadki, które napotkasz — im lepiej się przygotujesz, tym mniej godzin spędzisz na diagnozie:

Niekompletny plik

Hurtownia zapisała plik do końca, ale generowanie się przerwało. Plik istnieje, ale zawiera połowę produktów. Naiwny parser importuje niepełne dane, kończy z „aktualnymi stanami" które są fałszywe. Ochrona: weryfikuj oczekiwaną liczbę produktów (odchylenie >20% od poprzedniego = odrzuć feed).

Nagłe zerowanie stanów

Feed z 500 produktami — wszystkie mają stan 0. Realny scenariusz: hurtownia miała awarię, wygenerowała feed przed zaimportowaniem stanów. Sklep aktualizuje wszystko na 0, klient nic nie kupi. Ochrona: wykrywanie anomalii (spadek stanu >80% na wszystkich produktach jednocześnie = alarm, pauza synchronizacji).

Duplikaty SKU

Ten sam kod produktu pojawia się kilka razy w feedzie z różnymi stanami. Nie wiadomo, który jest aktualny. Zwykle błąd hurtowni w bazie danych. Rozwiązanie: log w takim przypadku i wybór ostatniego wiersza (albo max stanu — zależy od interpretacji).

Wartości w niewłaściwych typach

Stan magazynowy zamiast liczby to string „10 szt", cena zapisana jako „1 999,00 zł" (z jednostką i przecinkiem). Bez sanityzacji parser albo rzuca błąd, albo interpretuje niepoprawnie. Rozwiązanie: warstwa czyszczenia danych między parserem a importem — normalizacja liczb, walutami, jednostkami.

Zmiany schematu bez ostrzeżenia

Hurtownia dodała nowe pole, usunęła istniejące, przemianowała atrybut. Twój parser sypie błędami od dnia zmiany. Ochrona: monitoring liczby błędów parsowania. Wzrost >5% = sygnał sprawdzenia. Dobra praktyka: mieć wersjonowanie schemy i alertować przy nieoczekiwanym field.

Feed w innym języku niż polski

Hurtownia międzynarodowa dostarcza feed w angielskim. Nazwy i opisy trzeba przetłumaczyć przed importem. Automatyczne tłumaczenie (opisane w wpisie o opisach AI) może być odpowiedzią.

Rekomendacje — który format wybrać

W praktyce często nie masz wyboru — hurtownia oferuje jeden lub dwa formaty. Ale gdy masz opcje, oto zalecenia:

Sklep z 1-2 hurtowniami, standardowy asortyment

Wybieraj XML. IdoSell natywnie obsłuży najpopularniejsze schematy, konfiguracja w panelu, gotowe w kilka dni. Bez custom kodu, bez kosztów utrzymania.

Sklep z 3+ hurtowniami, dużym asortymentem

Rozważ dedykowane narzędzie (własne lub SaaS) do agregacji feedów z różnych formatów. Jednolity interfejs, wspólna logika (mapowanie SKU, priorytety multi-supplier, reguły bezpieczeństwa). Praktykę wdrożenia opisaliśmy w wpisie o synchronizacji stanów z hurtowniami.

Sklep z produktami wysokorotacyjnymi

Wybieraj hurtownie z REST API. Delta sync i możliwość odpytania w dowolnej chwili znacznie redukuje ryzyko oversoldu. Koszt integracji wyższy niż XML, ale zwraca się w mniejszej liczbie anulowanych zamówień.

Sklep na start bez zespołu technicznego

Trzymaj się XML z natywną integracją IdoSell. Bez potrzeby developera, bez custom kodu. Ograniczenie: musisz wybrać hurtownię, którą IdoSell wspiera natywnie. Lista popularnych polskich hurtowni z gotową integracją jest długa — zwykle znajdziesz swoją.

Kiedy warto zainwestować w custom integrację

Hurtownia nietypowa (nie obsługiwana natywnie), specyficzne wymagania biznesowe (reguły warunkowe, multi-supplier z priorytetami, agregacja stanów), potrzeba real-time. Wtedy własne narzędzie lub zamówione u agencji. Koszt: 5-15 tys. zł zależnie od skomplikowania (szerzej w wpisie o kosztach wdrożenia sklepu IdoSell).

Podsumowanie

Wybór formatu feedu hurtowni to nie „drobiazg techniczny" — to decyzja wpływająca na wydajność synchronizacji, koszty utrzymania i ryzyko błędów operacyjnych. Kluczowe wnioski:

XML — standard w PL, natywne wsparcie IdoSell, dobrze modeluje warianty; minus: duże pliki, brak delty

CSV — lekki i szybki, ale zdradliwy (encoding, brak standardu, słabo z wariantami)

REST API — najnowocześniejszy, delta sync, real-time; minus: nie każda hurtownia oferuje, rate limity

Sposób dostarczenia (FTP, HTTP, API, webhook) to osobny wymiar od formatu

Encoding to najczęstsze źródło błędów — sprawdzaj na starcie integracji

Częstotliwość pobierania dostosuj do częstotliwości generowania feedu

Buduj ochronę przed anomaliami (niekompletny plik, nagłe zerowania, duplikaty)

W IdoScale piszemy custom integracje z hurtowniami od lat — od standardowych XML po niestandardowe multi-format setupy. Jeśli planujesz integrację z niekonwencjonalną hurtownią lub potrzebujesz agregacji feedów z wielu źródeł — porozmawiajmy o Twoim scenariuszu.