Jak połączyć magazyn z Magento i Adobe Commerce przez REST API: zamówienia ze sklepu, ilości na źródłach MSI oraz status i numer przesyłki po spakowaniu.
Sklep na Magento albo Adobe Commerce potrafi trzymać zapasy w kilku miejscach naraz, więc magazyn musi wiedzieć nie tylko, ile towaru jest, ale też na którym źródle. Studio WMS.net prowadzi stan fizyczny na lokalizacjach i rezerwuje towar pod zamówienie. Do sklepu odsyła przesyłkę oraz ilość na źródle. Płatność i treść zamówienia zostają w Magento.
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. Tutaj schodzimy do interfejsów Magento i do modelu zapasów MSI. Dane pochodzą z dokumentacji Adobe Commerce dla programistów (stan na 6.10.2026). Zakres funkcji może się różnić między Adobe Commerce a Magento Open Source, a wariant Adobe Commerce as a Cloud Service ma własne adresy API, więc wersję sklepu potwierdza analiza.
REST i GraphQL w Magento
Do wymiany między serwerami służy REST, a GraphQL obsługuje witryny headless.
Dokumentacja REST podaje adres w postaci https://host/rest/kod-widoku-sklepu/endpoint. W Adobe Commerce as a Cloud Service adres wygląda inaczej (https://serwer.api.commerce.adobe.com/id-dzierżawy/endpoint), a uwierzytelnienie przechodzi przez Adobe Identity Management Service. GraphQL opisano jako interfejs dla headless storefrontów i aplikacji mobilnych, więc do wymiany z magazynem wybieramy REST.
Wywołania uwierzytelnia token albo OAuth 1.0a dla aplikacji zewnętrznych, a tokeny powinny chodzić po HTTPS. Przykłady z dokumentacji wysyłają token administratora w nagłówku Authorization. Zakres roli konta integracji ustala analiza.
Zapisy można wysyłać także asynchronicznie, z segmentem async w adresie, na przykład /rest/kod-widoku/async/V1/products. Odpowiedź zawiera bulk_uuid, a operacje wykonuje konsument kolejki async.operations.all. Metoda GET nie jest w tym trybie obsługiwana. Tryb pomaga przy dużych paczkach, ale oddziela przyjęcie zapytania od jego wykonania, więc integracja sprawdza wynik po bulk_uuid. Które endpointy sklepu mają wariant asynchroniczny, ustala analiza.
| Dane | Kierunek | Endpoint REST | Uwaga z dokumentacji |
|---|---|---|---|
| Nowe zamówienia | Magento → WMS | GET /V1/orders | Filtry searchCriteria po statusie i created_at |
| Ilość na źródle | WMS → Magento | POST /V1/inventory/source-items | Tablica sourceItems z sku i source_code oraz quantity i status |
| Ilość możliwa do sprzedaży | Magento → WMS | GET /V1/inventory/get-product-salable-quantity/:sku/:stockId | Zwraca liczbę całkowitą; służy do kontroli |
| Przesyłka i numer listu | WMS → Magento | POST /V1/order/{orderId}/ship | Pozycje order_item_id i qty, opcjonalnie tracks |
| Zwrot pieniędzy | sklep → WMS | POST /V1/order/{orderId}/refund | Wariant dla płatności online: POST /V1/invoice/{invoiceId}/refund |
Przepływ zamówienia od sklepu do kuriera
Zlecenie wydania powstaje po opłaceniu, a przesyłka po spakowaniu.
Zamówienia pobiera GET /V1/orders z parametrem searchCriteria. Filtr łączy pole z wartością i operatorem condition_type, na przykład eq albo gt. Kilka filtrów w jednej grupie działa jak OR, a osobne grupy jak AND. Stronicowanie obsługują pageSize i currentPage, a kolejność sortOrders. Dla magazynu typowe jest zapytanie o wybrany status z datą created_at późniejszą niż ostatnia pobrana, co opisuje dokumentacja wyszukiwania.
Zamówienie przechodzi w Magento przez dokumenty. Najpierw powstaje faktura (POST /V1/order/{orderId}/invoice), a po spakowaniu przesyłka. Korektę wystawia się dopiero po zwrocie. Zlecenie wydania powinno powstać po opłaceniu, czyli po fakturze albo w statusie, który sklep uznaje za opłacony. Dla płatności przy odbiorze moment zwolnienia 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 sku. Kompletację prowadzi aplikacja magazynowa na Androida, a zasady pracy na hali opisuje strona o kompletacji zamówień. Dokument WZ powstaje przy pakowaniu, jak pokazuje strona o dokumentach WZ.
Źródła zapasów i ilość możliwa do sprzedaży
Magento liczy ilość do sprzedaży osobno od ilości fizycznej.
Model MSI rozdziela kilka pojęć. Źródło (source) to fizyczne miejsce, które przechowuje i wysyła towar, na przykład magazyn albo sklep stacjonarny. Stock łączy kanał sprzedaży, obecnie witrynę, ze źródłami. Ilość na źródle zapisuje obiekt SourceItem, do którego wolno pisać, a StockItem to wartość zagregowana tylko do odczytu, powstająca przy reindeksacji. Tak opisuje to dokumentacja Inventory Management.
Rezerwacje pomniejszają ilość możliwą do sprzedaży od chwili złożenia zamówienia. Dopiero przesyłka zamienia rezerwację w odjęcie ilości na źródle. Anulowanie wprowadza kompensatę i zwraca ilość do puli, jak opisuje strona o statusach zamówień i rezerwacjach.
W praktyce źródło Magento odpowiada magazynowi albo strefie w WMS, a kod source_code łączy oba światy. Magazyn wysyła POST /V1/inventory/source-items z tablicą sourceItems, w której pozycja ma sku i source_code oraz opcjonalnie quantity i status (0 oznacza brak towaru, 1 dostępność). Magento przypisuje istniejące produkty do źródła domyślnego, więc sklep z jednym magazynem zaczyna od jednego kodu źródła. Organizację kilku oddziałów w jednym systemie opisuje strona o module Wieloodziałowość.
Do Magento wysyła się ilość fizyczną na źródle, a nie ilość pomniejszoną o rezerwacje. Rezerwacje odejmuje Magento, więc dwa systemy odejmujące je naraz zdwoją ubytek.
Druga pułapka dotyczy przesyłki. Każda przesyłka odejmuje w Magento ilość ze źródła, więc zapis nowej, już pomniejszonej wartości z WMS tuż po wydaniu mógłby odjąć ten sam towar dwa razy. Dlatego kolejność jest stała: najpierw przesyłka, potem bezwzględna wartość z lokalizacji. Wartość bezwzględna nadpisuje wynik odejmowania, a nie dodaje do niego różnicy.
| Dane | Źródło prawdy | Powód |
|---|---|---|
| Treść zamówienia, płatność, adres | Magento | Zmienia się po stronie kupującego, nie magazynu |
| Stan fizyczny i lokalizacja | WMS | Tylko magazyn widzi skany i dokumenty |
| Ilość na źródle (SourceItem) | WMS zapisuje, Magento przechowuje | Źródło zasilane jest ilością fizyczną |
| Rezerwacja pod zamówienie sklepu | Magento | Powstaje przy złożeniu zamówienia |
| Ilość możliwa do sprzedaży | Magento liczy, WMS kontroluje odczytem | Wynika ze źródeł stocku i rezerwacji |
| Wybór źródła dla przesyłki | do ustalenia w analizie | Algorytm SSA albo decyzja WMS na podstawie lokalizacji |
Algorytm wyboru źródła (SSA) ma w Magento dwie wersje. Priority wybiera źródło według ustalonego priorytetu, a distance według odległości od adresu dostawy. Odpowiedź POST /V1/inventory/source-selection-algorithm-result wskazuje źródła, ilości do odjęcia i flagę shippable. Gdy zapasy leżą w kilku magazynach WMS, trzeba zdecydować, czy źródło wybiera Magento, czy WMS.
Stany i statusy zamówień
Magento rozróżnia stan używany programowo i status widoczny dla ludzi.
Według dokumentacji statusów stan (state) decyduje o dostępnych operacjach i nie jest widoczny dla klienta ani administratora. Status służy do komunikacji z nimi. Sprzedawca może dodać własne statusy i przypisać je do stanów, ale w przebiegu zamówienia działają tylko statusy ustawione jako domyślne dla stanu. Pozostałe służą wyłącznie w komentarzach.
Etapy magazynowe, takie jak kompletacja, nie mają więc własnych stanów w Magento. Magazyn odzwierciedla je dokumentami (faktura, przesyłka) albo komentarzem z własnym statusem, a wybór ustala analiza. Po pełnej przesyłce Magento samo zmienia status na Complete.
| Status | Znaczenie według dokumentacji | Reakcja WMS |
|---|---|---|
| received | Status początkowy przy asynchronicznym składaniu zamówień | Czekanie na kolejny status, zlecenie nie powstaje |
| pending | Brak faktury i przesyłki | Zlecenie po opłaceniu, zależnie od płatności |
| holded | Wstrzymanie ustawiane ręcznie | Wstrzymanie zlecenia i zwolnienie kompletacji |
| complete | Zamówienie utworzone, opłacone i wysłane | WZ zamknięty, nic do zrobienia |
| closed | Wystawiono credit memo i zwrócono pieniądze | Przyjęcie zwrotu, jeśli towar wraca |
| canceled | Ręcznie w panelu albo przy braku płatności w terminie | Zwolnienie rezerwacji w WMS |
Przesyłki i numer listu
Przesyłkę zakłada się po zamknięciu WZ, bo wtedy znane są liczby sztuk.
Endpoint POST /V1/order/{orderId}/ship przyjmuje tablicę items z polami order_item_id i qty oraz pole notify. Opcjonalna tablica tracks niesie numer listu (track_number) i kod przewoźnika (carrier_code). Do przesyłki częściowej wystarczy podać tylko te pozycje, które wychodzą teraz.
Gdy na jednej pozycji brakuje towaru, powstaje przesyłka częściowa, a reszta zamówienia czeka na dostawę. Etykietę przygotowuje magazyn: integracja ze Studio Spedycja.net rejestruje numery listów i kojarzy je z dokumentami WZ, jak opisuje strona o wysyłce przez firmy kurierskie. Numer trafia do Magento w tablicy tracks razem z przesyłką.
Zwroty i credit memo
Zwrot pieniędzy zamyka credit memo, ale towar wraca fizycznie przez magazyn.
Dokumentacja opisuje dwa endpointy: POST /V1/order/{orderId}/refund dla faktur z płatnością offline i POST /V1/invoice/{invoiceId}/refund dla płatności online. Wywołanie niewłaściwego dla metody płatności kończy się błędem walidacji. Decyzję o zwrocie pieniędzy podejmuje sprzedawca, na przykład w systemie ERP połączonym z WMS.
Credit memo wpływa na zapasy. Przy opcji Return to Stock ilość wraca do źródeł i do puli możliwej do sprzedaży. Jeżeli paczka dopiero jedzie do magazynu, oferta pokaże towar, zanim ktokolwiek go oceni. Analiza rozstrzyga więc, czy ilość wraca przez Return to Stock, czy przez dokument przyjęcia w WMS i późniejszy zapis na źródło. W drugim wariancie paczka leży na lokalizacji poza stanem dostępnym do chwili oceny.
Błędy i ponowienia
Po awarii integracja ma dojść do poprawnego stanu bez ręcznej interwencji.
Kluczem wymiany jest numer zamówienia (increment_id) razem z identyfikatorem entity_id. Pobranie zamówień jest bezpieczne do powtórzenia, bo GET niczego nie zmienia. Zapisy trafiają do tabeli wysyłkowej z ponawianiem i unikalnym identyfikatorem komunikatu, więc po powrocie łączności ruch nie dubluje się. W trybie asynchronicznym odpowiedź accepted oznacza tylko przyjęcie zapytania, a wynik trzeba odczytać po bulk_uuid.
| Sytuacja | Skutek | Reakcja integracji |
|---|---|---|
| Token odrzucony albo rola bez uprawnień | Zapytania nie przechodzą | Alarm, odnowienie tokenu i kontrola roli |
| Zapis asynchroniczny przyjęty, ale niewykonany | Odpowiedź accepted bez zmiany w sklepie | Sprawdzenie bulk_uuid i konsumenta kolejki |
| Przesyłka dla zamówienia już wysłanego | Zdwojony dokument | Odczyt statusu i przesyłek przed zapisem |
| Ilość źródła nadpisana w czasie przesyłki | Podwójne odjęcie towaru | Wartość bezwzględna po zapisie przesyłki |
| Nieznany sku lub source_code w sklepie | Pozycja odrzucona | Wpis w dzienniku i lista rozbieżności do poprawy w kartotece |
| Ten sam numer zamówienia pobrany dwa razy | Zdwojone zlecenie wydania | Odrzucenie drugiej próby po kluczu zamówienia |
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 REST, a nie gotowy moduł do instalacji w Magento. Które endpointy 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:
- Źródła i stocki - które magazyny WMS odpowiadają kodom source_code i który stock obsługuje witrynę.
- Wybór źródła - czy źródło dla przesyłki wskazuje algorytm SSA Magento, czy WMS na podstawie lokalizacji.
- Dokumenty i statusy - po której fakturze lub którym statusie powstaje zlecenie wydania i jak magazyn zgłasza etapy.
- Zwroty i wersja sklepu - czy ilość wraca przez Return to Stock, czy przez przyjęcie w WMS, oraz którą wersję Magento obsługujemy.
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.