Integracja sklepu z hurtownią: XML, API, stany i zamówienia

Dobra integracja z hurtownią sprawia, że w Twoim sklepie widać tylko towar, który dostawca naprawdę ma, po cenie, na której zarabiasz, a zamówienie klienta trafia do hurtowni bez przepisywania. Numer przesyłki wraca do zamówienia sam. Poniżej opis, z czego składa się integracja sklepu z hurtownią, gdzie leży źródło prawdy dla każdego rodzaju danych i co ma się stać, gdy plik dostawcy przyjdzie pusty albo w połowie.

Trzy sposoby, w jakie hurtownia udostępnia dane

Często hurtownia daje dwa źródła naraz: pełny plik produktów raz na dobę i lekki plik stanów co godzinę. Integracja traktuje je osobno, bo mają różną częstotliwość i różne skutki błędu.

Zamówienia do hurtowni idą jedną z dróg: przez API, przez panel B2B dostawcy, mailem w ustalonym formacie albo plikiem. Numer przesyłki wraca przez API, w pliku statusów albo mailem. Sprawdź to u dostawcy przed projektowaniem, bo od tego zależy, ile da się zautomatyzować.

Integracja z hurtownią: kto jest źródłem prawdy

Najczęstszy błąd: import nadpisuje wszystko przy każdym przebiegu. Ręcznie poprawiony opis, zdjęcie albo cena znikają po godzinie. Każde pole ma przypisanego właściciela, a import zapisuje tylko pola, które należą do hurtowni.

Co integracja musi robić

1. Pobrać i sprawdzić feed. Kod odpowiedzi, rozmiar pliku, poprawność XML albo liczba kolumn CSV, kodowanie znaków. Plik, który nie przechodzi kontroli, nie jest importowany.
2. Dopasować produkty po EAN albo po kodzie dostawcy, nigdy po nazwie. Ten sam EAN u dwóch hurtowni to jeden produkt w sklepie z dwoma źródłami.
3. Zmapować kategorie i atrybuty. Tabela „kategoria dostawcy → Twoja kategoria”, tabela atrybutów (kolor, rozmiar, moc). Produkt z kategorią bez mapowania nie trafia do sprzedaży, tylko na listę do przypisania.
4. Policzyć stan do sprzedaży. Stan u dostawcy minus bufor, plus Twój stan magazynowy, jeśli masz towar u siebie. Dla „dużo / mało / brak” zamiast liczb potrzebna jest reguła przeliczenia.
5. Policzyć cenę sprzedaży. Koszt zakupu plus marża według reguły (procent, kwota, progi), z doliczeniem kosztu wysyłki z hurtowni i prowizji kanału. Cena ręczna jest zablokowana przed nadpisaniem, a spadek zysku poniżej progu wysyła alert.
6. Uzupełnić dane wymagane w sprzedaży: stawkę VAT, producenta i dane GPSR, jeśli dostawca je przekazuje. Brak danych blokuje publikację.
7. Wysłać zamówienie do hurtowni po opłaceniu albo po akceptacji, tylko z pozycjami tej hurtowni, z adresem klienta przy wysyłce bezpośredniej.
8. Odebrać potwierdzenie, status i numer przesyłki i zapisać je w zamówieniu, żeby klient dostał powiadomienie.
9. Obsłużyć brak towaru po złożeniu zamówienia: odpowiedź „brak” od hurtowni zmienia status i zakłada zadanie dla obsługi.

Przepływ danych

flowchart LR
  feed["Hurtownia
XML / CSV / API"] -->|"produkty, stany, koszt"| imp["Import
kontrola pliku"]
  imp --> ok{"Feed kompletny?"}
  ok -->|"nie"| hold["Wstrzymaj import
alert, ostatni dobry stan"]
  ok -->|"tak"| map["Mapowanie
EAN, kategorie, atrybuty"]
  map --> price["Stan do sprzedaży,
cena z marżą"]
  price --> shop["Sklep / Base"]
  shop -->|"zamówienie opłacone"| out["Kolejka zamówień
do dostawcy"]
  out -->|"zamówienie (raz)"| feed
  feed -.->|"status, numer przesyłki"| out
  out -.->|"tracking"| shop
  classDef n fill:#eff6ff,stroke:#2563eb,color:#0f172a;
  classDef w fill:#fef2f2,stroke:#b91c1c,color:#0f172a;
  class feed,imp,ok,map,price,shop,out n;
  class hold w;

Integracja sklepu z hurtownią przez Base (BaseLinker)

Base (BaseLinker) ma integracje z hurtowniami i import produktów z plików XML i CSV. Zanim zlecisz integrację dedykowaną, sprawdź w panelu Base, czy Twój dostawca jest na liście i co obejmuje jego integracja: same produkty i stany, czy też zamówienia i statusy. Zakres, jaki daje integracja BaseLinker z hurtowniami, różni się między dostawcami.

Integracja dedykowana ma sens, gdy:

• hurtownia ma API do zamówień, a gotowa integracja go nie używa,
• potrzebujesz reguły marży z progiem zysku i blokadą cen ręcznych,
• jeden produkt jest u kilku dostawców i chcesz wybierać źródło po cenie albo stanie,
• feed ma strukturę, której import z pliku nie przetwarza poprawnie,
• zamówienia mają trafiać do hurtowni zbiorczo, o ustalonej godzinie.

Więcej o tym, gdzie kończą się możliwości gotowych narzędzi: kiedy BaseLinker przestaje wystarczać.

Idempotencja: jedno zamówienie u dostawcy

Podwójne zamówienie w hurtowni to podwójna wysyłka do klienta i koszt zwrotu. Zdarza się, gdy integracja wysyła zamówienie, nie dostaje odpowiedzi w limicie czasu i ponawia.

• Klucz zamówienia u dostawcy: id zamówienia w sklepie + id hurtowni, unikalny w bazie integracji. Jedno zamówienie klienta z produktami od dwóch hurtowni daje dwa zamówienia u dostawców, każde z własnym kluczem.
• Twój numer w zamówieniu u dostawcy. Jeśli API hurtowni przyjmuje numer zewnętrzny, integracja go wysyła. Po timeoucie najpierw szuka zamówienia po tym numerze, dopiero potem ponawia.
• Brak numeru zewnętrznego w API albo zamówienie mailem: po timeoucie integracja nie ponawia automatycznie, tylko zakłada zadanie „sprawdź u dostawcy”. Ręczne sprawdzenie jest tańsze niż podwójna paczka.
• Import też ma być powtarzalny. Ten sam plik zaimportowany dwa razy daje ten sam wynik: bez nowych kopii produktów, bez podwójnych zdjęć.

Awarie feedu i dostawcy

Pusty albo ucięty plik. Hurtownia w trakcie generowania pliku zwraca połowę produktów. Import, który brakujące produkty uznaje za wycofane, w jednej chwili zeruje stany połowy sklepu. Zabezpieczenie: próg zmian. Jeśli plik ma o kilkanaście procent mniej pozycji niż poprzedni albo zmienia stan większej części katalogu niż zwykle, import się zatrzymuje, sklep zostaje z ostatnim dobrym stanem, a Ty dostajesz alert. Próg ustalasz po obserwacji kilku dni normalnej pracy.

Feed niedostępny. Błąd serwera, timeout, zmiana adresu. Ponowienia z rosnącym odstępem. Jeśli ostatni udany import jest starszy niż ustalony limit, produkty z tej hurtowni z małym stanem dostają stan zero albo są wstrzymane. Sprzedaż na podstawie stanu sprzed doby kończy się anulowaniami.

Zmiana struktury pliku. Dostawca zmienia nazwę pola albo format ceny. Kontrola pliku sprawdza obecność wymaganych pól i typy wartości. Cena 0, cena ujemna albo cena zakupu wyższa o kilkaset procent niż wczoraj blokuje aktualizację danego produktu.

API zamówień niedostępne. Zamówienia czekają w kolejce z czasem złożenia i wychodzą po przywróceniu, w kolejności. Jeśli przerwa przekracza godzinę odcięcia dostawcy na wysyłkę tego samego dnia, obsługa dostaje informację.

Brak numeru przesyłki. Zamówienie u dostawcy bez numeru po ustalonym czasie trafia na listę do sprawdzenia. Klient pyta o paczkę, zanim Ty to zauważysz, jeśli tej listy nie ma.

Limity API. Pytanie o stan każdego produktu osobno przy kilku tysiącach pozycji szybko przekracza limit. Integracja pobiera dane zbiorczo, jeśli API na to pozwala, i respektuje odpowiedzi o przekroczeniu limitu.

Bezpieczeństwo

• Klucze API i hasła do paneli B2B w zaszyfrowanej konfiguracji integracji, nie w adresie URL w arkuszu i nie w mailu. Jeśli hurtownia podaje klucz w adresie feedu, traktuj cały adres jak hasło.
• Osobne konto do integracji u dostawcy, jeśli to możliwe, z uprawnieniami tylko do pobierania danych i składania zamówień.
• Dane klientów (adres, telefon) wysyłasz do hurtowni tylko przy wysyłce bezpośredniej i tylko w zakresie potrzebnym do doręczenia. Ustal to z dostawcą w umowie powierzenia danych.
• Rotacja kluczy po zmianie osób z dostępem i po podejrzeniu wycieku.
• Audit log: każdy import (czas, liczba pozycji, liczba zmian, wynik kontroli) i każde zamówienie do dostawcy (czas, klucz, odpowiedź). Bez sekretów w logu. Szerzej: audit log w wymianie danych.

Monitoring

Lista kontrolna przed uruchomieniem

1. Plik z połową pozycji zatrzymuje import, a stany w sklepie zostają bez zmian.
2. Plik z błędną strukturą (brak pola ceny) nie zmienia żadnej ceny.
3. Ten sam plik zaimportowany dwa razy nie tworzy nowych produktów ani zdjęć.
4. Ręcznie zmieniony opis i zablokowana cena zostają po imporcie.
5. Wzrost ceny zakupu, który obniża zysk poniżej progu, wysyła alert.
6. Produkt z nową kategorią dostawcy trafia na listę do przypisania, nie do sprzedaży.
7. Zamówienie z produktami od dwóch hurtowni daje dwa zamówienia u dostawców.
8. Timeout przy wysyłce zamówienia nie tworzy drugiego zamówienia u dostawcy.
9. Numer przesyłki od hurtowni pojawia się w zamówieniu i w powiadomieniu dla klienta.
10. Odpowiedź „brak towaru” zmienia status i zakłada zadanie dla obsługi.

Testy prowadzisz na kopii sklepu i, jeśli dostawca to umożliwia, na jego środowisku testowym albo na zamówieniu testowym uzgodnionym z opiekunem.

FAQ

Czy Base ma integracje z hurtowniami? Tak, Base ma integracje z wieloma hurtowniami i import produktów z plików XML i CSV. Zakres (produkty, stany, zamówienia, statusy) zależy od konkretnego dostawcy, więc sprawdź go w panelu przed decyzją.

Jak często pobierać plik z hurtowni? Stany tak często, jak hurtownia aktualizuje plik, zwykle co godzinę lub częściej przy szybko rotującym towarze. Pełny katalog raz na dobę. Częstsze pobieranie nie pomoże, jeśli dostawca generuje plik rzadziej.

Co zrobić, gdy hurtownia nie ma API do zamówień? Zamówienia mogą wychodzić mailem w stałym formacie albo plikiem. Wtedy numer przesyłki często trzeba odbierać z pliku statusów albo maila, a część kontroli zostaje ręczna.

Czy import może poprawiać opisy z hurtowni? Może utworzyć opis przy pierwszym imporcie. Potem opis należy do Ciebie i import go nie nadpisuje. Unikalny opis pomaga stronie produktu w wyszukiwarce.

Jak połączyć kilka hurtowni z jednym sklepem? Każda hurtownia ma własny import i własne mapowanie, a produkty łączy EAN. Reguła wyboru źródła (np. tańszy dostawca z dostępnym stanem) decyduje, do kogo trafia zamówienie.

Powiązane

• Sklep na Commerce OS: dropshipping z dwóch hurtowni, import XML co godzinę
• Synchronizacja produktów
• Synchronizacja stanów magazynowych
• Automatyzacja zamówień
• Wdrożenie Base z integracją ERP

Od 2015 roku budujemy systemy i logikę wymiany danych. Napisz, z jakiej hurtowni korzystasz i w jakim formacie dostajesz dane, a odpowiemy, co da się połączyć gotowym narzędziem, a co wymaga integracji.