Przejdź do treści

Integracje API dla sklepów i zaplecza e-commerce

Zespół przepisuje zamówienia do ERP, a stany w sklepie rozjeżdżają się z hurtownią? Łączymy sklep z ERP, hurtownią, BaseLinkerem i systemami zamówień przez API albo pliki XML/CSV, także w B2B. Każde pole ma jedno źródło, a każdy błąd wymiany trafia do raportu.

Realizacjaok. 115 tys. produktów i wariantów z BaseLinkera, zamówienia partnerów wracają do BaseLinkera bez przepisywaniaSportina B2B · Magento + BaseLinker
Jedno zamówienie: sklep → ERP → sklep przykład · dane demonstracyjne
Sklep Shoper, WooCommerce albo Magento
  1. 1 · sklep → ERP Zamówienie #D-1042, 3 pozycje pozycje po SKU, dane klienta, dostawa; ponowienie nie tworzy drugiego dokumentu
  2. 2 · ERP → sklep Numer dokumentu, status „w realizacji” co dokładnie wraca, zależy od ERP
  3. 3 · ERP albo kurier → sklep Status „wysłane” i numer przesyłki klient widzi go w sklepie i w wiadomości
ERP obsługa zamówień i magazyn
Przykładowy scenariusz, nie dane klienta. Przekazanie zamówienia do ERP nie oznacza automatycznie wystawienia faktury.

Co synchronizujemy i jak często: każde pole ma jedno źródło

Typowy układ dla sklepu z hurtownią i ERP. Każde pole ma jednego właściciela i jeden kierunek; konkretny projekt może go zmienić, ale każde pole musi mieć jedną odpowiedź.

Cena, stany i zamówienia: skąd i dokąd

typowy układ
  1. API, XML, CSVHurtownia albo ERPwłaściciel ceny, stanu magazynowego i kartoteki
  2. cena i stan → sklepSklepstan co kilkanaście–kilkadziesiąt minut, cena razem ze stanami albo dobowo; opisy, zdjęcia i treści SEO zostają w sklepie, bez synchronizacji
  3. zamówienia → na zdarzenieERP, BaseLinker lub Apilozamówienia ze sklepu przez API platformy, z logiem operacji
  4. status → sklepStatus, numer przesyłkiz ERP, BaseLinkera albo od kuriera, na zdarzenie
Częstotliwość, wyjątki i kontrolę każdego zapisu dla tych samych pól pokazuje tabela niżej. Tabelę wypełniamy razem z Tobą przed pierwszym zapisem.
Reguły integracji: właściciel pola, kierunek, częstotliwość, wyjątek i kontrola zapisu
DaneWłaściciel polaKierunekCzęstotliwośćWyjątekKontrola zapisu
Stan magazynowyhurtownia albo ERP→ sklepco kilkanaście–kilkadziesiąt minutprodukt bez dopasowania po SKU lub EAN trafia do raportu, nie jest pomijany po cichuzapis tylko zmian, ponowienie, alert
CenaERP albo hurtownia→ skleprazem ze stanami albo dobowocena z monitoringu konkurencji nie schodzi poniżej marży minimalnejzakres ceny sprawdzany przed zapisem
Nowe produkty, kartotekahurtownia albo ERP→ sklepprzy nowym pliku lub zmianierekord z brakami (EAN, kategoria, zdjęcie) czeka w raporciewalidacja pól, test na próbce
Opisy, zdjęcia, treści SEOsklepbez synchronizacji—plik XML/CSV z brakami albo złym mapowaniem nie nadpisuje opisanego produktukopia pól przed zapisem, zmiana odwracalna
Zamówieniasklep→ ERP, BaseLinker lub Apilona zdarzeniepozycja bez odpowiednika w kartotece; ponowienie nie tworzy drugiego dokumentulog operacji; błąd widoczny od razu, nie po fakturze
Status, numer przesyłkiERP, BaseLinker albo kurier→ sklepna zdarzeniesynchronizujemy kilka statusów granicznych w jednym kierunku, nie wszystkie w obie stronylog operacji

Stan w sklepie nie zgadza się z hurtownią

Z tym problemem sklepy przychodzą najczęściej. Niżej przebieg, który projektujemy: gdzie widać objaw, w którym miejscu go kontrolujemy i jaki wynik da się potem sprawdzić.

  1. 01 · objawZamówienie na towar, którego nie maSklep przyjmuje zamówienie na towar, którego hurtownia już nie ma. Przyczyną są ręczne aktualizacje albo zbyt rzadka synchronizacja, a czasem dwa systemy zapisujące ten sam stan, przez co wartość wraca do poprzedniej.
  2. 02 · miejsce kontroliJeden właściciel stanuStan ma jednego właściciela: hurtownię albo ERP. Synchronizacja działa cyklicznie, w harmonogramie dopasowanym do limitów API. Zapisujemy tylko zmienione rekordy, odrzucone zapytanie wraca do kolejki, a nieudany przebieg wysyła alert. Po zapisie odczyt sprawdza, czy sklep ma tę samą wartość co źródło.
  3. 03 · oczekiwany wynikStany zgodne ze źródłemStany zgadzają się ze źródłem w ustalonym cyklu, a sklep nie przyjmuje zamówień na towar, którego nie ma. Gdy synchronizacja się nie powiedzie, widać to w alercie i raporcie przebiegu.
To opis sposobu pracy na typowym przypadku, nie relacja z konkretnego wdrożenia.

Kontrole, dzięki którym błędny zapis nie psuje sprzedaży

  1. przed zapisemDry-runpodgląd zmian przed zapisem
  2. każda operacjaLogzapisuje każdą operację z wynikiem, a każdy przebieg kończy się raportem
  3. limit lub błąd sieciRetryponawia zapytanie odrzucone przez limit lub błąd sieci
  4. wycofanieKopia zmienianych pólpozwala wycofać uzgodnione zapisy
  5. po błędzieAlertnieudana aktualizacja wysyła alert

Częstotliwość wynika z limitów API: BaseLinker przyjmuje 100 zapytań na minutę, Shoper liczy operacje i podaje ich stan w nagłówkach odpowiedzi (domyślnie 10 operacji, zwalniane po 2 na sekundę; w konkretnym sklepie wartości mogą być inne).

Zamówienia do ERP przekazujemy przez Shoper API lub API platformy. Zapis przez API z walidacją przed zapisem działa w sklepie CMP na Shoper Storefront: 21 639 nazw produktów w ok. 4 h, bez błędu (realizacja CMP Polska). Jak przygotować katalog przed importem, opisujemy przy danych produktowych.

Limity API, od których zależy harmonogram

BaseLinker: zapytań na minutę
100 / min
Shoper: domyślny licznik, zwalniany po 2 na sekundę
10 operacji
Shoper podaje stan licznika w nagłówkach odpowiedzi; w konkretnym sklepie wartości mogą być inne.

Co jeszcze łączymy: skąd, co i dokąd

Cztery przepływy, o które sklepy pytają najczęściej. Działają na API, plikach, regułach i harmonogramie, bez AI; model AI dokładamy tylko tam, gdzie poprawia wynik, np. przy tłumaczeniu kategorii hurtowni. Dwa układy opisujemy osobno: integrację sklepu z hurtownią (produkty, ceny i dostępność od dostawców) i integrację BaseLinkera (gdy BaseLinker jest w środku).

Hurtownia → Sklep

Nowe produkty, kategorie, atrybuty i ceny

Automatyczny import; kategorie hurtowni tłumaczone na drzewo sklepu regułami i słownikami, przy dużej skali także z pomocą AI.

  • Hurtownia: XML, CSV albo API
  • Sklep: Shoper, WooCommerce, Magento
Hurtownia albo ERP → Sklep

Stany i ceny

Cyklicznie, np. co kilkanaście lub kilkadziesiąt minut — zależnie od limitów API, źródła danych i ryzyka biznesowego.

  • Hurtownia albo ERP: API, plik, eksport
  • Sklep: Shoper, WooCommerce, Magento
Sklep → ERP albo system zamówień

Zamówienia z pozycjami

Eksport bez przepisywania, przez API platformy, z logiem operacji.

  • Sklep: WooCommerce, Shoper, Magento
  • ERP albo system zamówień: ERP z własnym API lub eksportem plików; BaseLinker, Apilo
Kilka hurtowni → Jeden katalog sklepu

Stany z priorytetem dostawcy, asortyment do scalenia

Priorytetyzacja stanów i konsolidacja asortymentu z wielu dostawców.

  • Kilka hurtowni: każda z własnym formatem
  • Jeden katalog sklepu: bez duplikatów tego samego towaru

Pozostałe połączenia: helpdesk, magazyn, kurierzy, PIM, BI, marketing

WMS, spedycja, PIM, BI i arkusze, marketing automation, monitoring cen – skąd, co i dokąd
  1. Sklep przekazuje: zamówienie, pozycje, status, dokument, dane klientaAPI na żądanie albo webhook przy zdarzeniu do: System zgłoszeńhelpdesk
  2. Sklep wymienia w obu kierunkach: zamówienia do kompletacji, wysyłki, dostępnośćAPI lub pliki wymiany, oba kierunki z: WMS i magazyn
  3. Sklep wymienia w obu kierunkach: przesyłki, etykiety, numery listów, statusyAPI przewoźnika lub broker, oba kierunki z: Spedycja i kurierzy
  4. PIM przekazuje: opisy, atrybuty, zdjęcia, tłumaczeniaeksport z PIM i import z walidacją do: Sklep
  5. Sklep przekazuje: sprzedaż, jakość danych, rotacja, zwrotyzaplanowany eksport CSV lub odczyt przez API do: BI i arkusze
  6. Sklep przekazuje: zdarzenia zakupowe, segmenty, porzucone koszykizdarzenia po stronie serwera, nie tylko w przeglądarce do: Marketing automation
  7. Monitoring cen przekazuje: ceny konkurencji, reguły cenoweimport cen z limitem marży minimalnej do: Sklep

System zgłoszeń a sklep

co musi zawierać zgłoszenie i dwa sposoby realizacji

Osoba obsługująca zgłoszenie powinna widzieć zamówienie, pozycje i status przesyłki bez otwierania panelu sklepu. Budujemy wymianę danych z helpdeskiem, który już masz, o ile udostępnia API.

  • zgłoszenie musi mieć kontekst: numer zamówienia, pozycje, kwotę, metodę dostawy i status,
  • dopasowanie zgłoszenia do zamówienia po adresie e-mail bywa zawodne — potrzebny jest numer zamówienia albo identyfikator klienta,
  • zmiana statusu w sklepie powinna aktualizować zgłoszenie, a nie generować kolejne,
  • zwrot i reklamacja to inne procesy niż pytanie o dostawę — i inne dane wejściowe,
  • bez klucza idempotencji (znacznika, po którym system rozpoznaje powtórzone zdarzenie) ten sam webhook potrafi utworzyć trzy zgłoszenia z jednego zdarzenia,
  • dane osobowe w zgłoszeniu wymagają decyzji, co faktycznie przesyłamy, a co pobieramy dopiero na żądanie.

Dwa sposoby realizacji

PodejścieJak działaKiedy wybrać
na żądaniesystem zgłoszeń pyta sklep o dane przy otwarciu zgłoszeniamałe wolumeny, dane zawsze aktualne
zdarzeniowosklep wysyła zdarzenie przy zmianie statusuduże wolumeny, potrzeba historii
Uczciwie o zakresie. Nie jesteśmy dostawcą systemu helpdesk i nie wdrażamy go za Ciebie. Budujemy warstwę wymiany danych między sklepem — Shoper, WooCommerce, Magento — a systemem, który już wybrałeś, o ile udostępnia API. Jeżeli szukasz gotowego narzędzia do obsługi zgłoszeń, to jest inna decyzja niż integracja.

Technologie i szczegółowe zakresy

REST API, XML, CSV, ERP, systemy zamówień, Python, harmonogram
REST APIShoper, Magento, WooCommerce, własne endpointy
XMLcentra, hurtownie, formaty własne i branżowe
CSVimporty z Excela, konwersje, mapowanie kolumn
ERPsystemy z własnym API lub eksportem plików
Systemy zamówieńBaseLinker, Apilo
Pythonrequests, pandas, xmltodict, SQLite, PostgreSQL
Cron / Task Schedulerautomatyczne uruchamianie cykliczne

Jak uruchamiamy integrację bez przestoju sprzedaży

Od próbki do monitoringu. Najpierw sprawdzamy możliwości i konfigurację tego, co już jest; kod piszemy tylko dla zakresu, którego dostępne rozwiązania nie obsługują.

  1. Analiza źródeł danychFormat, jakość i dostępność danych: API, plik XML/CSV, baza, FTP. Oceniamy kompletność i mapowanie.
  2. Mapowanie i regułySłownik między strukturą źródła a sklepem oraz tabela reguł jak wyżej.
  3. Test na małym zbiorzeWeryfikacja wyników i korekta przypadków brzegowych przed produkcją.
  4. Produkcja i monitoringPełny przebieg, log i raport po każdym uruchomieniu, alert przy błędach krytycznych.

Inny zakres – osobne strony

Integracje API — pytania

Nie ma tu Twojego pytania? Napisz

API pozwala odczytywać i zapisywać pojedyncze rekordy na bieżąco, ale ma limity zapytań. Plik przenosi całą paczkę danych w odstępach czasu: jest prostszy, ale mniej aktualny i wymaga sprawdzenia całego pliku przed zapisem. Wybór zależy od tego, co udostępnia źródło, jak często zmieniają się dane i ile kosztuje błąd.
Zależy od limitów API i liczby produktów. BaseLinker pozwala na 100 zapytań na minutę, a Shoper liczy operacje i podaje ich stan w nagłówkach odpowiedzi. W praktyce stany aktualizujemy co kilkanaście lub kilkadziesiąt minut, ceny razem ze stanami albo raz na dobę, a pełne dane katalogu rzadziej.
Ustalić dla każdego pola jednego właściciela i jeden kierunek zapisu, czyli źródło prawdy. Bez tego systemy nadpisują się nawzajem, a błąd wraca po każdej synchronizacji. Zasadę rozpisujemy przed wdrożeniem w tabeli: pole, system źródłowy, kierunek, częstotliwość.
Każdy zapis ma wpis w logu, każdy przebieg kończy się raportem, a błąd krytyczny wysyła alert. Po zapisie sprawdzamy odczytem, czy dane w docelowym systemie są takie, jak wysłane. Sam status zadania w harmonogramie nie wystarcza, bo zadanie może zakończyć się sukcesem, mimo że część zapytań została odrzucona.
Tak, jeśli system udostępnia API albo eksport plików. Poza ERP, hurtowniami i BaseLinkerem łączymy sklep z magazynem, kurierami, PIM, systemem zgłoszeń, arkuszami i narzędziami marketingowymi. Nie wdrażamy samych tych systemów, tylko wymianę danych między nimi a sklepem.

Podaj dwa systemy i dane, które mają między nimi przechodzić

Na przykład „hurtownia XML → Shoper: stany i ceny” albo „WooCommerce → ERP: zamówienia”. Dopisz, co dziś robicie ręcznie. Zaproponujemy pierwszy etap, który najszybciej zdejmie z zespołu ręczne przepisywanie danych.

opis integracjiprzykład
hurtownia XML → Shoper: stany i cenyWooCommerce → ERP: zamówieniadziś ręcznie: …co robicie ręcznie