API Shoper: jak działają integracje, uwierzytelnianie i limity

API Shoper pozwala zewnętrznej aplikacji odczytywać lub zmieniać dane sklepu w zakresie przyznanych uprawnień. REST API to interfejs, w którym aplikacja komunikuje się ze sklepem przez żądania HTTP, na przykład GET do odczytu i PUT do aktualizacji. Dokumentacja Shoper opisuje zasoby obejmujące między innymi produkty, zamówienia, klientów, wysyłki i webhooki.

Zakres integracji zaczynamy od wskazania systemu źródłowego dla każdego pola. System źródłowy to miejsce, które przechowuje wiążącą wartość, na przykład ERP dla ceny i stanu magazynowego. Jeśli dwa systemy mogą zmieniać tę samą wartość, specyfikacja musi określać, który zapis wygrywa.

Tabela pokazuje przykładowe przypisanie właściciela danych, które trzeba dopasować do procesu firmy.

Przed połączeniem z API Shoper należy zdefiniować zasoby, operacje, zakres uprawnień oraz właściciela aplikacji. Dokumentacja Shoper opisuje rejestrację aplikacji w panelu jako sposób uzyskania danych client_id i client_secret dla przepływu OAuth Authorization Code; szczegóły procesu i wymagań znajdują się w dokumentacji uwierzytelniania Shoper.

Przed programowaniem ustal:
- które zasoby aplikacja odczytuje, tworzy lub aktualizuje;
- czy użytkownik sklepu autoryzuje aplikację, czy integracja działa jako aplikacja serwerowa;
- kto odpowiada za aplikację, odnowienie tokenów i obsługę błędów;
- gdzie odbędą się testy i jakie dane można wykorzystać;
- które identyfikatory łączą rekordy, na przykład SKU, ID zamówienia i ID produktu.

Shoper dokumentuje przepływ Authorization Code oraz Client Credentials. Authorization Code wymaga przekierowania użytkownika do autoryzacji, a następnie wymiany kodu na token. Client Credentials uzyskuje token dla aplikacji serwerowej i według dokumentacji nie wydaje refresh tokenu. Przed wyborem przepływu sprawdź wymagania aplikacji i aktualny opis w dokumentacji OAuth Shoper.

Zalecamy przechowywać client_secret i tokeny w menedżerze sekretów lub chronionym magazynie konfiguracji po stronie serwera. Nie umieszczaj poświadczeń w repozytorium, logach, adresach URL ani kodzie przeglądarkowym. Loguj metodę, zasób, czas i status odpowiedzi, ale maskuj nagłówek Authorization oraz dane osobowe.

Jeśli planowana integracja obejmuje BaseLinker jako jeden z systemów pośredniczących, wdrożenie integracji z BaseLinkerem może pasować do tego zakresu. Oferta dotyczy konfiguracji BaseLinkera, więc nie zastępuje projektu połączenia opartego wyłącznie na bezpośrednim API Shoper.

Shoper REST API wymaga tokenu dostępu OAuth 2.0 w nagłówku Authorization: Bearer przy żądaniach do zasobów. Zakresy OAuth określają dozwolone operacje, na przykład odczyt produktów lub edycję zamówień; dokładne nazwy zakresów i przypisane im zasoby trzeba sprawdzić w referencji API Shoper. Brak wymaganego zakresu może skutkować odpowiedzią HTTP 403 Forbidden.

W Authorization Code aplikacja przekierowuje użytkownika do endpointu autoryzacji, odbiera kod i wymienia go na token. Dokumentacja opisuje endpoint wymiany /webapi/rest/oauth/token. W Client Credentials aplikacja wysyła żądanie POST /webapi/rest/auth z autoryzacją Basic, a późniejsze żądania zasobów przekazują token Bearer. Szczegóły endpointów i parametrów należy weryfikować w oficjalnej dokumentacji, ponieważ konfiguracja może zależeć od aplikacji i sklepu.

Tabela porządkuje pierwszą kontrolę; właściwą przyczynę potwierdź na podstawie odpowiedzi i logów żądania.

Listę zasobów, metod i wymaganych pól sprawdza się w referencji API dla konkretnego zadania. Dokumentacja Shoper udostępnia opisy REST API, webhooków i autoryzacji pod adresem developers.shoper.pl/docs; dostępność zasobu nie oznacza automatycznie, że aplikacja ma do niego uprawnienia.

Dla produktów określ, czy proces wymaga listowania, odczytu pojedynczego produktu, utworzenia czy aktualizacji. Dla zamówień rozdziel pobieranie od zmiany statusu. Dla stanów potwierdź, którego zasobu dotyczy zapis i jaki zakres go dopuszcza.

Dokumentacja API opisuje paginację list. Wartości domyślne wskazane w poprzedniej dokumentacji to limit 10 rekordów na stronę i parametr limit od 1 do 50; dostępne mogą być parametry page lub offset oraz nagłówki informujące o liczbie wyników i stron. Przed implementacją potwierdź bieżące parametry zasobu w dokumentacji, a integrację zaprojektuj tak, by przechodziła przez wszystkie strony.

Żądania z treścią JSON powinny deklarować Content-Type: application/json. Dokumentacja opisuje też operacje bulk, które grupują do 25 operacji w jednym żądaniu HTTP. Wynik każdej operacji trzeba oceniać osobno, ponieważ odpowiedź zbiorcza nie przesądza o powodzeniu wszystkich zmian.

Częstotliwość synchronizacji powinna wynikać z tempa zmian danych i akceptowanego opóźnienia sprzedażowego. Webhook przekazuje informację o zdarzeniu, a odczyt cykliczny może uzupełniać dane lub wykrywać rozbieżności.

Tabela łączy typ danych z mechanizmem; interwał należy dobrać do wolumenu i wymagań sklepu.

Kolejka oddziela odbiór zdarzenia od wykonania pracy. Zapisuj identyfikator zdarzenia, stan przetwarzania i liczbę prób. Przed ponowieniem zapisu sprawdź, czy poprzednia próba nie zakończyła się sukcesem. Przy dużych synchronizacjach utrzymuj punkt wznowienia, aby nie przetwarzać całego katalogu po każdej przerwie.

Z naszych wdrożeń wynika, że kontrolne pobranie zmienionych rekordów pomaga wychwycić zdarzenia, których integracja nie przetworzyła podczas niedostępności.

Dokumentacja Shoper opisuje domyślny limit 10 operacji i tempo opróżniania licznika 2 operacje na sekundę; wartości te sprawdziliśmy w październiku 2026 w dokumentacji limitów API Shoper. Mechanizm ogranicza tempo wywołań, a po przekroczeniu limitu API może zwrócić HTTP 429 Too Many Requests i nagłówek Retry-After.

Dokumentacja wymienia nagłówki limitów, między innymi X-SHOP-API-LIMIT, X-SHOP-API-BANDWIDTH i X-SHOP-API-CALLS. Integrator powinien odczytywać dostępne nagłówki odpowiedzi i sterować kolejką, zanim regularnie zacznie otrzymywać 429. Przy 429 respektuj Retry-After; przy błędach 5xx stosuj ograniczone ponowienia z rosnącym odstępem.

W diagnostyce oddziel cztery źródła problemu:
- dostęp: token, nagłówek Bearer, domena sklepu i zakres;
- walidacja: pola, typy danych i format żądania;
- limit: nagłówki limitu, Retry-After i tempo kolejki;
- integrator: timeout, połączenie, kolejka i zapisane identyfikatory żądań.

Nie zapisuj sekretów ani pełnego nagłówka Authorization. Zachowuj status HTTP, zasób, metodę, czas i numer próby, aby odtworzyć błąd bez ujawniania danych dostępowych.

Test integracji API Shoper powinien objąć odczyt, zapis, paginację, uprawnienia, błędy i powtórzenia. Sam kod 200 nie potwierdza, że synchronizacja zachowała dane i reguły procesu.

Minimalny plan testów obejmuje:
- odczyt produktu i zamówienia z wymaganym zakresem;
- kontrolowany zapis, jeśli integracja ma zmieniać dane;
- paginację listy większej niż jedna strona;
- brakujące i puste pola oraz polskie znaki;
- token bez wymaganego zakresu i token nieważny;
- ponowienie po błędzie sieciowym;
- powtórzone żądanie i ochronę przed duplikatem;
- ograniczenie kolejki po odpowiedzi 429.

Dla każdego testu zapisz stan oczekiwany, wykonane żądanie bez sekretów, odpowiedź i stan końcowy w Shoperze. Gotowość do produkcji wymaga także wznowienia synchronizacji po przerwie oraz alertu dla błędów wymagających interwencji operatora.

Monitoring integracji powinien mierzyć terminowość przepływu i zdolność do wznowienia pracy po błędzie. Zbieraj liczbę nieudanych żądań, udział odpowiedzi 4xx i 5xx, opóźnienie synchronizacji, wielkość kolejki, liczbę ponowień oraz rozbieżności danych.

Tabela łączy sygnał z pierwszym krokiem; próg alarmu ustaw dla procesu, a nie dla pojedynczego błędu automatycznie ponowionego przez integrację.

Jeżeli plan obejmuje BaseLinker i potrzebujesz wykonawcy do jego konfiguracji, zakres wdrożenia BaseLinkera dla sprzedaży wielokanałowej może być punktem wyjścia do rozmowy. Przy integracji opartej wyłącznie na bezpośrednim API Shoper potrzebny jest zakres prac dopasowany do tego połączenia.

• Jak połączyć sklep Shoper z Empik Marketplace i obsługiwać zamówienia?
• Integracja API krok po kroku: jak połączyć sprzedaż z operacjami
• Jak zintegrować zamówienia ze sklepu internetowego z systemem księgowym?
• SubSync vs Apilo: jak dobrać integrację do Subiekta i sprzedaży wielokanałowej
• Integracja Inter Cars ze sklepem internetowym: jak działa i co sprawdzić przed wdrożeniem