API Shoper: integracje, uwierzytelnianie, limity i bezpieczne wdrożenie

API Shoper pozwala połączyć sklep z ERP, WMS, systemem partnera, narzędziem raportowym lub własną aplikacją. Nie jest jednak gotową integracją. Dokumentacja opisuje dostępne zasoby i reguły komunikacji, a wykonawca nadal musi zaprojektować przepływ danych, uprawnienia, odporność na błędy i sposób ponowienia operacji.

API Shoper — co to jest i do czego służy

API Shoper to interfejs programistyczny, przez który autoryzowana aplikacja może odczytywać lub zmieniać dane sklepu w granicach przyznanych uprawnień. Oficjalna dokumentacja REST API obejmuje między innymi produkty, kategorie, stany magazynowe, zamówienia, płatności, dostawy, klientów, promocje i wybrane elementy treści.

Najczęstsze zastosowania biznesowe to:

• przekazywanie zamówień do ERP lub systemu realizacji;
• synchronizacja stanów, cen i danych produktów;
• integracja wielu punktów sprzedaży lub partnerów B2B;
• tworzenie dokumentów, etykiet i zadań operacyjnych;
• kontrolowane raportowanie bez ręcznego eksportowania plików;
• budowa aplikacji rozszerzającej proces sklepu.

API nie powinno być używane tylko dlatego, że „da się połączyć systemy”. Najpierw trzeba ustalić źródło prawdy dla każdego pola. Jeżeli cenę może jednocześnie zmieniać ERP, panel sklepu i importer, sama integracja nie rozwiąże konfliktu — może go jedynie przyspieszyć.

Jak uzyskać dostęp do API Shoper

Aktualna dokumentacja Shoper opisuje uwierzytelnianie OAuth 2.0. Dostęp zależy od typu integracji i może wykorzystywać przepływ właściwy dla aplikacji albo autoryzację użytkownika. Sekretu klienta, tokenu ani danych administratora nie wolno umieszczać w kodzie frontendu, publicznym repozytorium czy treści formularza.

Minimalny bezpieczny model wygląda tak:

1. Aplikacja otrzymuje własną tożsamość i tylko potrzebne zakresy dostępu.
2. Sekrety są przechowywane po stronie serwera w kontrolowanym środowisku.
3. Połączenie ze sklepem odbywa się przez HTTPS.
4. Logi nie zapisują tokenów ani pełnych danych klientów.
5. Odebranie dostępu jednej integracji nie wymaga zmiany hasła całego panelu.

Nie kopiuj tokenu z instrukcji znalezionej w starszym artykule. Panel, sposób rejestracji aplikacji i dostępne przepływy mogą się zmieniać, dlatego przed wdrożeniem trzeba sprawdzić bieżącą dokumentację oraz wariant konta Shopera.

Zasoby, filtry i paginacja: pobieraj tylko potrzebne dane

Pierwsza wersja integracji często działa na kilku rekordach, a problemy pojawiają się dopiero przy pełnym katalogu. Dlatego od początku trzeba obsłużyć paginację, filtrowanie, daty modyfikacji i stabilne identyfikatory.

Przykład: synchronizacja zamówień nie powinna za każdym razem pobierać całej historii. Integracja może wybierać rekordy zmienione od ostatniego potwierdzonego punktu, zapisywać kursor lub znacznik czasu i osobno prowadzić procedurę okresowej kontroli. Ostatni zapisany czas nie może być aktualizowany przed trwałym przetworzeniem danych, bo awaria utworzy lukę.

Przy imporcie produktów zwróć uwagę na relację produktu, wariantu, stanów magazynowych, cen i zdjęć. Jeden rekord biznesowy może wymagać kilku zasobów API, a kolejność zmian ma znaczenie dla tego, co klient zobaczy w sklepie.

Limity API Shoper i obsługa błędów

Shoper ogranicza liczbę operacji wykonywanych przez aplikację. Bieżące wartości i zużycie są komunikowane w nagłówkach odpowiedzi, a po przekroczeniu limitu API może zwrócić 429 Too Many Requests wraz z Retry-After. Integracja powinna czytać te sygnały, zwalniać i ponawiać operację później, zamiast natychmiast uruchamiać tę samą serię żądań.

Bezpieczna obsługa obejmuje:

• kolejkę z kontrolowaną współbieżnością;
• retry z rosnącym odstępem dla błędów przejściowych;
• brak automatycznego ponawiania błędów walidacji bez zmiany danych;
• idempotencję, aby powtórzenie nie tworzyło drugiego zamówienia lub dokumentu;
• rejestr operacji zakończonych, odrzuconych i wymagających ręcznej decyzji;
• alert po przekroczeniu uzgodnionego czasu lub liczby prób.

Operacje zbiorcze mogą ograniczyć liczbę wywołań, ale nie zwalniają z analizy wyniku każdego elementu. Częściowe powodzenie paczki trzeba rozliczyć rekord po rekordzie.

Webhooks czy cykliczne odpytywanie API

Webhook informuje system o zdarzeniu, dzięki czemu nie trzeba bez przerwy pytać sklepu o wszystkie zmiany. To dobry mechanizm do uruchomienia procesu po nowym zamówieniu lub aktualizacji danych, ale odbiornik webhooka również musi być odporny na powtórzenia, opóźnienia i chwilową niedostępność.

W praktyce stosuje się model hybrydowy:

• webhook szybko uruchamia obsługę zdarzenia;
• kolejka oddziela przyjęcie sygnału od właściwego przetwarzania;
• okresowa synchronizacja kontrolna wykrywa rekordy pominięte przez awarię;
• stan integracji pozwala ustalić, co zostało naprawdę zapisane w obu systemach.

Nie zakładaj, że kolejność dostarczenia zdarzeń zawsze odpowiada kolejności biznesowej. Jeśli kilka zmian dotyczy tego samego zamówienia, system powinien odczytać aktualny stan i stosować jawne reguły przejść.

Jak zaprojektować bezpieczną integrację Shoper API

Bezpośrednie połączenie każdego systemu z każdym szybko tworzy trudną do utrzymania sieć. Gdy proces obejmuje wielu partnerów, różne formaty danych albo uprawnienia zależne od roli, warto zastosować warstwę pośrednią. Taki middleware może ukryć dane administracyjne Shopera, walidować żądania, mapować identyfikatory i prowadzić audyt operacji.

Przed implementacją przygotuj kontrakt danych:

Takie podejście zastosowaliśmy w projekcie integratora zamówień API dla sklepu Shoper. Case study pokazuje zakres wdrożenia i architekturę pośrednią; nie jest uniwersalną obietnicą identycznego wyniku dla innego sklepu.

API Shoper a Storefront — dwa różne zakresy

REST API służy do integracji danych i procesów sklepu. Storefront dotyczy przede wszystkim szablonu oraz doświadczenia kupującego. Projekt może potrzebować obu warstw, ale zmiana motywu nie zastępuje integracji ERP, a połączenie zamówień przez API nie przebuduje karty produktu.

Jeżeli sklep nadal korzysta ze starszego motywu, zobacz zakres przejścia z Shoper RWD na Storefront. Przy wspólnym projekcie osobno odbieramy front, osobno przepływy API i dopiero potem testujemy ich punkty styku.

Checklista przed zleceniem integracji

• spisz systemy uczestniczące i właściciela każdego pola;
• podaj skalę: produkty, zamówienia, częstotliwość i sezonowe piki;
• opisz proces ręczny i momenty, w których dziś powstają błędy;
• ustal dozwolone operacje oraz dane, których partner nie może zobaczyć;
• wskaż wymaganą szybkość, dopuszczalne opóźnienie i procedurę awaryjną;
• uzgodnij środowisko testowe, kryteria odbioru i monitoring po uruchomieniu.

Jeśli chcesz połączyć Shopera z ERP, WMS albo systemem partnera, opisz przepływ i skalę procesu. Na tej podstawie można ocenić, czy wystarczy prosta integracja, czy potrzebna jest kolejka i warstwa middleware.

Źródła do ponownej weryfikacji przed wdrożeniem

• Shoper REST API — dokumentacja techniczna
• Shoper Storefront — oficjalna dokumentacja
• Shoper Storefront — JavaScript API
• Shoper Storefront — moduły