API, XML i CSV to tylko techniczne nośniki. Najważniejsze jest to, które dane mają być źródłem prawdy, jak często są aktualizowane i co dzieje się, gdy hurtownia wysyła błędne SKU, brak EAN albo ujemny stan.
Porównanie API, XML i CSV
API daje największą kontrolę nad synchronizacją, ale wymaga tokenów, limitów, obsługi błędów, retry i monitorowania: BaseLinker 100 żądań/min, Shoper według nagłówków limitu (domyślnie 2 operacje na sekundę, w sprawdzanym sklepie 10) — przy 22 tys. produktów pełny odczyt to kilkadziesiąt minut. XML dobrze sprawdza się jako feed produktowy, szczególnie przy wielu polach i zdjęciach. CSV jest prosty, ale wrażliwy na separator, kodowanie, kolumny i niejednoznaczne wartości.
Limity API, które trzeba obsłużyć
- żądań do API BaseLinkera
- 100 / min
- operacji API Shopera: domyślnie 2, w sprawdzanym sklepie 10
- 2–10 / s
- produktów: pełny odczyt to kilkadziesiąt minut
- 22 tys.
Wybór formatu powinien zależeć od częstotliwości aktualizacji i jakości danych. Ceny oraz stany zwykle wymagają częstszej synchronizacji niż opisy, zdjęcia i kategorie. W naszym wdrożeniu B2B kopia stanów z BaseLinkera odświeża się cyklicznie, według harmonogramu, a ceny raz na dobę. Złożone zamówienie od razu obniża stan w platformie i trafia przez API do BaseLinkera, który zdejmuje stan z magazynu wskazanego na pozycji; pozostałe kanały dostają zmianę z BaseLinkera przy swojej synchronizacji. Gdy taki proces ma być stabilny i powtarzalny, rozwijamy go jako automatyzację importu i eksportu CSV/XML/API; dla Shopera osobno opisujemy import produktów CSV/XML.
Hybryda w naszym wdrożeniu B2B: inna częstotliwość dla każdego pola
Kopia stanów z BaseLinkera
odświeżana w sklepie
Ceny
rzadziej niż stany
Zamówienie obniża stan
w platformie od razu, w BaseLinkerze przez API
| Format | Kiedy wystarcza | Co sprawdzić |
|---|---|---|
| API | zamówienia, statusy, stany i procesy wymagające odpowiedzi systemu; częste aktualizacje, komunikacja dwukierunkowa, częściowe aktualizacje i logi | autoryzacja i tokeny, limity, retry, obsługa błędów, monitorowanie |
| XML | feed katalogu: zdjęcia, parametry i warianty; batchowe aktualizacje | wersja pliku, mapowanie, walidacja przed importem, raport zmian |
| CSV | prosty start i proste importy | separator, kodowanie, kolumny, niejednoznaczne wartości |
| Hybryda | produkty z XML/CSV, zamówienia lub stany przez API | nie trzeba wszystkiego robić jednym kanałem; każdy kanał potrzebuje własnych reguł pól |
Ustal, które dane mają pierwszeństwo
Przed integracją trzeba zdecydować, czy sklep ma tylko pobierać dane z hurtowni, czy także nadpisywać własne opisy, kategorie i zdjęcia. Bez tej decyzji pełne nadpisanie katalogu potrafi zniszczyć ręcznie przygotowane opisy, kategorie i treści SEO albo opublikować dane techniczne w formie nieczytelnej dla klienta. Gdy z tych danych korzystają także partnerzy handlowi, decyzja dotyczy całej platformy B2B.
Źródło prawdy może być inne dla różnych pól. ERP może kontrolować stany i ceny, hurtownia zdjęcia oraz parametry, a sklep opisy kategorii i SEO. Integracja musi to respektować. Jak taki podział pól wygląda przy połączeniu sklepu z systemem księgowo-magazynowym, opisuje strona o integracji ERP ze sklepem internetowym.
- ceny i stany zwykle powinny mieć osobne reguły aktualizacji
- opisy SEO nie powinny być bezmyślnie nadpisywane feedem hurtowni
- SKU i EAN muszą być stabilnymi identyfikatorami
- kategorie sklepu często wymagają własnego mapowania zamiast kopiowania drzewa hurtowni
Przy kilku dostawcach dochodzi reguła ceny dla każdego z nich: czy w sklepie ma być cena katalogowa dostawcy, czy cena zakupowa z narzutem, w jakiej walucie przychodzi i jak ją przeliczać, jak zaokrąglać oraz które ręczne ceny i promocje integracja ma zostawić bez zmian. Te same pytania dotyczą produktu, który ma kilka źródeł: trzeba ustalić, który dostawca wygrywa przy cenie, a który przy dostępności. Jak prowadzimy taki proces jako usługę, opisuje integracja sklepu z hurtownią.
Jedno pole od właściciela do logu: stan
- Właściciel
- ERP może kontrolować stany i ceny; sklep tylko pobiera wartość
- Kanał
- API – stany wymagają częstszej synchronizacji niż opisy, zdjęcia i kategorie (sekcja 01)
- Przed zapisem
- walidacja: błędny albo ujemny stan zatrzymuje paczkę, rekord trafia do raportu błędów (sekcja 03)
- Błąd zapisu
- retry dla timeoutów i chwilowych błędów API, bez tworzenia duplikatów (sekcja 04)
- Log
- co system zrobił, czego nie zrobił i dlaczego
Walidacja przed importem ogranicza chaos w sklepie
Każdy import powinien mieć etap kontroli. Sprawdzamy brakujące SKU, puste EAN-y, duplikaty, niepoprawne ceny, błędne stany, brak zdjęć, warianty bez produktu nadrzędnego i kategorie, których nie ma w sklepie.
Walidacja pozwala zatrzymać błędną paczkę danych przed zapisem produkcyjnym. Przy większych katalogach warto generować raport błędów i osobno listę rekordów gotowych do importu.
- kontrola obowiązkowych pól: SKU, nazwa, cena, stan, kategoria
- wykrywanie duplikatów SKU i EAN
- mapowanie kategorii hurtowni na strukturę sklepu
- dry-run przed zapisem i raport błędów dla operatora
- przy ryzykownych aktualizacjach możliwość cofnięcia partii importu
kontrola SKU, nazwa, cena, stan, kategoriabrak SKUrekord do raportu błędówduplikat EANrekord do raportu błędówujemny stanpaczka zatrzymana przed zapisemnowa kategoriakategorii nie ma w sklepie: mapowanie na strukturę sklepureszta paczkilista rekordów gotowych do importuIntegracja musi mieć logi, retry i obsługę błędów
Jeżeli integracja działa w tle, musi zostawiać ślad. Logi powinny pokazywać datę uruchomienia, liczbę przetworzonych rekordów, błędy API, timeouty, pominięte produkty i decyzje mappera. Bez tego nie da się odróżnić problemu w danych od awarii połączenia.
Retry powinien być kontrolowany. Nie można bez końca ponawiać błędnego zapisu zamówienia albo tworzyć duplikatów. Dobre integracje są idempotentne: ponowienie operacji nie tworzy drugiego zamówienia ani drugiego produktu, bo mają identyfikatory, blokady duplikacji i jasne statusy operacji.
Logi
logi importu produktów, stanów, cen i zdjęć
Retry
retry dla timeoutów i chwilowych błędów API
Bez duplikatów
ochrona przed duplikacją zamówień i produktów
Alerty
alerty dla błędów krytycznych oraz raporty okresowe
Jak zacząć integrację z hurtownią?
Najpierw pobierz próbkę danych i sprawdź jakość SKU, EAN, kategorii, zdjęć, wariantów, cen i stanów. Następnie ustal reguły pól, częstotliwość aktualizacji, format integracji i sposób raportowania błędów.
Nie warto od razu budować pełnej synchronizacji wszystkiego. Bezpieczniej zacząć od MVP: import produktów, aktualizacja stanów i cen, raport błędów, a później rozszerzyć proces o zamówienia, statusy i pełne API.
- Import produktów
- Aktualizacja stanów i cen
- Raport błędów
- Zamówienia, statusy i pełne API
Jeśli źródłem jest plik, zacznij od tego, jak przygotować plik CSV do importu produktów.