Przejdź do treści

Integracja sklepu z hurtownią: API, XML czy CSV?

Często hybryda: katalog i zdjęcia z XML/CSV, stany, ceny i zamówienia przez API, o ile hurtownia udostępnia API. Gdy dostawca daje tylko plik, stany i ceny też przychodzą z XML/CSV, a ich świeżość zależy od tego, jak często plik jest pobierany. Poza samym plikiem produktów trzeba ustalić źródło prawdy, mapowanie SKU, EAN, kategorii, cen i stanów, sposób aktualizacji, logi błędów, retry oraz bezpieczny model publikacji danych w sklepie.

Który format do jakich danych?

  1. zamówienia, statusy, stanyAPIAPI daje największą kontrolę, ale wymaga obsługi limitów, tokenów i błędów
  2. feed kataloguXMLXML jest dobry dla feedów produktowych, ale wymaga mapowania i walidacji
  3. prosty startCSVCSV bywa najprostszy, lecz szybko ujawnia problemy z kolumnami i wariantami
Często hybryda: katalog i zdjęcia z XML/CSV, stany, ceny i zamówienia przez API. Bez logów i dry-run integracja staje się niewidocznym punktem awarii.
Najpierw proces, potem format danych

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.

01

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

cyklicznie

Kopia stanów z BaseLinkera

odświeżana w sklepie

raz na dobę

Ceny

rzadziej niż stany

od razu

Zamówienie obniża stan

w platformie od razu, w BaseLinkerze przez API

API, XML i CSV w integracji sklepu z hurtownią
FormatKiedy wystarczaCo sprawdzić
APIzamówienia, statusy, stany i procesy wymagające odpowiedzi systemu; częste aktualizacje, komunikacja dwukierunkowa, częściowe aktualizacje i logiautoryzacja i tokeny, limity, retry, obsługa błędów, monitorowanie
XMLfeed katalogu: zdjęcia, parametry i warianty; batchowe aktualizacjewersja pliku, mapowanie, walidacja przed importem, raport zmian
CSVprosty start i proste importyseparator, kodowanie, kolumny, niejednoznaczne wartości
Hybrydaprodukty z XML/CSV, zamówienia lub stany przez APInie trzeba wszystkiego robić jednym kanałem; każdy kanał potrzebuje własnych reguł pól
02

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
03

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
dry-run: paczka z hurtowniprzykład
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 importu
Walidacja zatrzymuje błędną paczkę danych przed zapisem produkcyjnym: osobno raport błędów, osobno rekordy gotowe do importu.
04

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 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

05

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.

  1. Import produktówMVP
  2. Aktualizacja stanów i cenMVP
  3. Raport błędówMVP
  4. Zamówienia, statusy i pełne APIpóźniej

Jeśli źródłem jest plik, zacznij od tego, jak przygotować plik CSV do importu produktów.

FAQ: integracja z hurtownią

To zależy od danych i częstotliwości aktualizacji. API jest najlepsze do procesów dynamicznych, XML do większych feedów produktowych, a CSV do prostych importów. Często najlepsza jest hybryda.
Trzeba wdrożyć walidację, mapowanie kategorii, kontrolę duplikatów, logi, dry-run i osobne reguły dla pól, których nie wolno nadpisywać automatycznie.
Tak, ale trzeba ustalić priorytety źródeł danych i regułę ceny dla każdego dostawcy: cena katalogowa czy zakupowa z narzutem, waluta i przeliczenie, zaokrąglenie oraz ręczne wyjątki, których integracja nie nadpisuje. Ten sam produkt może mieć różne stany, ceny, EAN-y i zdjęcia w kilku feedach, więc konieczne są reguły łączenia danych.
Zależy od rotacji i ryzyka sprzedaży niedostępnego produktu. Ceny i stany zwykle aktualizujemy częściej niż opisy i zdjęcia. Przy API można robić synchronizację częstszą, przy plikach trzeba uważać na czas importu. W naszej platformie B2B stany (własny i dostawcy) przychodzą z BaseLinkera, a złożone zamówienie zdejmuje stan w BaseLinkerze.
Tak, w wielu projektach może uprościć obsługę zamówień, stanów i kanałów sprzedaży. Nadal trzeba jednak pilnować mapowania SKU, statusów, logów i zasad źródła prawdy.
Sprawdzić logi, obowiązkowe pola, SKU, kategorie, warianty, zdjęcia, limity API, kodowanie pliku i błędy walidacji. Problem często leży w danych, nie w samym imporcie.

Ręcznie przepisujesz ceny i stany z hurtowni?

Połączymy plik XML, CSV albo API hurtowni ze sklepem: import produktów, aktualizacja cen i stanów według ustalonych reguł i raport błędów zamiast ręcznego porównywania arkuszy. Zaczynamy od MVP, które od razu zdejmuje najwięcej ręcznej pracy.

Podobna realizacjaOk. 115 tys. produktów i wariantów z BaseLinkera w katalogu B2BSportina B2B · Magento