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.
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 łatwo stracić ręcznie przygotowane treści SEO albo opublikować dane techniczne w formie nieczytelnej dla klienta.
Ź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ć.
- 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
Czy hurtownia ma nadpisywać wszystkie pola, czy tylko aktualizować dostępność i cenę?
Pełne nadpisanie katalogu może zniszczyć opisy, kategorie i dane SEO przygotowane ręcznie.
API, XML czy CSV — różnice praktyczne
API daje największą kontrolę nad synchronizacją, ale wymaga tokenów, limitów, obsługi błędów, retry i monitorowania. 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.
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. 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.
- API: lepsza kontrola, statusy, częściowe aktualizacje i logi
- XML: dobre źródło katalogu, zdjęć, parametrów i wariantów
- CSV: dobry start, ale wymaga stałej kontroli kolumn i kodowania
- hybryda: produkty z XML/CSV, zamówienia lub stany przez API
Najlepsze do zamówień, statusów, stanów i procesów wymagających odpowiedzi systemu.
Dobre do dużych feedów produktowych, ale wymagają walidacji przed importem.
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
Najpierw symulujemy zmiany i raportujemy błędy, dopiero potem zapisujemy dane.
Przy ryzykownych aktualizacjach warto mieć możliwość cofnięcia partii importu.
Integracja 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 mają identyfikatory, blokady duplikacji i jasne statusy operacji.
- logi importu produktów, stanów, cen i zdjęć
- retry dla timeoutów i chwilowych błędów API
- ochrona przed duplikacją zamówień i produktów
- alerty dla błędów krytycznych oraz raporty okresowe
Automatyzacja bez logów jest trudniejsza w utrzymaniu niż ręczny import.
Ponowienie operacji nie powinno tworzyć drugiego zamówienia ani drugiego produktu.
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.