Jak połączyć magazyn ze sklepem PrestaShop przez Webservice: kto prowadzi stan dostępny, jak zmienia się status zamówienia i co robi integracja po błędzie.
PrestaShop trzyma w sklepie zamówienia i stany towaru, a magazyn potrzebuje z nich tylko tego, co 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: status zamówienia i numer przesyłki. Stan dostępny wraca tą samą drogą.
Ogólny przepływ danych między platformą a magazynem opisuje strona o integracji WMS z platformami e-commerce, a układ magazynu sklepu strona o WMS dla e-commerce. Drogę przez warstwę pośrednią pokazuje integracja WMS z BaseLinkerem, a sprzedaż na Allegro integracja WMS z Allegro. Tutaj schodzimy do Webservice PrestaShop, czyli interfejsu, przez który magazyn rozmawia ze sklepem bezpośrednio. Opis opiera się na dokumentacji dla programistów PrestaShop 9 (stan na 6.10.2026), więc wersję sklepu potwierdza analiza.
Co udostępnia Webservice PrestaShop
Jeden interfejs CRUD i osobny zasób na każdy rodzaj danych.
Webservice daje dostęp do bazy sklepu przez operacje CRUD: POST tworzy rekord, GET go czyta, PUT aktualizuje, PATCH zmienia wybrane pola, a DELETE usuwa. Adres leży w katalogu /api/ instalacji sklepu. Uwierzytelnienie opiera się na kluczu API podanym jako nazwa użytkownika przy pustym haśle, a dokumentacja zaleca nagłówek autoryzacji zamiast klucza w adresie.
Interfejs włącza się w panelu sklepu w sekcji Advanced Parameters > Web service, gdzie powstaje też 32-znakowy klucz. Uprawnienia nadaje się osobno dla każdego zasobu i każdej metody. Instrukcja tworzenia dostępu radzi nie dawać kluczom API wszystkich praw do wszystkich zasobów, więc magazyn dostaje osobny klucz z odczytem zamówień i zapisem w kilku zasobach opisanych niżej.
Odpowiedź da się zawęzić. Parametr display wybiera pola, filter[pole]=wartość filtruje rekordy, a limit=0,100 ogranicza ich liczbę. Wynik porządkuje sort, a zakres dat wymaga date=1. Format JSON włącza output_format=JSON. Schemat zasobu pokazuje schema=synopsis, co oszczędza zgadywania nazw pól.
| Dane | Kierunek | Zasób | Uwaga z dokumentacji |
|---|---|---|---|
| Nowe zamówienia | sklep → WMS | orders | Pole current_state da się filtrować; pozycje w order_rows niosą referencję i EAN13 |
| Stan dostępny | WMS → sklep | stock_availables | Rekord dotyczy produktu i kombinacji; ilość w polu quantity |
| Status zamówienia | WMS → sklep | order_histories | POST z id_order i id_order_state; sendemail=1 wysyła e-mail |
| Numer przesyłki | WMS → sklep | order_carriers | Pole tracking_number; wymagane id_order i id_carrier |
| Korekta po zwrocie | sklep → WMS | order_slip | Dokument korygujący z pozycjami order_slip_details |
Opis zasobów nie podaje limitu zapytań na minutę. Tempo wymiany ogranicza więc wydajność hostingu sklepu, a nie reguła interfejsu, i ustala je analiza.
Przepływ zamówienia od sklepu do kuriera
Magazyn odpytuje sklep i odpowiada po każdym etapie.
Webservice odpowiada na zapytania, więc to magazyn sprawdza, czy pojawiły się nowe zamówienia. Integracja filtruje je po statusie (filter[current_state]), sortuje rosnąco po identyfikatorze i pobiera partiami przez limit. Zlecenie wydania powstaje dla zamówienia w statusie, który sklep uznaje za opłacony. Które statusy to oznaczają, a także czy sklep potrafi sam powiadomić magazyn o nowym zamówieniu, ustala analiza.
W Studio WMS.net zamówienie przyjmuje postać zlecenia wydania ZWZ z odbiorcą i przewoźnikiem w nagłówku. Pozycje łączy się z indeksem towaru po referencji albo po EAN13, bo oba pola leżą w order_rows. Kompletację prowadzi aplikacja magazynowa na Androida, a zasady pracy na hali opisuje strona o kompletacji zamówień. Przy pakowaniu na podstawie ZWZ powstaje dokument WZ, który omawia strona o dokumentach WZ.
Stany magazynowe w PrestaShop
Zasób stock_availables przyjmuje ilość dla produktu i jego kombinacji.
Stan towaru w sklepie leży w zasobie stock_availables. Rekord wiąże ilość (quantity) z produktem i jego kombinacją (id_product_attribute), a pola depends_on_stock i out_of_stock opisują zależność od magazynu oraz zachowanie sklepu przy braku towaru. W sklepie z kombinacjami, na przykład rozmiarami i kolorami, stan wysyła się osobno dla każdej kombinacji. Indeks WMS musi więc wskazywać kombinację, a nie tylko produkt.
Dokumentacja opisuje aktualizację na dwa sposoby: PUT z pełnym, wcześniej pobranym zasobem albo PATCH z samym identyfikatorem i zmienionymi polami. Dla stanów wygodniejszy jest PATCH, bo przenosi tylko liczbę, ale o jego przyjęciu przez ten zasób w danej wersji sklepu rozstrzyga test w analizie. Do sklepu powinien trafiać stan dostępny, czyli towar na półce pomniejszony o rezerwacje, który opisuje strona o stanach magazynowych.
| Dane | Źródło prawdy | Powód |
|---|---|---|
| Treść zamówienia, płatność, adres | PrestaShop | Zmienia się po stronie kupującego, nie magazynu |
| Stan fizyczny i lokalizacja | WMS | Tylko magazyn widzi skany i dokumenty |
| Rezerwacja pod zamówienie | WMS | Powstaje przy zleceniu wydania |
| Stan dostępny w sklepie | WMS liczy, PrestaShop publikuje | Oferta ma pokazywać półkę pomniejszoną o rezerwacje |
| Status realizacji | WMS zmienia, PrestaShop pokazuje | Etap pracy wynika z dokumentu magazynowego |
Stan dostępny w sklepie liczy jeden system, ten, który zna rezerwacje. Ręczna zmiana quantity w panelu sklepu przy jednoczesnym zapisie z WMS kończy się rozjazdem, którego nikt nie wyjaśni po fakcie.
Po inwentaryzacji do sklepu wysyła się pełną wartość quantity, a nie różnicę, bo powtórzenie takiego zapisu niczego nie psuje. Zapas bezpieczeństwa dla towarów o małym stanie ustala analiza.
Statusy zamówień i ich mapowanie
Statusy zakłada sprzedawca, więc ich odpowiedniki w WMS trzeba uzgodnić.
Zasób order_states opisuje status: jego nazwę w wielu językach oraz flagi, na przykład paid i shipped. Do statusu przypisano też szablon wiadomości. Magazyn nie wyśle więc słowa „spakowane”, tylko identyfikator statusu, który sprzedawca wcześniej założył. Zmianę wykonuje POST do order_histories z wymaganymi polami id_order i id_order_state.
Parametr sendemail=1 uruchamia wiadomość do kupującego zgodną z szablonem statusu. Wysyłka e-maila przy każdej zmianie bywa niepożądana, dlatego analiza wskazuje, które zmiany ją wywołują. Tabela podaje punkt wyjścia, a nazwy w ostatniej kolumnie są przykładami.
| Zdarzenie w WMS | Dokument | Przykładowy status | Zapis |
|---|---|---|---|
| Towar zarezerwowany, zlecenie zapisane | ZWZ | W przygotowaniu | POST order_histories |
| Kompletacja i pakowanie zakończone | WZ w toku | Spakowane | POST order_histories |
| Paczka przekazana kurierowi | WZ zamknięty | Wysłane | numer listu, potem POST order_histories |
| Brak towaru na lokalizacji | ZWZ z uwagą | Wstrzymane do wyjaśnienia | POST order_histories bez e-maila |
Jedna reguła chroni przed błędem: przed zmianą statusu integracja odczytuje bieżący current_state 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ę.
Przesyłki i numer listu
Numer listu powstaje po spakowaniu i wraca do sklepu przed zmianą statusu.
Numer przesyłki ma w PrestaShop dwa miejsca. Pole shipping_number leży w zasobie orders, a pole tracking_number w zasobie order_carriers, który wiąże zamówienie z przewoźnikiem. Magazyn zapisuje numer w order_carriers, a który z dwóch zasobów sklep pokazuje kupującemu, sprawdza analiza.
Etykietę kurierską magazyn przygotowuje sam. Integracja ze Studio Spedycja.net rejestruje numery listów i kojarzy je z dokumentami WZ, a drukarka etykiet drukuje je na stanowisku pakowania, jak opisuje strona o wysyłce przez firmy kurierskie. Numer zapisuje się przed zmianą statusu na wysłane, bo kupujący po tej zmianie od razu szuka listu.
Zwroty i dokumenty korygujące
Sklep rozlicza pieniądze, a magazyn przyjmuje towar.
Dokumentacja opisuje zasób order_slip, czyli dokument korygujący z kwotami i pozycjami order_slip_details. Odpowiada on na pytanie o pieniądze, a nie o towar. Magazyn odpowiada za paczkę: przyjmuje ją dokumentem przyjęcia, odkłada na wydzieloną lokalizację poza stanem dostępnym i dopiero po ocenie zwraca na półkę sprzedażową.
Zwrot wiąże się z zamówieniem po polu id_order, więc magazynier skanujący paczkę widzi, co kupujący zamawiał. Czy sklep rejestruje zwrot towaru osobnym zasobem Webservice, czy tylko wystawia dokument korygujący, potwierdza analiza. 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.
Każda wymiana ma jawny klucz, którym jest numer zamówienia z pola reference albo jego identyfikator. Dzięki temu ponowione pobranie nie tworzy drugiego zlecenia, a powtórzony zapis quantity niczego nie zmienia. Wychodzące komunikaty trafiają do tabeli wysyłkowej z ponawianiem i unikalnym identyfikatorem, więc po powrocie łączności ruch nie dubluje się.
Wyjątkiem jest POST do order_histories, bo każde wywołanie dodaje nowy wpis historii. Powtórzenie po błędzie sieci mogłoby więc zapisać status dwa razy i wysłać drugi e-mail. Dlatego integracja czyta current_state przed zapisem i pomija zmianę, która już zaszła.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Klucz wyłączony albo bez uprawnienia do zasobu | Zapytania odrzucone | Alarm i kontrola uprawnień klucza dla każdego zasobu |
| Sklep wolny lub niedostępny | Brak odpowiedzi | Kolejka wychodząca i ponowienie po wydłużanym odstępie |
| Powtórzony POST do order_histories | Drugi wpis historii i drugi e-mail | Odczyt current_state przed zapisem |
| Ten sam numer zamówienia pobrany dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
| Status zmieniony ręcznie w sklepie w trakcie kompletacji | Rozjazd statusów | Odczyt przed zapisem i reguła z analizy |
Błąd, który zniknął po ponowieniu, nadal trzeba zapisać w dzienniku integracji. Bez zapisu nikt nie sprawdzi, czy wraca.
Kto wykonuje integrację po stronie Studio WMS.net
Usługa Windows na serwerze, a zakres dla sklepu potwierdza analiza.
Integracje w Studio WMS.net, w tym z platformami sprzedażowymi, wykonuje usługa Windows SSService.exe instalowana na serwerze. Działa w sieci klienta i łączy się ze sklepem ruchem wychodzącym HTTPS, więc nie trzeba publikować w Internecie punktu dostępowego magazynu.
Strona opisuje drogę wymiany przez Webservice, a nie gotowy moduł do instalacji w sklepie. Które zasoby wchodzą w zakres dla danego sklepu, potwierdza analiza przedwdrożeniowa. Zachowanie przy awarii opisuje sekcja o błędach i ponowieniach.
Co ustala analiza wdrożeniowa
Cztery decyzje, od których zależy zakres prac.
Zakres integracji dla konkretnego sklepu wynika z analizy przedwdrożeniowej. Na liście decyzji są cztery pozycje:
- Statusy sklepu - które identyfikatory order_states odpowiadają etapom ZWZ i WZ oraz które zmiany wysyłają e-mail.
- Identyfikacja towaru - po czym łączy się indeks WMS z produktem i kombinacją: referencja czy EAN13.
- Tempo wymiany - jak często pobiera się zamówienia i wysyła stany przy wydajności hostingu sklepu.
- Przesyłki i zwroty - gdzie zapisuje się numer listu i jak sklep rejestruje zwrot towaru.
Zakres prac programistycznych zależy od liczby i złożoności systemów, z którymi magazyn ma się komunikować, a zasady wyceny opisuje cennik.