Przejdź do treści

Integracje Shoper API bez ręcznej pracy w panelu

Zespół przepisuje stany, ceny i zamówienia między Shoperem a ERP, hurtownią albo BaseLinkerem? Łączymy te systemy przez Shoper API: dane przechodzą same, błędne rekordy czekają na decyzję, a każda operacja zostaje w historii.

Realizacja20 847 opisów opublikowanych przez Shoper API w 96 hCMP Polska · Shoper
Jedna aktualizacja stanu: hurtownia → integracja → Shoper API → log przykład · dane demonstracyjne
  • hurtownia → integracja Stan wariantu TR-118-42: 7 → 3 odczyt pliku albo API dostawcy według harmonogramu odebrane
  • walidacja Liczba całkowita, wariant istnieje w sklepie błędny rekord nie dochodzi do wywołania API i nie zużywa limitu poprawny
  • integracja → Shoper Zapis w paczce /webapi/rest/bulk do 25 operacji w żądaniu; tempo według nagłówków limitu, po 429 czekamy tyle, ile mówi Retry-After zapisane
  • log Wynik każdej pozycji paczki pozycja odrzucona wraca do ponowienia albo czeka na decyzję w logu
Przykład na danych demonstracyjnych. Wariant w Shoperze to osobny rekord product-stocks z własnym stanem; źródło i częstotliwość odczytu zależą od dostawcy.

Panel, plik czy API?

API nie jest domyślną odpowiedzią na każdą operację masową. Przy jednorazowej zmianie na kilkuset produktach import pliku jest szybszy i tańszy. API wygrywa wtedy, gdy operacja się powtarza, musi być dwukierunkowa albo ma reagować na zdarzenie.

Panel
  • jednorazowa zmiana na kilkudziesięciu produktach: wystarczy
  • wsad kilku tysięcy produktów: nierealne
  • log: brak śladu
Import pliku
  • jednorazowy wsad kilku tysięcy produktów: właściwe narzędzie
  • stany kilka razy na godzinę: za wolne
  • dane wracające ze sklepu: jednokierunkowe
Shoper API
  • stany zmieniające się kilka razy na godzinę
  • zamówienia do ERP na zdarzenie
  • tylko wybrane pola, log każdej operacji, dwukierunkowo
Skrót tabeli „Siedem sytuacji” niżej.

Sygnały, że panel już nie wystarcza

Stany zmieniają się poza sklepem

magazyn, ERP lub hurtownia mają własne stany, a Shoper musi je regularnie aktualizować bez ręcznego importu

Ceny i rabaty są dynamiczne

cenniki, promocje, marże, rabaty B2B albo ceny dostawcy zmieniają się częściej, niż zespół nadąża je aktualizować

Zamówienia trzeba eksportować

do ERP, BaseLinkera, plików lub wewnętrznych procesów, bez przepisywania danych

Katalog jest za duży na panel

tysiące produktów, wariantów, EAN-ów, SKU, zdjęć i atrybutów wymagają procesu, a nie ręcznej edycji

Integracja działa tylko częściowo

nie obsługuje wyjątków, limitów, błędów, duplikatów albo ponownych prób po nieudanym zapisie

Brakuje logów

nikt nie wie, dlaczego produkt nie zaktualizował stanu, zamówienie nie wyszło do ERP albo cena została nadpisana

Siedem sytuacji: panel, import pliku czy Shoper API

pełne porównanie: kiedy panel wystarczy, kiedy plik, a kiedy API jest właściwym narzędziem
Porównanie panelu, importu pliku i Shoper API
SytuacjaPanelImport plikuShoper API
Jednorazowa zmiana na kilkudziesięciu produktachwystarczyzbędnezbędne
Jednorazowy wsad kilku tysięcy produktównierealnewłaściwe narzędziemożliwe, ale drożej
Stany zmieniające się kilka razy na godzinęnierealneza wolnewłaściwe narzędzie
Zamówienia wychodzące do ERP na zdarzenieręczna pracaopóźnienie cykluwłaściwe narzędzie
Aktualizacja tylko wybranych pól, bez ruszania resztyryzyko pomyłkizależy od importerapełna kontrola zakresu
Proces, który ma zostawić log i dać się odtworzyćbrak śladulog importulog każdej operacji
Dane wracające ze sklepu do innego systemueksport ręcznyjednokierunkowedwukierunkowo

Gotowa aplikacja ze sklepu Shopera czy własna integracja

format danych, reguły cenowe, wyjątki, częstotliwość i kontrola wyniku

Do hurtowni, Allegro czy popularnych ERP są gotowe aplikacje i integratory. Jeśli dane pasują do ich schematu, to zwykle szybszy i tańszy start. Własna integracja ma sens dopiero wtedy, gdy któreś z kryteriów poniżej wychodzi poza to, co aplikacja obsługuje.

Kryteria wyboru między gotową aplikacją a własną integracją przez Shoper API
KryteriumGotowa aplikacja wystarczy, gdyWłasna integracja, gdy
Format danychdostawca daje plik albo API w układzie, który aplikacja znakażdy dostawca ma inny układ pliku, kolumny zmieniają się między wersjami cennika
Reguły cenowejedna marża albo przelicznik dla całej ofertyinna reguła dla każdej marki, waluty obce, ceny „od” dla konfiguracji, ceny promocyjne do ochrony
Wyjątkikażdy produkt z pliku trafia do sklepu tak samoczęść pozycji ma czekać na decyzję: nowe produkty, duże zmiany ceny, ręcznie poprawione karty
Częstotliwośćaktualizacja co kilka godzin albo raz dziennie w całościróżny rytm dla stanów, cen i opisów albo reakcja na zdarzenie w innym systemie
Kontrola wynikuwystarcza informacja „import zakończony”potrzebny raport: co zapisano, co pominięto i dlaczego, z możliwością cofnięcia partii

Jeżeli nie wiesz, po której stronie jesteś, wyślij przykładowy plik od dostawcy i opis reguł ceny. Często odpowiedź brzmi: aplikacja plus porządek w danych przed jej uruchomieniem.

Cenniki od wielu dostawców: jak prowadzimy taki proces

Typowa sytuacja: każdy producent przysyła cennik w innym układzie, część w walutach obcych, a zmiany trafiają do sklepu ręcznie albo przez arkusz. Integrację dzielimy na trzy osobne zakresy, bo każdy ma inne ryzyko i inny rytm. Ta sekcja opisuje wykonanie przez API Shopera; ten sam proces dla innych platform i wielu dostawców opisuje integracja sklepu z hurtownią.

Od pliku do zapisu w sklepie: źródło → reguły → plan → zapis → odczytschemat procesu
  1. 01Źródło

    Odczyt cennika i sklepu. Plik producenta czytamy razem z aktualnym stanem sklepu pobranym przez API, a pozycje dopasowujemy po kodzie producenta lub EAN-ie.

    do wyjaśnieniaPozycje bez jednoznacznego dopasowania trafiają na listę do wyjaśnienia, nie do zapisu.

  2. 02Reguły

    Reguła ceny dla dostawcy. Cena katalogowa albo zakupowa z narzutem, waluta i sposób przeliczenia, zaokrąglenie – ustalone z klientem na piśmie przed pierwszym zapisem.

  3. 03Plan

    Plan zmian do akceptacji. Arkusz z wierszem na każdą zmianę: było, będzie, powód. Nowe produkty, duże zmiany ceny i wycofania czekają na decyzję w wierszu; reszta przechodzi według reguły.

    ochronaPola i pozycje ustawione w sklepie ręcznie, na przykład ceny specjalne, promocje czy poprawione nazwy, nie są nadpisywane automatycznie. Lista takich wyjątków jest częścią planu.

  4. 04Zapis

    Próba, potem partie. Najpierw próba na kilku pozycjach, potem partie w tempie dopuszczonym przez limity API (opis niżej). Przed zapisem kopia poprzednich wartości, każda operacja w dzienniku.

  5. 05Odczyt

    Odczyt kontrolny. Po zapisie odczytujemy zmienione pola ze sklepu i porównujemy z planem, a kontrolę powtarzamy na świeżym odczycie po czasie.

    raport wyjątkówRaport dla każdego dostawcy: zapisane, pominięte, czekające na decyzję i dlaczego.

Schemat procesu, nie panel klienta. Wyjątki wypadają z przepływu na tym etapie, na którym je widać, a raport po odczycie zbiera je dla każdego dostawcy.

Trzy zakresy integracji cenników

Tworzenie nowych produktów

z cennika powstaje karta według uzgodnionego wzoru: nazwa, kategoria, warianty, zdjęcia i dane techniczne; nowe karty mogą zostać ukryte do przeglądu, zanim pojawią się w sklepie

Aktualizacja cen

dla każdego dostawcy osobna reguła: cena katalogowa albo zakupowa z narzutem, waluta i sposób przeliczenia, zaokrąglenie; reguły ustalamy z klientem na piśmie, zanim cokolwiek zostanie zapisane

Synchronizacja danych i dostępności

stany, terminy dostawy, produkty wycofane przez producenta; tu decyduje częstotliwość i to, który system jest źródłem prawdy dla każdego pola

Przy jednorazowym zasileniu katalogu ten sam sposób pracy opisuje strona importu produktów CSV/XML do Shopera, łącznie z tym, jak sprawdzamy wynik importu. Reguły sprawdzania pól przed zapisem (SKU, EAN, ceny, stany) opisuje walidacja danych produktowych.

Shoper API w praktyce: od ręcznej pracy do kontrolowanego procesu

Połączenie dwóch API to mniejsza część pracy. Klient dostaje proces, który zapisuje poprawne dane, odkłada wyjątki do decyzji i pokazuje, co zrobił. Przy każdym przypadku podajemy, co zmierzyliśmy i jak.

Tysiące produktów bez opisów i meta: przebieg w sklepie CMP

Problem: katalog rośnie z hurtowni, a opisy, SEO title i meta description trzeba pisać ręcznie. Co zrobiliśmy: pobranie danych przez Shoper API, automatyzacja opisów AI z walidacją i publikacja batchami z logiem.

opisów opublikowanych przez Shoper API
20 847
przebiegu automatu zamiast miesięcy pracy ręcznej (eksport, generowanie, publikacja)
96 h 14 min

Case CMP: 20 847 opisów w 96 h przez Shoper API

Dwa kolejne przypadki, opisane bez nazw sklepów:

Plik produktów dla Google Merchant Center

Wbudowany plik pokazywał ponad 99% pozycji jako niedostępne, a GTIN był pusty prawie wszędzie. Powstał własny plik generowany co noc z danych katalogu: jedna pozycja to jeden dostępny rozmiar z EAN-em i grupą wariantów, cena porównywana z kartą przed publikacją, bezpiecznik przy podejrzanie małym pliku.

Wynik. Pierwsze pobranie przez Merchant Center (15.10.2026) przeszło bez błędów pliku; EAN ma prawie każda pozycja (brak w 3 na ok. 2 tys.). Opis: plik produktów Google z Shopera.

Wariant, który po imporcie daje złą cenę na liście

Import z BaseLinkera nie ustawia wariantu domyślnego na dostępnym rozmiarze, więc bez korekty listing pokazuje cenę innego wariantu niż ten, który da się kupić. Odczyt wariantów przez API, reguła wyboru wariantu domyślnego i nocna korekta z kopią stanu i odczytem kontrolnym.

Produkty z zawyżoną ceną na liście

przed naprawą (połowa września 2026)103
po naprawie (kontrola 20 653 aktywnych produktów)4
Wynik. Produktów z zawyżoną ceną na liście było 103, po pełnej naprawie w połowie września 2026 – 4; porównanie odczytów katalogu w czasie pokazało, że bez korekty import przywraca problem, dlatego od połowy października 2026 korekta działa co noc. Opis: wariant domyślny po imporcie z BaseLinkera.

Co konkretnie podłącza się przez Shoper API

Każdy scenariusz zastępuje powtarzalną pracę w panelu. Zwykle zaczynamy od jednego, tego najbardziej kosztownego czasowo, a później dokładamy logikę wyjątków i raportowanie.

Scenariusze integracji przez Shoper API
ScenariuszKierunekCzęstotliwośćCo zastępuje
Pobieranie i aktualizacja produktów: warianty, SKU, EAN, opisy, statusy i widocznośćobaprzy zmianieręczną edycję kart w panelu
Synchronizacja stanów: własnych, dostawcy, rezerwacji i komunikatów dostępności na karciedo Shoperacykliczniecodzienny import pliku
Aktualizacja cen i promocji: rabaty, marże, cenniki B2B i wyjątki dla grup klientówdo Shoperacykliczniemasowe edycje przed akcją
Pobieranie zamówień do ERP, BaseLinkera, CSV/XLSX lub integracji kurierskichz Shoperana zdarzenieprzepisywanie zamówień do ERP
Aktualizacja statusów i przesyłekdo Shoperana zdarzenieręczne zmiany statusów

Pozostałe zastosowania w jednym miejscu

Pozostałe scenariusze, systemy po drugiej stronie, raporty i eksporty

Pozostałe scenariusze

kierunek · częstotliwość · co zastępuje

  • Synchronizacja kontrahentów · oba · przy zmianie · dublowanie danych klienta
  • Eksport danych do ERP · z Shopera · cyklicznie · eksporty robione ręcznie
  • Import z hurtowni · do Shopera · cyklicznie · obróbkę pliku w arkuszu
  • Publikacja opisów i metadanych · do Shopera · partiami · wklejanie treści produkt po produkcie
  • Do tego mapowanie kategorii, uzupełnianie cech i porządkowanie filtrów pod SEO e-commerce oraz webhooki: reakcje na zamówienia, zmiany statusu i aktualizacje produktów, które powinny uruchamiać automatyzację.

Systemy po drugiej stronie integracji

co przechodzi i w którą stronę

  • ERP: stany, ceny, zamówienia, kontrahenci · oba
  • hurtownia: katalog, dostępność, ceny zakupu · do sklepu
  • BaseLinker: oferty, stany, zamówienia z marketplace · oba
  • magazyn / WMS: dostępność, kompletacja, wysyłki · oba
  • arkusz / BI: raporty sprzedaży i jakości danych · ze sklepu
  • helpdesk: kontekst zamówienia przy zgłoszeniu · ze sklepu

Raporty i eksporty ze sklepu

Najczęściej pomijane zastosowanie API to nie zapis, a odczyt. Dane, po które zespół co tydzień wchodzi do panelu, można wyciągać automatycznie i w stałym formacie:

  • sprzedaż w rozbiciu na kategorie, marki i warianty, nie tylko na produkty,
  • produkty bez zdjęcia, opisu, EAN-u albo kategorii — lista do uzupełnienia,
  • rotacja i zapasy: co nie schodzi, co kończy się w tym tygodniu,
  • zamówienia z podziałem na status, metodę dostawy i płatność,
  • zwroty i anulacje jako osobny zbiór, nie odjęcie od sprzedaży,
  • zestawienie różnic między stanem w sklepie a stanem w ERP.
  • Wynik trafia do arkusza, pliku CSV albo bezpośrednio do narzędzia raportowego.
Import i eksport CSV/XML/API

Jak wdrażamy integrację Shoper API bez ryzyka dla katalogu

  1. Opis procesuJakie dane mają płynąć, w którą stronę, jak często i co jest źródłem prawdy dla produktów, cen, stanów i zamówień.
  2. Mapa danychPola Shopera porównane z ERP, hurtownią, BaseLinkerem lub plikami i opisane reguły transformacji.
  3. Prototyp i dry-runTestowy przebieg pokazuje payload, logi i potencjalne błędy bez ryzykownego zapisu masowych zmian.
  4. Wdrożenie i monitoringIntegracja uruchamiana etapami, z pilnowaniem limitów, wyjątków, kolejki zadań, retry i raportowania błędów.
  5. Rozwój automatyzacjiPo stabilizacji na tym samym połączeniu można dodać kolejne procesy: opisy AI, walidację danych, mapowanie kategorii, eksporty, B2B lub raporty sprzedażowe.

Jak działa Shoper API: autoryzacja, limity i paginacja

Shoper udostępnia REST API pod adresem https://adres-sklepu/webapi/rest/. Oficjalna dokumentacja jest na developers.shoper.pl. Poniżej to, co z niej najczęściej decyduje o stabilności integracji, uzupełnione o to, co widzimy w sklepach klientów.

Shoper REST API · zapytanie i nagłówkiprzykład
GET /webapi/rest/products?limit=50&page=1limit od 1 do 50, domyślnie 10X-Shop-Result-Pagesliczba stron do odczytuX-Shop-Api-Limit: 10domyślnieX-Shop-Api-Bandwidth: 2domyślnie 2 operacje na sekundęX-Shop-Api-Callsbieżący stan licznikaPOST /webapi/rest/bulkdo 25 operacji w jednym żądaniu, osobny wynik dla każdej pozycji429 Too Many Requests · Retry-Afterczekamy tyle, ile mówi Retry-After
Przykład na podstawie zasad z tabeli niżej; wartości domyślne bywają inne w konkretnym sklepie.
Dla zespołu technicznego: autoryzacja, limity, paginacja i zasady zapisu
Podstawowe zasady Shoper REST API
TematJak to działaNa co uważać
AutoryzacjaOAuth 2.0: aplikacja z panelu Shopera dostaje token dostępu, przy integracji serwer–serwer token pobiera się z /webapi/rest/authuprawnienia tokenu ustawia się w panelu, do odczytu danych wystarczy zakres tylko do odczytu
Limit zapytańlicznik operacji na aplikację: X-Shop-Api-Limit (domyślnie 10) i X-Shop-Api-Bandwidth (domyślnie 2 operacje na sekundę), bieżący stan w X-Shop-Api-Callspo przekroczeniu odpowiedź 429 z Retry-After; wartości bywają inne niż domyślne: w sklepie sprawdzanym w październiku 2026 Bandwidth wynosił 10
Paginacjaparametr limit od 1 do 50 (domyślnie 10) i page, liczba stron w nagłówku X-Shop-Result-Pagesbez ustawienia limit=50 pełny odczyt katalogu wymaga pięciokrotnie więcej zapytań
Wariantywariant produktu to osobny rekord w product-stocks, z własnym kodem, ceną i stanemw katalogu, który obsługujemy, na ok. 22 tys. produktów przypada ok. 168 tys. wariantów (pełny odczyt, wrzesień 2026), więc czas odczytu i zapisu liczy się od wariantów, nie od produktów
Operacje zbiorcze/webapi/rest/bulk przyjmuje do 25 operacji w jednym żądaniukażda operacja w paczce może się nie udać osobno, wynik trzeba sprawdzić dla każdej pozycji

Typowe objawy problemów z tymi zasadami (błędy 429, urwana paginacja, duplikaty po ponowieniu) opisujemy w poradniku najczęstsze błędy Shoper API. Konkretne przypadki z zapisu przez API opisuje seria: częściowy PUT, który wyłączył kolekcję, zapis, który wraca do starej treści, wykluczenia z kampanii przez feeds_excludes i blokada IP „Zostałeś zablokowany”.

Jak integracja obsługuje te zasady

Największa różnica między skryptem a stabilną integracją to obsługa wyjątków. Trzeba wiedzieć, co zrobić, gdy API zwróci błąd, dostawca zmieni strukturę, produkt nie ma EAN-u albo zamówienie wymaga ręcznej decyzji.

Zapis idzie paczkami sterowanymi nagłówkami limitu, nie stałą liczbą zapytań na sekundę. Logika pośrednia (middleware w Pythonie lub PHP) tłumaczy dane między Shoperem, ERP, hurtownią, plikami i innymi systemami.

ZagadnienieJak to rozwiązujemyEfekt
reguły zapisujasne zasady tworzenia, aktualizacji i pomijania rekordówprzewidywalny katalog
autoryzacjadane dostępowe poza kodem, w konfiguracjibrak sekretów w repo
limitykontrola tempa z nagłówków X-Shop-Api-Limit/Bandwidth i backoff po 429 (BaseLinker: 100/min)brak utraty rekordów
paginacjaprzetwarzanie strona po stroniestabilna pamięć
retryponowienia z rosnącym odstępemodporność na chwilowe błędy
Pozostałe zasady: idempotencja, błędy, dry-run, harmonogram, źródło prawdy
ZagadnienieJak to rozwiązujemyEfekt
idempotencjaklucz operacji przy zapisie: ta sama operacja powtórzona po błędzie nie tworzy drugiego rekordubrak duplikatów
błędylog zamiast cichego ignorowania; podział na ponawialne i wymagające decyzjialert tylko gdy trzeba
dry-runtryb testowy przed zapisem na produkcjizmiana widoczna przed zapisem
harmonogramokna poza szczytem ruchusklep nie zwalnia
źródło prawdyjeden właściciel każdego pola, bezpieczne mapowanie między systemamibrak pętli nadpisań

Shoper API — pytania

Nie ma tu Twojego pytania? Napisz

Tak. Shoper API obsługuje odczyt i zapis produktów, stanów, cen i zamówień, więc spinamy go z ERP, BaseLinkerem albo hurtownią. Kluczowe jest ustalenie źródła prawdy i kolejności synchronizacji, żeby systemy nie nadpisywały się nawzajem. Każdą aktualizację logujemy i zabezpieczamy retry oraz alertem przy błędzie.
Nie publikujemy tysięcy rekordów bez walidacji. Najpierw próbka: sprawdzamy SKU, EAN, ceny i stany oraz podgląd zmian przed zapisem. Przed zapisem kopiujemy poprzednie wartości pól, które aktualizacja zmienia, a zapis idzie partiami z logiem. Log pokazuje, co i kiedy zmieniono, a kopia pozwala przywrócić te pola w wybranej partii. Nie cofa zamówień złożonych w międzyczasie, zmian wprowadzonych w panelu ani danych, które zdążyły trafić do innych systemów, dlatego kontrolujemy wynik już po pierwszej partii.
Najczęściej produkty, warianty, stany magazynowe, ceny, zamówienia, statusy, kategorie, atrybuty, klienci, eksporty i procesy powiązane z ERP, hurtownią lub BaseLinkerem.
Zależy od procesu. Pliki CSV/XML są dobre dla prostych lub okresowych aktualizacji, a API ma większy sens przy częstych zmianach, zamówieniach, stanach, cennikach i automatyzacji zdarzeń.
Tak. Kluczowe jest ustalenie, który system jest źródłem prawdy dla produktów, cen, stanów, zamówień i klientów oraz jakie dane mogą być nadpisywane automatycznie.
Trzeba wdrożyć walidację, dry-run, logi, retry, limity, raporty błędów i reguły pomijania rekordów, które są niepełne lub konfliktowe.
Tak. Można uruchamiać ją cyklicznie dla stanów i cen, zdarzeniowo dla zamówień albo ręcznie w trybie kontrolowanym, gdy publikacja wymaga akceptacji.
Tak i zwykle to najlepsze podejście. Najpierw warto wdrożyć jeden proces, na przykład eksport zamówień albo aktualizację stanów, a dopiero potem rozszerzać integrację.

Masz proces w Shoperze, który zespół nadal robi ręcznie?

Opisz, co trzeba połączyć: ERP, BaseLinker, hurtownię, stany, ceny, zamówienia, CSV/XML albo własny system. Zaczniemy od procesu, który dziś zabiera zespołowi najwięcej czasu.