Integracja z hurtownią - co trzeba ustalić, zanim cokolwiek zaprogramujesz

Publikacja: 30 września 2026 · Grzegorz Rapczyński

Integracja z hurtownią to najczęściej zamawiana u mnie robota integracyjna i jednocześnie ta, przy której najwięcej zależy od rozmowy przed rozpoczęciem. Techniczna strona to zwykle mniejsza część projektu. Większa to decyzje biznesowe, których nikt nie podjął.

Poniżej lista rzeczy, które ustalam, zanim napiszę pierwszą linijkę.

Co dostajesz od hurtowni

Pierwsze pytanie i zwykle najbardziej rozczarowujące. Hurtownie udostępniają dane w bardzo różnej jakości:

• API - najlepsze, bo pozwala pytać o pojedynczy produkt i pobierać zmiany. Rzadkość poza największymi.
• Plik XML lub CSV pod adresem - najczęstszy wariant. Cały katalog naraz, odświeżany co jakiś czas.
• Plik na FTP - to samo, tylko trudniejsze w automatyzacji.
• Plik wysyłany mailem - zdarza się i wtedy pierwsza część roboty to wyciągnięcie go ze skrzynki.

Drugie pytanie: jak często dane się zmieniają i jak często wolno je pobierać. Część hurtowni ogranicza liczbę pobrań albo aktualizuje plik raz dziennie - wtedy integracja co godzinę nie ma sensu, tylko obciąża.

Trzecie: co jest w pliku, a czego nie ma. Stany i ceny zwykle są. Opisy, zdjęcia, parametry techniczne i kody EAN - bardzo różnie. Brakujące dane trzeba będzie uzupełnić samemu i to zwykle największa część pracy.

Stany magazynowe

Decyzje, które trzeba podjąć:

• Czy pokazujesz stan hurtowni jeden do jednego? Rzadko dobry pomysł - hurtownia ma 400 sztuk, klient zamawia 300, a Ty dowiadujesz się, że tyle jednak nie ma.
• Bufor bezpieczeństwa. Odejmij od stanu hurtowni kilka sztuk albo pokazuj maksymalnie dziesięć. Chroni przed sytuacją, w której towar znika między pobraniem pliku a zamówieniem.
• Własny magazyn plus hurtownia. Jeśli część towaru masz u siebie, integracja nie może nadpisywać tych stanów. To najczęstsza przyczyna katastrof: skrypt nadpisuje wszystko i sklep pokazuje zero na towarze leżącym w magazynie.
• Produkty z kilku hurtowni. Ten sam produkt u dwóch dostawców - sumować stany czy brać z tańszego? To decyzja biznesowa i musi być podjęta przed wdrożeniem.

Ceny i marża

Najrzadziej przemyślana część. Pytania:

• Czy ceny aktualizują się automatycznie? Jeśli tak, hurtownia podnosi cenę o 20% i Twój sklep robi to samo, bez Twojej wiedzy.
• Marża procentowa czy kwotowa? Procent na tanich produktach daje grosze, kwota na drogich wygląda absurdalnie. Zwykle potrzebne są progi.
• Zaokrąglanie. Cena zakupu 23,47 zł plus 35% to 31,68 zł. Zaokrąglenie do 32,90 wygląda lepiej i jeszcze poprawia marżę.
• Produkty z ceną narzuconą przez producenta. Muszą być wyłączone z automatycznego przeliczania.
• Co z promocjami? Jeśli ustawisz cenę promocyjną ręcznie, a integracja przeliczy ceny w nocy - promocja zniknie. To trzeba przewidzieć w projekcie.

Nowe produkty i te, które znikają

Dwie decyzje, obie ważniejsze, niż się wydaje.

Nowe produkty w pliku. Dodawać automatycznie czy czekać na Twoją akceptację? Automat oznacza, że hurtownia poszerza ofertę i Twój sklep dostaje 3000 produktów, których nie chcesz sprzedawać. Zwykle lepiej: nowe produkty trafiają do poczekalni, Ty decydujesz.

Produkty, które zniknęły z pliku. Nie kasować - wyłączać. Skasowany produkt to utracony adres, utracona pozycja w wyszukiwarce i błąd 404 dla każdego, kto miał do niego link. Wyłączony produkt da się włączyć z powrotem, gdy wróci do oferty.

Do tego trzecia sytuacja, o której łatwo zapomnieć: produkt zniknął z pliku, bo hurtownia miała awarię eksportu. Dlatego integracja powinna mieć zabezpieczenie: jeśli plik jest mniejszy niż zwykle o więcej niż jakiś procent, nie przetwarzaj go i wyślij alert.

Dopasowanie produktów

Po czym integracja rozpoznaje, że produkt z pliku to ten produkt w sklepie? Możliwości w kolejności od najlepszej:

1. Kod dostawcy zapisany przy produkcie - najpewniejszy i wymaga jednorazowego uzupełnienia.
2. Kod EAN - dobry, jeśli hurtownia go podaje i jest poprawny. Bywa, że nie jest.
3. Kod producenta - działa, ale różne hurtownie zapisują go różnie.
4. Nazwa - ostateczność. Dopasowanie po nazwie zawsze kiedyś zawiedzie.

Pole dostawcy w karcie produktu jest do tego stworzone - pisałem o nim przy producentach i dostawcach. Przy kilku hurtowniach to jedyny sposób, żeby utrzymać porządek.

Co się dzieje, gdy integracja padnie

Padnie. Hurtownia zmieni format pliku, zmieni adres, wyłączy serwer na weekend albo doda kolumnę, której nikt się nie spodziewał.

Trzy rzeczy, które muszą być w projekcie od początku:

• Log każdego uruchomienia - co pobrano, ile zmieniono, co się nie udało. Bez tego diagnoza po fakcie jest zgadywanką.
• Powiadomienie o błędzie. Mail przy niepowodzeniu. Integracja, która po cichu przestała działać trzy tygodnie temu, to najgorszy możliwy scenariusz - sklep sprzedaje towar, którego nie ma.
• Zasada: w razie wątpliwości nic nie rób. Lepiej zostawić stare stany niż wyzerować katalog na podstawie uszkodzonego pliku.

Jeśli hurtownia nie ma gotowego modułu albo Twoje reguły cenowe nie mieszczą się w żadnym z dostępnych, zostaje rozwiązanie pisane pod konkretny sklep. Piszę takie własne moduły do PrestaShop i wtedy integracja działa dokładnie według Twoich zasad, a nie według tego, co przewidział autor gotowca.

Jeśli po stronie firmy stoi system magazynowo-księgowy, a nie hurtownia, zasady są podobne, ale decyzje inne. Opisałem je przy integracji sklepu z systemem ERP.

Najczęstsze pytania

Ile trwa wdrożenie integracji z hurtownią?

Przy porządnym pliku i jasnych zasadach zwykle kilka dni. Przy pliku niskiej jakości, dopasowywaniu produktów po nazwie albo kilku hurtowniach naraz - kilka tygodni. Największą częścią pracy rzadko jest kod, a zwykle porządkowanie danych.

Czy lepiej gotowy moduł czy rozwiązanie pisane na miarę?

Jeśli hurtownia ma oficjalny moduł i Twoje zasady są standardowe - zaczynaj od modułu. Rozwiązanie własne ma sens przy nietypowych regułach cenowych, kilku źródłach naraz albo gdy moduł nie radzi sobie z wielkością katalogu.

Jak często aktualizować stany?

Zależy od rotacji. Przy wolno schodzącym towarze raz dziennie wystarczy. Przy towarze, który znika z hurtowni w kilka godzin, co godzinę lub częściej - o ile hurtownia na to pozwala.

Co z opisami i zdjęciami z hurtowni?

Opisy od hurtowni ma w swoim sklepie każdy, kto z niej bierze towar - to duplikat, który nie ma czym wygrać w wyszukiwarce. Warto traktować je jako punkt wyjścia i przepisywać przynajmniej dla najlepiej sprzedających się pozycji.

Planujesz integrację z hurtownią

Zacznijmy od pliku, który daje Twoja hurtownia - po jego obejrzeniu powiem, co da się zrobić automatycznie, a co trzeba będzie uzupełnić ręcznie. Napisz, z jakiej hurtowni bierzesz towar: formularz kontaktowy, 881 932 088 lub kontakt@grvision.pl.