Jak połączyć magazyn ze sklepem WooCommerce przez REST API: kto odejmuje stan, jak działają statusy i webhooki oraz jak ponowić wymianę danych po błędzie.
Sklep na WooCommerce liczy własny stan towaru i odejmuje go sam, gdy zamówienie przechodzi w odpowiedni status. Dla magazynu to główna trudność tej integracji: dwa systemy odejmują te same sztuki. Studio WMS.net rezerwuje towar na lokalizacji, prowadzi kompletację i wydanie, a do sklepu odsyła status i stan dostępny. 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. Tutaj schodzimy do punktów końcowych API i do decyzji, które trzeba podjąć przed pierwszą linią kodu. Dane o API pochodzą z oficjalnej dokumentacji REST API WooCommerce (stan na 6.10.2026). Sklepy na Shoperze opisuje strona o integracji WMS z Shoper.
Co WooCommerce udostępnia magazynowi
REST API w WordPressie, klucz z sekretem i brak podanego limitu zapytań.
REST API stoi pod adresem /wp-json/wc/v3/ i wymaga w WordPressie włączonych ładnych adresów (permalinków), bo z domyślnymi nie działa (opis wymagań). Uwierzytelnienie przez HTTPS opiera się na kluczu i sekrecie podawanych w nagłówku HTTP Basic. Dla zwykłego HTTP dokumentacja przewiduje OAuth 1.0a, ale zaleca HTTPS. Magazyn dostaje klucz z uprawnieniami, których naprawdę potrzebuje, a wyciek klucza wymaga jego wymiany.
Dokumentacja nie podaje limitu zapytań na minutę, więc o tempie decyduje wydajność serwera sklepu. Listy przychodzą stronami, domyślnie po 10 pozycji, a rozmiar strony jest ograniczony do 100 rekordów (zasady stronicowania WordPressa). Nagłówki X-WP-Total i X-WP-TotalPages mówią, ile jest rekordów i stron. Zamówienia i produkty można filtrować parametrem modified_after, a zapisy grupować w żądaniach batch do 100 obiektów.
| Dane | Kierunek | Punkt końcowy lub zdarzenie | Ograniczenie z dokumentacji |
|---|---|---|---|
| Nowe zamówienia | WooCommerce → WMS | GET /orders z modified_after; webhook order.created | stronicowanie nagłówkami, strona do 100 rekordów |
| Zmiana zamówienia | WooCommerce → WMS | webhook order.updated | wysyłany w tle przez wp-cron |
| Status zamówienia | WMS → WooCommerce | PUT /orders/{id}, pole status | osiem wartości domyślnych, w tym trash |
| Stan towaru | WMS → WooCommerce | /products/batch, /products/{id}/variations | do 100 obiektów w żądaniu |
| Numer przesyłki | WMS → WooCommerce | POST /orders/{id}/notes | flaga customer_note pokazuje notatkę kupującemu |
| Zwrot | WooCommerce → WMS | /orders/{id}/refunds | api_refund domyślnie true: zwraca bramka płatności |
Przepływ zamówienia i status w sklepie
Status zamówienia w sklepie rozstrzyga, kiedy magazyn ma zacząć pracę.
WooCommerce zmienia stan towaru przy statusie, a nie przy samym zamówieniu (dokumentacja statusów). Status pending oznacza zamówienie bez płatności i sztuki jeszcze się nie zmniejszają. Przy processing płatność jest zaksięgowana i sklep odjął sztuki. Status on-hold czeka na potwierdzenie płatności, a sztuki są już odjęte. Dlatego zlecenie wydania ZWZ powstaje po przejściu w processing. Przy przelewie tradycyjnym dochodzi decyzja o reakcji na on-hold, którą ustala analiza.
W Studio WMS.net zamówienie przyjmuje postać zlecenia wydania ZWZ z odbiorcą i przewoźnikiem w nagłówku. Kompletację prowadzi aplikacja magazynowa na Androidzie, a pakowanie zamyka dokument WZ. Zasady pracy na hali opisuje strona o kompletacji zamówień.
Stany i źródło prawdy
Sklep odejmuje sztuki sam, więc magazyn musi dopasować moment, w którym nadpisuje liczbę.
Stan w WooCommerce opisują pola manage_stock i stock_quantity, a dostępność pole stock_status (na przykład instock lub outofstock). Pole backorders decyduje, czy sklep sprzedaje poniżej zera. Dla produktu z wariantami stock_quantity produktu obowiązuje wszystkie warianty, chyba że stan podano na poziomie wariantu. Indeks WMS trzeba więc łączyć z wariantem, a nie z produktem nadrzędnym, i robi się to po kodzie SKU albo po EAN.
WMS wysyła stan dostępny, czyli towar na półce pomniejszony o rezerwacje (opis na stronie o stanach magazynowych), jako pełną wartość stock_quantity. Pełna wartość jest bezpieczniejsza niż różnica, bo powtórzenie zapisu niczego nie psuje.
| Dane | Prowadzi | Powód |
|---|---|---|
| Treść zamówienia i płatność | WooCommerce | Zmienia się po stronie kupującego |
| Stan fizyczny i lokalizacja | WMS | Tylko magazyn widzi skany i dokumenty |
| Liczba widoczna w ofercie | WMS liczy, WooCommerce publikuje | Sklep odejmuje sztuki sam i chwilowo wyprzedza WMS |
| Sprzedaż poniżej zera | Decyzja sprzedawcy w sklepie | Pole backorders ustawia się w produkcie |
| Status zamówienia | WMS zmienia, WooCommerce przechowuje | Etap pracy wynika z dokumentu magazynowego |
Kolejność ma znaczenie: najpierw pobrać nowe zamówienia, potem wysłać stan. Zapis starszy niż zamówienie, które sklep już odjął, zawyży liczbę w ofercie.
Taki zawyżony zapis powstaje, gdy sklep przyjął zamówienie i odjął sztuki, a WMS nie zdążył go jeszcze zarezerwować. Usługa pobiera więc zamówienia przed wysyłką stanu, a stan liczy dopiero po założeniu rezerwacji. 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
Domyślna lista statusów jest krótka, więc etapy pakowania często trafiają do notatek.
Dokumentacja REST API wymienia siedem domyślnych statusów, od pending po failed, a lista zamówień przyjmuje dodatkowo trash. Nie ma wśród nich statusu „spakowane”. Jeżeli sprzedawca nie dodał własnego, etap pakowania pokazuje notatka do zamówienia. Zmianę statusu wykonuje żądanie PUT z polem status, a webhook order.updated informuje WMS o zmianie po stronie sklepu.
| Zdarzenie w WMS | Dokument | Status w sklepie |
|---|---|---|
| Towar zarezerwowany, zlecenie zapisane | ZWZ | processing, bez zmiany |
| Kompletacja i pakowanie zakończone | WZ w toku | processing i notatka |
| Paczka przekazana kurierowi | WZ zamknięty | completed |
| Brak towaru na lokalizacji | ZWZ z uwagą | processing i notatka wewnętrzna |
Przed każdą zmianą integracja odczytuje bieżący status zamówienia. Gdy sprzedawca lub kupujący anulował zamówienie w trakcie kompletacji, sklep sam przywrócił sztuki, a WMS zwalnia rezerwację i zgłasza towar do odłożenia. Status anulowania zostaje bez zmian.
Etykiety i numery przesyłek
Dokumentacja zamówienia nie ma pola na numer przesyłki, więc wybór miejsca to decyzja.
Zamówienie w REST API nie ma osobnego pola numeru przesyłki. Numer można zapisać w notatce do zamówienia (POST na /orders/{id}/notes, a flaga customer_note pokazuje ją kupującemu), w polu własnym meta_data albo we wtyczce do śledzenia przesyłek, jeśli sklep ją ma. Etykietę wystawia ten, kto ma umowę z przewoźnikiem. Gdy robi to magazyn przez Studio Spedycja.net (opis programu), numer listu jest skojarzony z dokumentem WZ i trafia do sklepu po zamknięciu WZ. Zasady wysyłki opisuje strona o firmach kurierskich.
Zwroty od kupujących
Zwrot założony przez API może uruchomić prawdziwy zwrot pieniędzy.
Zwrot tworzy żądanie POST na /orders/{id}/refunds z kwotą zwrotu i listą pozycji. Parametr api_refund ma domyślnie wartość true, co oznacza, że zwrot generuje API bramki płatności.
Integracja magazynowa nie zakłada zwrotu w sklepie bez wyraźnej decyzji sprzedawcy. Domyślne api_refund=true uruchamia zwrot płatności w bramce.
Magazyn zajmuje się towarem. Przyjmuje paczkę dokumentem przyjęcia i odkłada ją na wydzieloną lokalizację poza stanem dostępnym, a integracja wiąże ją z zamówieniem po numerze. Pozycje zwrotu w sklepie pozwalają zestawić, co miało wrócić, z tym, co przyjęto. Decyzję o zwrocie pieniędzy podejmuje sprzedawca, na przykład w systemie ERP połączonym z WMS.
Błędy i ponowienia
Webhook potrafi sam się wyłączyć, więc sam nie wystarcza.
Webhooki WooCommerce wysyłają dane żądaniem POST, domyślnie w tle przez wp-cron, więc zdarzenie może przyjść z opóźnieniem (dokumentacja webhooków). Po pięciu kolejnych nieudanych dostarczeniach webhook zostaje wyłączony i trzeba go włączyć ponownie przez REST API. Nagłówek X-WC-Webhook-Signature niesie podpis HMAC-SHA256, którym odbiorca sprawdza autentyczność danych. Dlatego usługa robi odczyt kontrolny zamówień z parametrem modified_after i startuje od nieco wcześniejszej daty niż ostatni udany odczyt. Duplikaty odsiewa klucz zamówienia.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Webhook wyłączony po pięciu błędach | Zdarzenia przestają przychodzić | Odczyt kontrolny z modified_after, alarm i ponowne włączenie przez API |
| Opóźnienie wp-cron | Zdarzenie przychodzi późno | Odczyt kontrolny nie zależy od wp-cron |
| Przeciążony serwer sklepu | Zapisy kończą się błędem lub przekroczeniem czasu | Mniejsze paczki batch i ponowienie z rosnącym odstępem |
| Ten sam numer zamówienia pobrany dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
| Stan wysłany przed pobraniem zamówienia | Liczba w ofercie jest zawyżona | Kolejność: najpierw zamówienia, potem stan |
Każdy zapis do sklepu trafia najpierw do tabeli wysyłkowej z unikalnym identyfikatorem komunikatu. Po powrocie łączności usługa wysyła tylko to, czego sklep nie przyjął, bez dublowania ruchu. Błąd, który zniknął po ponowieniu, nadal trzeba zapisać w dzienniku integracji.
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 WooCommerce, a nie listę gotowych ustawień ani gotową wtyczkę do sklepu. Zakres dla konkretnego sklepu potwierdza analiza przedwdrożeniowa. Na liście decyzji są cztery pozycje:
- Zasady stanu - jak WMS nadpisuje stock_quantity przy tym, że sklep odejmuje sztuki sam, i co ustawia pole backorders.
- Pobieranie zamówień - webhook, odpytywanie albo oba naraz, oraz interwał odczytu kontrolnego.
- Statusy - kiedy WMS zmienia status na completed, czy sklep ma własne statusy i jakie notatki trafiają do kupującego.
- Numer przesyłki - notatka, pole własne albo wtyczka do śledzenia.
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.