Jak połączyć magazyn ze sklepem Shoper przez REST API: limit zapytań, źródło prawdy dla stanów, mapa statusów i ponowienia po błędzie w wymianie danych.
Sklep na Shoperze przyjmuje zamówienie i płatność, a magazyn zaczyna pracę dopiero wtedy, gdy towar da się spakować. Studio WMS.net nie zastępuje panelu sklepu. Rezerwuje towar na lokalizacji, prowadzi kompletację i wydanie, a wynik odsyła do sklepu. Od 2024 roku historia marki wymienia integracje z platformami e-commerce (Baselinker, Shoper).
Ogólny przepływ danych między platformą a magazynem opisuje strona o integracji WMS z platformami e-commerce, a układ całego magazynu sklepu strona o WMS dla e-commerce. Ta strona zajmuje się tym, co jest specyficzne dla Shopera: zasobami API, limitem zapytań i statusami. Dane o API pochodzą z oficjalnej dokumentacji Shopera (stan na 6.10.2026). Drugą popularną drogę opisuje strona o integracji z BaseLinkerem.
Co Shoper udostępnia magazynowi
Jedno REST API, osobny zasób na każdy rodzaj danych i limit liczony na aplikację.
Zapytania kierujesz na adres sklepu z końcówką /webapi/rest/. Uwierzytelnienie opiera się na OAuth 2.0: aplikacja wysyła identyfikator i sekret metodą POST na /webapi/rest/auth, dostaje token i podaje go w nagłówku Authorization jako Bearer (dokumentacja uwierzytelnienia). Token ma ograniczoną ważność, więc usługa musi pobrać nowy bez udziału człowieka. Uprawnienia przydziela się osobno dla zasobu i czynności, na przykład orders_read albo orders_edit. Magazyn nie potrzebuje prawa usuwania zamówień, więc tego uprawnienia nie nadaje się w ogóle.
Limit liczy się na aplikację metodą cieknącego wiadra (dokumentacja żądań zbiorczych). Licznik bieżących wywołań wraca w nagłówku X-SHOP-API-CALLS, a pojemność wiadra w X-SHOP-API-LIMIT, domyślnie 10. Licznik maleje o wartość z X-SHOP-API-BANDWIDTH, domyślnie 2 na sekundę. Po przepełnieniu sklep zwraca błąd 429 z nagłówkiem Retry-After. Listy przychodzą stronami po najwyżej 50 rekordów (parametr limit, domyślnie 10), a do 25 wywołań można połączyć w jedno żądanie na /webapi/rest/bulk. Przy takim limicie liczy się kolejka z odstępem, a pojedyncze wywołanie nie ma znaczenia.
| Dane | Kierunek | Zasób lub zdarzenie | Ograniczenie z dokumentacji |
|---|---|---|---|
| Nowe zamówienia | Shoper → WMS | orders, webhook order.create | strony po najwyżej 50 rekordów |
| Opłacenie zamówienia | Shoper → WMS | webhook order.paid | sklep musi móc wywołać adres odbioru |
| Status zamówienia | WMS → Shoper | orders (PUT), statuses | status_id z listy sklepu; typy new, opened, closed, not completed |
| Stan towaru | WMS → Shoper | product-stocks | do 25 wywołań w jednym żądaniu bulk |
| Paczka i numer przesyłki | WMS → Shoper | parcels | nazwy pól potwierdza analiza |
Przepływ zamówienia od Shopera do kuriera
Zamówienie pobiera usługa Windows, a sklep dostaje z powrotem status i paczkę.
Zamówienie można pobrać dwiema drogami. Webhook order.create (albo order.paid) wywołuje adres odbioru zaraz po zdarzeniu (dokumentacja zdarzenia order.status). Odpytywanie zasobu orders co jakiś czas nie wymaga niczego poza łącznością wychodzącą. Usługa Windows w sieci klienta, która nawiązuje tylko połączenia wychodzące po HTTPS, nie wystawia adresu odbioru, więc przy tej konfiguracji zostaje odpytywanie. Webhook wymaga adresu, który sklep może wywołać z Internetu, a to jest decyzja o bezpieczeństwie sieci, nie o wygodzie.
Zdarzenie przyspiesza integrację, ale kompletność gwarantuje dopiero odczyt kontrolny listy zamówień. Magazyn nie może zależeć od jednego powiadomienia.
Schemat pokazuje podział ról. Usługa stoi pośrodku, bo to ona pilnuje limitu i kolejki. Sklep nie widzi struktury WMS, a WMS nie zna adresu API sklepu.
W Studio WMS.net zamówienie ze sklepu przyjmuje postać zlecenia wydania ZWZ z odbiorcą i przewoźnikiem w nagłówku. Kompletację prowadzi aplikacja magazynowa na Androidzie, a przy pakowaniu na podstawie ZWZ powstaje dokument WZ. Zasady pracy na hali opisuje strona o kompletacji zamówień.
Stany i źródło prawdy
Gdy sklep i magazyn liczą te same sztuki, ostatnie słowo ma ten, który zna rezerwacje.
Shoper zapisuje stan towaru w zasobie product-stocks. Fizyczną liczbę sztuk zna tylko magazyn, bo widzi skany i lokalizacje. Do sklepu powinien trafiać stan dostępny, czyli towar na półce pomniejszony o rezerwacje (opis na stronie o stanach magazynowych). Zmianę wykonuje żądanie PUT na wskazany wiersz zasobu, a wiele zmian łączy się w paczki po 25. Pełne uzgodnienie całego katalogu robi się poza godzinami szczytu, a w ciągu dnia wysyła się tylko pozycje, w których stan się zmienił. Domyślny ubytek 2 wywołań na sekundę nie pozwala inaczej.
| Dane | Prowadzi | Powód |
|---|---|---|
| Treść zamówienia, płatność, adres | Shoper | Zmienia się po stronie kupującego |
| Stan fizyczny i lokalizacja | WMS | Tylko magazyn widzi skany i dokumenty |
| Rezerwacja pod zamówienie | WMS | Powstaje przy zleceniu wydania |
| Stan widoczny w sklepie | WMS liczy, Shoper publikuje | Oferta ma pokazywać półkę pomniejszoną o rezerwacje |
| Opis i cena produktu | Shoper | Magazyn nie edytuje katalogu handlowego |
| Status zamówienia | WMS zmienia, Shoper przechowuje | Etap pracy wynika z dokumentu magazynowego |
Ręczna zmiana stanu w panelu sklepu zostanie nadpisana przy najbliższej synchronizacji. Albo sprzedawca przestaje edytować stan w panelu, albo każdą korektę wprowadza w magazynie.
Wiersz zasobu product-stocks trzeba połączyć z indeksem WMS po jednym polu, na przykład po kodzie produktu albo po numerze EAN. Które z nich sklep wypełnia konsekwentnie, sprawdza analiza. Zapas bezpieczeństwa dla towarów o małym stanie odejmuje się od wartości wysyłanej do sklepu, a jego wielkość ustala sprzedawca.
Statusy zamówień i ich mapowanie
Listę statusów tworzy sprzedawca, więc ich odpowiedniki w WMS trzeba uzgodnić.
Zasób statuses zwraca listę statusów sklepu. Każdy ma liczbowy identyfikator status_id i typ: new, opened, closed albo not completed. Zmianę wykonuje zapis pola status_id w zamówieniu (dokumentacja zasobu orders), a webhook order.status przesyła zmianę razem z identyfikatorem zamówienia i nowego statusu. Magazyn nie wyśle więc słowa „spakowane”, tylko identyfikator, który sprzedawca wcześniej założył. Przy statusie sklep przechowuje też ustawienie powiadomienia e-mail o zmianie, więc status pośredni może wysłać kupującemu wiadomość, której nikt nie planował.
| Zdarzenie w WMS | Dokument | Przykładowy status |
|---|---|---|
| Towar zarezerwowany, zlecenie zapisane | ZWZ | W realizacji |
| Kompletacja i pakowanie zakończone | WZ w toku | Spakowane |
| Paczka przekazana kurierowi | WZ zamknięty | Wysłane |
| Brak towaru na lokalizacji | ZWZ z uwagą | Wstrzymane do wyjaśnienia |
Przed każdą zmianą integracja odczytuje bieżący status zamówienia. Jeżeli sprzedawca anulował zamówienie w trakcie kompletacji, WMS tego nie nadpisuje. Zwalnia rezerwację i zgłasza towar do odłożenia na lokalizację. Nazwy statusów w tabeli są przykładami, a ich identyfikatory podaje sklep.
Etykiety i numery przesyłek
Dane paczki są znane dopiero przy pakowaniu, więc numer wraca do sklepu na końcu.
Informacje o przesyłce Shoper przechowuje w zasobie parcels, do którego magazyn zapisuje numer przesyłki po zamknięciu dokumentu WZ. Etykietę wystawia ten, kto ma skonfigurowaną umowę z przewoźnikiem. Gdy robi to magazyn przez Studio Spedycja.net (opis programu), numer listu przewozowego jest skojarzony z dokumentem WZ, a integracja zapisuje go w sklepie. Gdy etykietę tworzy narzędzie przewoźnika po stronie sklepu, numer wraca do WMS i trafia do tego samego dokumentu. Zasady wysyłki opisuje strona o firmach kurierskich. Nazwy pól zasobu parcels i obsługę poszczególnych przewoźników potwierdza analiza.
Zwroty od kupujących
Pieniądze wracają do kupującego ze sklepu, a towar do magazynu.
Zwrot płatności należy do sklepu i bramki płatniczej, a API Shopera ma dla niego osobne zasoby zwrotów i transakcji zamówienia. Magazyn zajmuje się towarem. Przyjmuje paczkę dokumentem przyjęcia i odkłada ją na wydzieloną lokalizację poza stanem dostępnym. Integracja wiąże paczkę z zamówieniem po numerze, więc magazynier widzi, co kupujący zamawiał. Dopiero ocena stanu decyduje, czy towar wraca na półkę sprzedażową. Wtedy stan dostępny rośnie, a kolejna synchronizacja wysyła do sklepu nową wartość. Decyzję o zwrocie pieniędzy podejmuje sprzedawca poza magazynem, na przykład w systemie ERP połączonym z WMS.
Błędy i ponowienia
Po awarii integracja ma dojść do poprawnego stanu bez ręcznej interwencji.
Kluczem każdej wymiany jest numer zamówienia ze sklepu, więc ponowione pobranie nie tworzy drugiego zlecenia. Zapis do Shopera trafia najpierw do tabeli wysyłkowej z unikalnym identyfikatorem komunikatu. Po powrocie łączności usługa wysyła tylko to, czego sklep jeszcze nie przyjął, i nie dubluje ruchu. Dokumentacja zaleca przy błędzie 429 i błędach serwera rosnące odstępy między próbami.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Błąd 429, przepełnione wiadro | Wywołania odrzucone | Pauza o wartość Retry-After, potem wznowienie kolejki |
| Wygasły token OAuth | Sklep odrzuca zapytania | Nowe uwierzytelnienie i powtórzenie wywołania |
| Webhook nie dotarł | Zamówienie czeka w sklepie | Odczyt kontrolny zasobu orders nadrabia lukę |
| Ten sam numer zamówienia pobrany dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
| Anulowanie w trakcie kompletacji | Ryzyko nadpisania decyzji sprzedawcy | Odczyt statusu przed zapisem i zwolnienie rezerwacji |
| Błąd serwera sklepu | Zapis nie doszedł | Ponowienie z rosnącym odstępem, alarm po kolejnej porażce |
Błąd, który zniknął po ponowieniu, nadal trzeba zapisać w dzienniku integracji. Bez zapisu nikt nie sprawdzi, czy wraca.
Co ustala analiza przedwdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Integracje w Studio WMS.net, w tym z platformami sprzedażowymi, wykonuje usługa Windows SSService.exe, instalowana na serwerze. Strona opisuje drogę wymiany i granice API Shopera, a nie listę gotowych ustawień ani gotowy moduł do tej platformy. Zakres dla konkretnego sklepu potwierdza analiza przedwdrożeniowa. Na liście decyzji są cztery pozycje:
- Pobieranie zamówień - webhook albo odpytywanie, oraz interwał przy domyślnym ubytku 2 wywołań na sekundę.
- Identyfikacja towaru - po czym łączy się indeks WMS z wierszem product-stocks. Wybór musi być jeden i spójny.
- Mapa statusów - które identyfikatory status_id odpowiadają etapom ZWZ i WZ, i które z nich wysyłają kupującemu e-mail.
- Przewoźnicy - kto wystawia etykietę i gdzie zapisuje się numer przesyłki.
Zakres prac programistycznych zależy od liczby i złożoności systemów, z którymi magazyn ma się komunikować. Zasady wyceny opisuje cennik.