Integracja z hurtownią — CSV, XML/IOF czy API dla sklepu internetowego

Integracja z hurtownią to synchronizacja dwóch rodzajów danych, które zmieniają się w zupełnie innym tempie. Oferta — nazwy, opisy, zdjęcia, kategorie — zmienia się rzadko, czasem raz na tydzień albo jeszcze rzadziej. Stany magazynowe i ceny zmieniają się często: u jednych hurtowni co godzinę, u innych w czasie rzeczywistym. Wybór między CSV, XML (często w konkretnym standardzie, jak IOF u IdoSell) a API nie jest więc kwestią mody technologicznej. Wynika z tego, jak często dane się zmieniają i jak szybko musisz na tę zmianę reagować.

Co właściwie synchronizujesz z hurtownią

Ofertę i stany z cenami synchronizujesz osobno, bo każde z nich wymaga innego mechanizmu. Plik aktualizowany raz w tygodniu może być ręcznie wgrywanym CSV bez żadnej automatyzacji. Dane, które muszą być aktualne w ciągu minut — stan produktu na granicy wyprzedania, cena u hurtowni zmieniającej cenniki kilka razy dziennie — wymagają mechanizmu cyklicznego albo API. Przy ręcznym imporcie raz dziennie przez część dnia sprzedajesz towar, którego hurtownia już nie ma, albo po cenie, która już nie obowiązuje.

Do oferty należą nazwa produktu, opis, zdjęcia, kategoria i atrybuty (kolor, rozmiar, materiał). Zmieniają się dopiero wtedy, gdy hurtownia dodaje nowy produkt albo poprawia błąd w opisie. Do stanu i ceny należą dostępna ilość i cena zakupu (albo cena sugerowana, jeśli hurtownia ją podaje). Te pola mogą zmieniać się kilka razy dziennie, nawet gdy sam produkt pozostaje bez zmian.

Nie musisz więc budować jednej integracji dla obu rodzajów danych — i zwykle nie warto. Ofertę możesz importować jednym mechanizmem (np. cyklicznym CSV raz w tygodniu), a stan i cenę innym, częstszym (np. plikiem XML co godzinę albo przez API w czasie rzeczywistym). Upchnięcie obu w jednym, rzadko uruchamianym imporcie to częsty powód, dla którego stan w sklepie rozjeżdża się z rzeczywistością u hurtowni. Mechanizm działa poprawnie, tylko dane o różnym tempie zmian trafiły do jednego harmonogramu.

CSV — najprostszy format, z jednym mitem do obalenia

CSV obsługuje każda platforma sklepowa, a hurtownia wyeksportuje go z własnego systemu bez dedykowanej integracji. Różnice między platformami dotyczą szczegółów pliku.

Shopify. Dokumentacja opisuje wymagania formalne pliku: „save your CSV file in UTF-8 format using LF-style linefeeds”, kolumny rozdzielone przecinkiem, w pierwszym wierszu nagłówki kolumn (help.shopify.com/en/manual/products/import-export/using-csv, odczyt 2026-10-05). Zdjęcia nie są częścią pliku: „A CSV file can only contain text” i „You can use only image URLs in CSV files”, a same zdjęcia muszą być publicznie dostępne pod adresem https://, bez ochrony hasłem. Żadna z trzech stron dokumentacji Shopify o imporcie (import CSV, przegląd importu i eksportu, typowe problemy) nie podaje maksymalnego rozmiaru pliku w MB. Często powtarzany limit 15 MB nie ma więc oparcia w aktualnej dokumentacji. Jedyny konkretny limit dotyczy sklepów z co najmniej 500 000 wariantów (poza sklepami Plus): mogą utworzyć najwyżej 10 000 nowych wariantów w ciągu 24 godzin przez CSV albo API.

WooCommerce. Wbudowany importer CSV produktów nie ma własnego, stałego limitu wielkości: „The Maximum size value shown on the upload screen is set at the server level” (woocommerce.com/document/product-csv-importer-exporter, odczyt 2026-10-05). Limit podniesie dostawca hostingu. Przed dużym importem dokumentacja radzi zrobić kopię zapasową, przetestować mały import na kopii sklepu (stagingu) i podzielić plik na mniejsze partie, w których łatwiej znaleźć błąd. Wymagane kolumny to SKU (jeśli ją pominiesz, WooCommerce wygeneruje własne) i Name; reszta jest opcjonalna. Produkt wariantowy importujesz jako wiersz nadrzędny plus wiersze wariantów, powiązane kolumną Parent, SKU i atrybutami. Zamianę istniejącego produktu prostego na wariantowy od WooCommerce 11.1 robisz jednym importem, jeśli wiersz nadrzędny stoi w pliku przed swoimi wariantami. W starszej wersji albo gdy nie kontrolujesz kolejności wierszy potrzebne są dwa przebiegi: najpierw produkt z atrybutami, potem warianty.

PrestaShop. Import wymaga pliku CSV, z rekomendowanym separatorem średnikowym („We recommend using a semicolon ';' as a field separator”), w kodowaniu UTF-8 (alternatywnie ISO-8859-1) i z datami w formacie ISO 8601 (docs.prestashop-project.org, odczyt 2026-10-01). Limitu wielkości pliku ta strona nie podaje (odczyt 2026-10-05). Dokumentacja podaje przykładowy nagłówek dla produktów: "Enabled";"Name";"Categories";"Price";"Tax rule ID";"Buying price";"On sale";"Reference";"Weight";"Quantity";"Short desc.";"Long desc";"Images URL". Kolumna Reference odpowiada SKU, a Images URL przyjmuje adresy, nie pliki — tak jak w Shopify i WooCommerce. Dane importujesz dla jednego języka na raz, więc katalog wielojęzyczny wymaga tylu importów, ile jest języków. Integracja PrestaShop z hurtowniami zaczyna się od tego samego importu CSV: dokumentacja nie opisuje osobnej, wbudowanej ścieżki dla hurtowni, a hurtownie różnią się formatem pliku (separator, kodowanie, nazwy kolumn). Jeśli stany i ceny mają się zmieniać częściej, niż jesteś w stanie wgrywać plik, potrzebujesz API albo integratora — opisanych niżej.

XML i IOF — kiedy CSV nie wystarcza

XML przydaje się, gdy dane mają strukturę, której CSV nie oddaje dobrze: zagnieżdżone kategorie, warianty powiązane z produktem nadrzędnym, wiele zdjęć na produkt w jednym pliku. W polskim e-commerce najczęściej spotykany nazwany standard to Internet Offer Format (IOF) promowany przez IdoSell. Strona dla deweloperów opisuje go jako „pierwszy tworzony przez praktyków kompletny standard wymiany informacji o towarach w formacie XML” (idosell.com/pl/developers/otwarte-standardy-i-api-do-integracji/internet-offer-format-iof, odczyt 2026-10-05). Standard składa się z kilku plików, m.in. gateway.xml, full.xml, light.xml, categories.xml i stocks.xml.

Hurtownie działające poza platformą IdoSell obsługuje narzędzie IAI Downloader: na podstawie ich plików CSV albo XML generuje ofertę w formacie IOF, która trafia do panelu i jest potem automatycznie synchronizowana. Hurtownie działające na IdoSell mają krótszą drogę — gotowy plik gateway.xml, wskazywany jako adres URL, z automatyczną synchronizacją. Jak pisze pomoc IdoSell: „Hurtownie działające na platformie IdoSell, posiadają gotowy mechanizm udostępniania oferty do integracji” (pomoc.idosell.com/towary/iai-downloader/integracja-z-hurtownia, odczyt 2026-10-05).

W obiegu są dwie wersje standardu. Instrukcja pomocy dla ścieżki gateway.xml wymaga pliku IOF 2.6, a dokumentacja dla deweloperów podaje IOF 3.0 jako najnowszą, rekomendowaną wersję. Strona poprzednich wersji zaznacza przy tym, że 2.6 jest nadal wspierana przez aplikację Downloader i IdoSell (changelog IOF, odczyt 2026-10-01). Przy integracji z konkretną hurtownią sprawdź, której wersji używa jej plik, zamiast zakładać jedną.

Dokumentacja IdoSell ostrzega też, że niektóre generatory plików CSV/XML po stronie hurtowni tworzą dane, których narzędzie importujące nie odczyta poprawnie. Wtedy zaleca zapisać oryginalny plik i wskazać go ręcznie zamiast linku.

API i integratory — kiedy potrzebujesz synchronizacji w czasie rzeczywistym

Jeśli zmiana stanu u hurtowni musi dotrzeć do sklepu w ciągu minut, a nie godzin, cykliczny plik przestaje wystarczać. Wtedy potrzebujesz API albo integratora, który synchronizację zrobi za Ciebie. W Polsce to przede wszystkim Base.com, Sellasist i Apilo — platformy łączące sklep, marketplace'y (głównie Allegro) i magazyn albo hurtownię w jednym panelu. Częstotliwość synchronizacji zależy od produktu i planu:

• Base.com w darmowym planie Freemium (do 100 zamówień miesięcznie i do 1000 produktów) synchronizuje zamówienia, stany i ceny co godzinę, a w płatnym planie Business — w czasie rzeczywistym (base.com/pl-PL/cennik, odczyt 2026-10-05).
• Apilo w standardzie synchronizuje stany i ceny co 1–4 godziny, zależnie od planu; w najtańszym planie Starter stany co 2 godziny, a ceny co 4 godziny. Tryb „na żywo” to płatny dodatek, osobno dla stanów i dla cen, od 59 do 349 zł miesięcznie każdy, zależnie od planu (apilo.com/pl/cennik-apilo, odczyt 2026-10-05).
• Sellasist podaje synchronizację stanów i cen „Maks. 10 minut – bez dodatkowych opłat”, zarówno w pakiecie darmowym, jak i w abonamencie. Kwota abonamentu zależy od liczby zamówień i/lub aktywnych ofert w poprzednim miesiącu kalendarzowym, a skala progów sięga ponad 10 000 zamówień miesięcznie (sellasist.pl/cennik, odczyt 2026-10-05).

Base.com rozróżnia też, co można zaimportować jako plik, a co wymaga dedykowanego modułu: „Produkty do magazynu Base.com można importować z pliku XML, tylko jeżeli ma on znaną Base.com strukturę (np. format Ceneo). […] Możliwy jest natomiast import z dowolnego pliku CSV”. Import XML działa więc tylko dla rozpoznanych formatów, a do podłączenia konkretnej hurtowni Base.com poleca gotowy moduł Hurtownie, z ponad 600 zintegrowanymi hurtowniami (base.com/pl-PL/integracje-connect, odczyt 2026-10-05).

Pełne porównanie cenników i funkcji tych integratorów przy sprzedaży na Allegro znajdziesz w tekście o integracji sklepu z Allegro. Tu liczy się jedno: wybierając integrator, wybierasz w praktyce częstotliwość synchronizacji, a nie tylko listę obsługiwanych hurtowni.

Integracja Allegro z hurtownią i koszt podłączenia hurtowni

Ofertę hurtowni wystawisz na Allegro przez integrator: hurtownia zasila jego magazyn, a z magazynu powstają oferty. Base.com opisuje to jako wystawianie produktów „z dowolnego magazynu (sklepu, hurtowni, ERP lub magazynu Base.com)” i dodaje automatyczne przekazywanie zamówień dropshippingowych, z zastrzeżeniem „dot. części hurtowni” (base.com/pl-PL/cennik, odczyt 2026-10-05). Stan i cena w ofercie na Allegro są wtedy tak aktualne, jak pozwala plan integratora opisany wyżej.

Samo podłączenie hurtowni bywa osobną pozycją w cenniku, a różnice między integratorami są duże:

• Base.com — hurtownie działające w oparciu o Base Connect podłączysz bez limitu i bez dodatkowych opłat, w każdym planie. Hurtownię zintegrowaną inaczej, np. plikiem integracyjnym, podłączysz bez opłat tylko jedną; każda kolejna wymaga planu Business i kosztuje 50 zł miesięcznie (base.com/pl-PL/cennik, odczyt 2026-10-05).
• Apilo — utrzymanie połączenia z jedną hurtownią kosztuje 59 zł miesięcznie, przy czym co piąta hurtownia jest gratis. Podłączenie hurtowni spoza listy to opłata jednorazowa od 599 zł: 300 zł za analizę płatne z góry plus wdrożenie od 299 zł (apilo.com/pl/cennik-apilo, odczyt 2026-10-05).

Przy kilku hurtowniach ta pozycja potrafi przekroczyć różnicę w cenie samych planów. Zanim wybierzesz integrator, sprawdź, czy Twoje hurtownie są na jego liście gotowych integracji. Hurtownia spoza listy oznacza jednorazowy koszt wdrożenia albo własny import pliku.

Dropshipping — ten sam mechanizm, wyższe wymagania co do aktualności

Dropshipping nie zmienia logiki integracji, tylko zaostrza wymagania co do częstotliwości. Zamówienie złożone w Twoim sklepie trafia automatycznie do hurtowni (przez API albo plik wymiany zamówień), hurtownia pakuje towar i wysyła go prosto do klienta, a Ty nie trzymasz zapasu. Jeśli stan hurtowni synchronizuje się raz dziennie, ryzyko sprzedania towaru, którego już nie ma, jest wyższe niż przy własnym magazynie — bo między zamówieniem klienta a realizacją nie masz drugiej warstwy kontroli w postaci własnego stanu fizycznego.

Dropshipping zmienia też obieg dokumentów. Zwykle to Ty, jako sprzedawca widoczny dla klienta, wystawiasz fakturę albo paragon, choć towar nie przeszedł przez Twój magazyn. Hurtownia wystawia własny dokument sprzedaży Tobie, jako odbiorcy B2B. Te dwa dokumenty żyją w dwóch systemach i nie muszą się zgadzać numerem ani datą. Jeśli ich obieg nie jest ustalony z góry, łatwo o rozjazd w księgowości. Kto powinien być właścicielem którego dokumentu przy integracji z ERP — piszemy w tekście o integracjach ERP/WMS/CRM.

Feed produktowy do Google — osobna rzecz od importu z hurtowni

Import z hurtowni zasila Twój katalog, a feed do Google Merchant Center budujesz z tego katalogu, nie z surowego pliku hurtowni. Google akceptuje trzy formaty: „Delimited text files: .txt (tab-delimited text) or .tsv (tab-separated values). XML files: .xml”. Pojedynczy plik może mieć do 4 GB (support.google.com/merchants/answer/12631822, odczyt 2026-10-05); limitu liczby produktów w pliku strona nie podaje. Plik możesz przesyłać ręcznie, ale wtedy wgrywasz go po każdej zmianie. Merchant Center umie też pobierać plik ze stałego adresu URL — domyślnie co 24 godziny, z możliwością zmiany harmonogramu (support.google.com/merchants/answer/12158380, odczyt 2026-10-01). Działa to jak gateway.xml przy IOF: wskazujesz adres raz, a system sam go cyklicznie odpytuje. Wymagania co do treści feedu — limity tytułu i opisu, GTIN, zdjęcia — opisujemy w tekście o Google Merchant Center.

Typowe błędy przy integracji z hurtownią

• Duplikaty SKU — hurtownia używa tego samego identyfikatora dla produktu bazowego i jego wariantu, mapowanie w sklepie tego nie rozdziela, więc warianty nadpisują się przy każdej synchronizacji.
• Niezgodność kodowania — plik w ISO-8859-1 importowany jako UTF-8 (albo odwrotnie) zamienia polskie znaki w nazwach i opisach w nieczytelne ciągi.
• Pomylona cena netto i brutto — hurtownia wysyła cenę netto, sklep traktuje ją jako brutto (albo odwrotnie). Marża psuje się na całym katalogu, a import nie zgłasza żadnego błędu.
• Wyścig między synchronizacją stanu a zamówieniem klienta — przy aktualizacji stanu co godzinę w tej godzinie można sprzedać towar, którego hurtownia już nie ma. Ryzyko rośnie przy wysokiej rotacji i przy dropshippingu.
• Zdjęcia pod niepublicznym albo tymczasowym adresem — jeśli adresy zdjęć w CSV wskazują serwer hurtowni, który wygasa albo blokuje dostęp z zewnątrz, produkty lądują w sklepie bez zdjęć, choć import „się powiódł”.
• Jeden plik dla wielu języków — gdy importer (jak PrestaShop) obsługuje jeden język na przebieg, plik z kolumnami dla kilku języków kończy się błędem albo importem tylko jednego języka, zależnie od narzędzia.
• Wspólny harmonogram dla oferty i stanów — jeśli oba procesy idą w jednym, rzadkim cyklu, stan i cena są nieaktualne tak długo, jak rzadko odświeżasz ofertę, choć mogłyby się aktualizować znacznie częściej.

Większość tych błędów nie daje komunikatu „import się nie powiódł”. Plik wczytuje się bez problemu, a błąd widać dopiero w efekcie: w złej cenie, brakującym zdjęciu albo sprzedanym produkcie, którego już nie ma. Dlatego prowadź prosty log każdej synchronizacji (liczba zaktualizowanych pozycji, liczba błędów, czas trwania) i porównuj go z poprzednim przebiegiem. Nagły spadek liczby zaktualizowanych pozycji, nawet bez błędu, zwykle oznacza zmianę po stronie hurtowni — formatu pliku, adresu URL albo układu kolumn — zanim zauważysz ją w sklepie.

Jeśli nie wiesz, czy przy Twojej wielkości katalogu warto budować pełną automatyczną integrację (API, synchronizacja w czasie rzeczywistym), czy wystarczy cykliczny import CSV, sprawdź to w kalkulatorze kosztu sklepu internetowego. Uwzględnia liczbę SKU i integracje, w tym z ERP, więc zobaczysz, jak obie zmienne przesuwają budżet.

Gdzie integracja z hurtownią wpisuje się w resztę operacji sklepu — razem z ERP, WMS i automatyzacją — pokazujemy w dziale operacji e-commerce.