Integracja WooCommerce z Subiektem – architektura i realne scenariusze

Integracja WooCommerce z Subiektem to dla wielu sklepów internetowych moment przełomowy: kończy się ręczne przepisywanie zamówień, a zaczyna uporządkowana, automatyczna wymiana danych. Dopiero przy rosnącej liczbie transakcji widać, jak ważna staje się dobrze zaprojektowana architektura integracji – taka, która nie tylko zepnie systemy ze sobą, ale także wytrzyma sezonowe piki sprzedaży, częste zmiany stanów magazynowych oraz wymagania działu księgowości i logistyki.

Modele architektury integracji WooCommerce – Subiekt

Bezpośrednia integracja po API Subiekta

Najprostszy logicznie model zakłada, że WooCommerce komunikuje się bezpośrednio z API Subiekta lub dedykowanym dodatkiem typu nexo/GT. Po stronie WordPressa działa wtyczka integracyjna, która w tle wysyła zapytania do Subiekta w momentach zdefiniowanych przez administratora sklepu.

Charakterystyczne cechy tego podejścia:

• brak pośrednich systemów – integracja jest relacją 1:1, WooCommerce ⇄ Subiekt
• niska złożoność wdrożenia, jeśli istnieje gotowy plugin
• większa zależność od stabilności serwera z Subiektem oraz od jakości samego API

W prostych przypadkach, przy kilku zamówieniach dziennie, taka integracja jest w pełni wystarczająca. Problemy pojawiają się, gdy rośnie liczba zmian stanów magazynowych, a Subiekt zaczyna pełnić rolę centralnego systemu obsługującego nie tylko e‑commerce, ale także sprzedaż stacjonarną i B2B.

Integracja z wykorzystaniem warstwy pośredniej (middleware)

Bardziej dojrzałe wdrożenia wykorzystują dodatkową warstwę integracyjną, czyli tzw. middleware. Jest to aplikacja lub usługa, która stoi pomiędzy WooCommerce a Subiektem, odbiera dane z jednego systemu, przetwarza je i przekazuje do drugiego. Taka warstwa może działać w chmurze lub na serwerze firmowym.

Kluczowe zalety middleware:

• możliwość kolejkowania komunikatów (brak utraty zamówień przy awarii jednego z systemów)
• łatwiejsza transformacja danych (mapowanie pól, jednostek miary, kodów VAT)
• dodawanie nowych kanałów sprzedaży bez ingerencji w Subiekta

Middleware sprawdza się zwłaszcza w organizacjach, które oprócz WooCommerce korzystają z marketplace’ów, aplikacji mobilnych lub systemów POS, a Subiekt ma pozostać centralnym systemem magazynowo‑księgowym.

Architektura oparta o zdarzenia i kolejki

Najbardziej skalowalny model wykorzystuje architekturę zdarzeniową (event-driven). WooCommerce emituje zdarzenia, takie jak:

• utworzono zamówienie
• zmieniono status zamówienia
• zaktualizowano produkt

Zdarzenia trafiają do kolejki (np. RabbitMQ, AWS SQS, Redis Streams), skąd odbiera je proces integracyjny odpowiedzialny za komunikację z Subiektem. W drugą stronę analogicznie – zmiany w Subiekcie również mogą być wystawiane jako zdarzenia odbierane przez WooCommerce.

Taki model bardzo dobrze znosi obciążenia sezonowe, np. w Black Friday, kiedy liczba zamówień zwiększa się kilkukrotnie. Zamiast natychmiastowej, blokującej komunikacji, integracja przetwarza komunikaty w tempie dostosowanym do wydajności Subiekta, jednocześnie nie gubiąc żadnych zmian.

Kryteria wyboru odpowiedniej architektury

Przy wyborze modelu integracji warto ocenić:

• planowaną skalę sprzedaży (liczba zamówień dziennie, liczba produktów)
• liczbę kanałów sprzedaży (tylko WooCommerce czy także marketplace’y, hurtownie, POS)
• dostępne kompetencje techniczne (czy firma ma zespół IT lub partnera integracyjnego)
• wymóg czasu zbliżonego do real-time (np. kluczowy jest aktualny stan magazynu)

W praktyce małe sklepy zwykle zaczynają od prostego, bezpośredniego połączenia. Wraz ze wzrostem sprzedaży i komplikacją procesów, architektura ewoluuje w stronę integracji z warstwą pośrednią oraz kolejkowaniem zdarzeń.

Zakres wymiany danych między WooCommerce a Subiektem

Synchronizacja produktów i kategorii

Najważniejsza decyzja dotyczy tego, który system ma być masterem danych produktowych. Jedne firmy budują ofertę w WooCommerce i eksportują ją do Subiekta, inne odwrotnie – utrzymują produkty w Subiekcie, a WooCommerce jest jedynie kanałem sprzedaży.

Zakres typowej synchronizacji produktów:

• nazwy produktów oraz opisy
• kategorie, ewentualnie drzewo kategorii
• kody EAN, SKU, symbole towarów
• ceny (detaliczne, hurtowe, promocje)
• powiązania z wariantami (rozmiar, kolor, model)

W Subiekcie dane produktowe są ściśle powiązane z ewidencją magazynową oraz podatkową. Dlatego przy integracji trzeba zwrócić uwagę na zgodność stawek VAT, jednostek miary oraz kodów CN/PKWiU w przypadku firm prowadzących intensywną sprawozdawczość.

Stany magazynowe i rezerwacje

Jednym z najbardziej newralgicznych obszarów jest synchronizacja stanów magazynowych. Subiekt zwykle jest traktowany jako główne źródło prawdy o ilościach towaru.

Typowy scenariusz:

• Subiekt wysyła do WooCommerce aktualne stany magazynowe (np. co 5 minut lub przy każdej zmianie)
• WooCommerce dokonuje rezerwacji towaru w momencie złożenia zamówienia
• Subiekt po imporcie zamówienia aktualizuje ilości i generuje dokumenty magazynowe (ZK, WZ)

Przy większym wolumenie sprzedaży dobrze jest dodać mechanizmy ochronne, np. limit maksymalnej różnicy między stanem w Subiekcie a WooCommerce, po którego przekroczeniu integracja wysyła alert do administratora lub czasowo blokuje sprzedaż danego produktu.

Dane klientów i kontrahentów

Integracja powinna jednoznacznie określić, kiedy i w jakim formacie do Subiekta trafiają dane klientów, takich jak:

• dane do faktury (NIP, adres firmy, nazwa)
• dane do wysyłki (imię, nazwisko, adres, telefon)
• tagi lub atrybuty wykorzystywane przez dział sprzedaży (np. kanał pozyskania klienta)

Najczęściej każdy klient z WooCommerce jest zapisywany w Subiekcie jako kontrahent. W praktyce pojawiają się tu problemy z duplikatami – ten sam klient może złożyć zamówienia z różnymi adresami, innym formatem nazwy firmy lub literówkami. Dlatego warstwa integracyjna powinna wdrożyć logikę rozpoznawania i łączenia kontrahentów według NIP, e‑maila czy telefonu.

Zamówienia, dokumenty sprzedaży i płatności

Centralnym elementem integracji są zamówienia. WooCommerce przechowuje je jako ordery, natomiast Subiekt jako dokumenty handlowe i magazynowe. Przeliczenie jednego modelu na drugi wymaga ustalenia kilku zasad biznesowych:

• na jakim etapie zamówienie z WooCommerce trafia do Subiekta (po opłaceniu, czy już po złożeniu)
• jakie typy dokumentów mają powstać (ZK, WZ, FS, PA, korekty)
• jak odwzorować statusy zamówień WooCommerce na statusy Subiekta

Ważne jest także powiązanie integracji z bramkami płatności. WooCommerce otrzymuje informację o zaksięgowaniu płatności (np. z Przelewy24, PayU, PayPal) i powinien odpowiednio zaktualizować zamówienie w Subiekcie – najczęściej poprzez zmianę statusu i dopisanie odpowiednich form płatności.

Realne scenariusze wdrożeń i problemy praktyczne

Sklep z dużą zmiennością cen i promocji

Wyobraźmy sobie sklep, w którym ceny produktów zmieniają się kilkukrotnie w ciągu dnia – np. w branży elektrotechnicznej, IT lub części samochodowych. W takim środowisku Subiekt bywa połączony z systemem dostawców, z którego na bieżąco pobierane są aktualne cenniki.

Wyzwania integracyjne:

• duża liczba aktualizacji cen i stanów przy tysiącach indeksów
• konieczność zachowania spójności między ceną w momencie zakupu a ceną na fakturze
• obsługa promocji warunkowych, np. rabaty progowe

Rozwiązaniem jest wprowadzenie do integracji bufora danych oraz zrozumiały dla biznesu harmonogram aktualizacji. Przykładowo: stany magazynowe są aktualizowane co 5 minut, natomiast ceny raz na godzinę lub przy ręcznym wymuszeniu przez operatora. Pozwala to zachować równowagę między aktualnością danych a wydajnością systemu.

Integracja sklepu omnichannel

Sklep, który oprócz WooCommerce posiada kilka salonów stacjonarnych, wymaga ściślejszego spięcia z Subiektem. Sprzedaż offline i online odbywa się na wspólnych stanach magazynowych, co rodzi ryzyko podwójnej sprzedaży tego samego towaru.

W takim scenariuszu Subiekt jest głównym systemem zarządzającym magazynem, natomiast:

• POS w salonach raportują sprzedaż w czasie zbliżonym do rzeczywistego
• WooCommerce rezerwuje towar już przy złożeniu zamówienia
• moduł integracyjny rozstrzyga konflikty stanów (np. kolejność priorytetów kanałów)

Warstwa middleware może przydzielać priorytety kanałom sprzedaży. Dla niektórych firm ważniejsza jest obsługa zamówień internetowych, dla innych klientów w salonach. Integracja powinna odzwierciedlać tę strategię, np. poprzez automatyczne zdejmowanie rezerwacji z zamówień o niższym priorytecie w sytuacji skrajnych braków.

Obsługa zwrotów, reklamacji i korekt

Często pomijanym na etapie projektu obszarem jest obsługa zwrotów i reklamacji. WooCommerce pozwala na ręczne oznaczanie zamówień jako zwrócone lub zreklamowane, Subiekt natomiast wymaga wystawienia odpowiednich korekt dokumentów magazynowych i faktur.

Scenariusz zwrotu może wyglądać następująco:

• klient zgłasza zwrot w sklepie internetowym
• operator zmienia status zamówienia na zwrot lub tworzy częściową korektę pozycji
• integracja generuje w Subiekcie dokument korekty i przyjęcia na magazyn

Kluczowe jest odwzorowanie częściowych zwrotów oraz sytuacji, w których klient zatrzymuje część zamówienia. Integracja musi potrafić rozdzielać pozycje zamówienia, przeliczać wartości oraz poprawnie ujmować je w rejestrach VAT i raportach sprzedaży.

Sklep z własną produkcją i kompletacją zestawów

W firmach, które prowadzą własną produkcję lub sprzedają zestawy (np. komputery składane na zamówienie, paczki prezentowe), Subiekt często odzwierciedla strukturę BOM (listy materiałowej), a WooCommerce prezentuje gotowy produkt końcowy.

Integracja musi uwzględnić, że sprzedaż jednego produktu w sklepie internetowym może oznaczać w Subiekcie ruch na wielu pozycjach magazynowych. Przy sprzedaży zestawu komputerowego składającego się z procesora, płyty głównej, RAM i obudowy, złożenie jednego zamówienia w WooCommerce wymaga:

• sprawdzenia dostępności wszystkich komponentów w Subiekcie
• rezerwacji odpowiednich ilości na magazynie
• ewentualnego wyzwolenia procesu produkcyjnego lub kompletacji

To typowy przykład, gdzie zwykłe mapowanie 1:1 pozycji nie wystarczy. Warstwa integracji powinna znać strukturę zestawów lub komunikować się z modułem produkcyjnym Subiekta, tak aby uniknąć sprzedaży produktów niewykonalnych w produkcji.

Aspekty techniczne i organizacyjne skutecznej integracji

Bezpieczeństwo i polityka dostępu

Integracja WooCommerce – Subiekt wiąże się z wymianą danych wrażliwych: informacji o klientach, transakcjach i dokumentach finansowych. Dlatego konieczne jest zaprojektowanie polityki dostępu:

• oddzielne konta techniczne w Subiekcie, z ograniczonymi uprawnieniami
• komunikacja po protokołach szyfrowanych (TLS), zwłaszcza przy dostępie z chmury
• logowanie wszystkich operacji integracyjnych w celach audytowych

Po stronie WordPressa należy zadbać o aktualizacje wtyczek integracyjnych, ochronę panelu administratora oraz regularne kopie zapasowe. Atak na sklep może pośrednio narazić na wyciek dane z Subiekta, jeśli integracja nie jest odpowiednio odseparowana.

Monitorowanie, logowanie i obsługa błędów

Każda poważniejsza integracja powinna posiadać wbudowany mechanizm monitoringu. Bez niego trudno zauważyć, że np. od trzech godzin nie synchronizują się stany magazynowe, a nowo dodane produkty nie pojawiają się w sklepie.

Kluczowe elementy monitoringu:

• logowanie wszystkich operacji (udanych i nieudanych) z możliwością filtrowania po numerze zamówienia, SKU, dacie
• alerty e‑mail lub do systemu typu Slack/Teams w przypadku błędów krytycznych
• panel integracyjny pozwalający na ręczne ponowienie wybranych operacji

Dobrą praktyką jest także wprowadzenie limitów powtórzeń. Jeśli danego zamówienia nie da się zaimportować do Subiekta z powodu brakującego produktu lub niezgodnej stawki VAT, integracja nie powinna próbować w nieskończoność, lecz zgłosić problem operatorowi.

Testy, środowiska i migracja z rozwiązań ręcznych

Przejście z ręcznego przepisywania zamówień do automatycznej integracji często wiąże się z lękiem przed utratą kontroli. Aby zminimalizować ryzyko, warto wdrożyć integrację etapami i na odseparowanych środowiskach:

• środowisko testowe Subiekta, z kopią części danych
• kopię sklepu WooCommerce na subdomenie testowej
• scenariusze testowe odzwierciedlające realne przypadki (promocje, rabaty, zwroty)

Przez pierwsze tygodnie integrację można uruchomić w trybie informacyjnym, w którym dane są wysyłane, ale nie wszystkie operacje skutkują utworzeniem dokumentów księgowych. Daje to zespołowi czas na dopracowanie mapowania pól, typów dokumentów i ścieżek wyjątków.

Rola partnera wdrożeniowego i utrzymanie w czasie

Integracja WooCommerce z Subiektem nie jest projektem jednorazowym, lecz procesem, który będzie ewoluował wraz z rozwojem firmy. Zmiany w przepisach podatkowych, nowi dostawcy, kolejne kanały sprzedaży – wszystko to wymusza modyfikacje w logice wymiany danych.

Dlatego warto mieć po swojej stronie partnera wdrożeniowego, który:

• zna zarówno WooCommerce, jak i specyfikę Subiekta (GT, nexo, nexo PRO)
• potrafi projektować procesy biznesowe, a nie tylko pisać kod
• zapewnia wsparcie powdrożeniowe, SLA i monitoring

Utrzymanie integracji obejmuje także regularne przeglądy konfiguracji oraz aktualizacje komponentów. Zmiana wersji Subiekta lub WooCommerce bez uprzedniego sprawdzenia kompatybilności z modułem integracyjnym jest jedną z najczęstszych przyczyn nagłych awarii, które pojawiają się w okresach największej sprzedaży.