Integracje WooCommerce z ERP i API hurtowni

#Integracje WooCommerce z ERP i API hurtowni

Jeżeli szukasz ogólnego wsparcia przy budowie i rozwoju sklepu, zacznij od strony programista WooCommerce. Szerszy kontekst architektury (headless, ERP i dane pod AI) opisujemy w rozwiązaniach Enterprise. Ta strona dotyczy węższego, bardziej technicznego problemu: wymiany danych między WooCommerce a systemami zewnętrznymi.

#Czym jest integracja WooCommerce z systemem zewnętrznym

W większości sklepów prawda o produktach nie mieszka w WooCommerce. Mieszka w ERP, w systemie magazynowym albo w API hurtowni. WooCommerce jest witryną sprzedażową, ale stany, ceny i część danych produktowych pochodzą skądinąd. Integracja to warstwa, która utrzymuje te dwa światy w zgodzie.

W praktyce integracja odpowiada na trzy pytania:

• Co synchronizujemy - katalog, atrybuty, stany magazynowe, ceny, zamówienia, dane klientów.
• W którą stronę - jednokierunkowo (system źródłowy dyktuje sklepowi) albo dwukierunkowo (np. zamówienia wracają do ERP).
• Jak często - od cyklicznego odpytywania co kilka minut po zdarzeniowe aktualizacje przez webhooki.

#Co można zintegrować z WooCommerce

Nie musisz robić wszystkiego naraz. Najczęstszy pierwszy krok to synchronizacja stanów i cen, bo to ona najszybciej zwraca się w odzyskanym czasie obsługi i uniknietych zwrotach.

#Jak działa synchronizacja danych

Mechanika jest wszędzie podobna, niezależnie od tego, czy źródłem jest ERP, czy API hurtowni. Różni się źródło, nie zasada.

#Mapowanie danych

System źródłowy opisuje produkty własną strukturą pól. Pierwsza praca integracji to przełożyć ją na model produktów i atrybutów WooCommerce: EAN i indeks jako klucze łączące rekordy, atrybuty techniczne na atrybuty i warianty, media i opisy na karty produktów. Mapę pól trzymamy deklaratywnie, więc dodanie nowego parametru to rozszerzenie mapowania, nie przepisywanie logiki.

#Synchronizacja stanów i cen

Sercem większości integracji jest cykliczne pobieranie dwóch rzeczy: stanu magazynowego i ceny. Pozycje niedostępne w systemie źródłowym są automatycznie ukrywane albo oznaczane jako niedostępne, co eliminuje najkosztowniejszy błąd sklepu, czyli sprzedaż czegoś, czego nie da się zrealizować. Zmiana ceny w systemie źródłowym przenosi się do sklepu przy najbliższym cyklu.

#Logika marżowa

Ceny z ERP czy hurtowni to zwykle koszt, nie cena sprzedaży. Nad warstwą pobierania danych działa logika marżowa: na cenę źródłową system narzuca zdefiniowaną marżę i dopiero wynik trafia do WooCommerce. Właściciel steruje rentownością regułami, nie ręczną edycją cen.

#Realne wdrożenie

Ta sama mechanika stoi za naszym wdrożeniem dla sklepu z częściami motoryzacyjnymi, spiętego bezpośrednio z REST API hurtowni: integracja WooCommerce z API hurtowni. Katalog, stany i ceny utrzymują się tam same, a marża pilnuje rentowności przy zmiennym cenniku dostawcy.

#Z jakimi systemami ERP się integrujemy

Ważne rozróżnienie: integrujemy WooCommerce z API tych systemów, a nie wdrażamy samego ERP. To praca po stronie WordPressa, PHP i warstwy wymiany danych, a nie konsulting ERP.

• Rynek polski: Comarch Optima i XL, Subiekt GT i nexo, enova365, Symfonia. Tu integracja odbywa się zwykle przez dedykowane API lub warstwę pośredniczącą.
• Rynek międzynarodowy: Microsoft Dynamics 365 Business Central, SAP Business One, Oracle NetSuite, Odoo. Systemy chmurowe udostępniają REST API, co upraszcza spięcie ze sklepem.

Jeżeli Twój system nie jest na liście, ale ma jakiekolwiek API albo eksport danych, najczęściej da się go zintegrować.

#Jak projektujemy integracje z konkretnymi systemami ERP

Każdy ERP ma własne API, własny format danych i własne pułapki. Poniżej podejście, jakie stosujemy do najczęstszych systemów. To wzorce architektury, nie gotowa wtyczka za kilkadziesiąt dolarów.

#Comarch ERP Optima (rynek polski)

Optima wystawia dane przez WebService/API, więc budujemy dedykowane middleware (most API) w PHP zamiast synchronizacji przez pliki CSV, która przy każdej aktualizacji stanów obciąża serwer.

• Synchronizacja różnicowa (delta sync): zamiast pobierać całą bazę (np. 15 000 produktów), zadanie CRON odpytuje API Optimy co kilka minut wyłącznie o zmodyfikowane indeksy (produkty, których stan lub cena zmieniły się w ostatnim oknie). Potrafi to ściąć liczbę zapytań do bazy MySQL WordPressa o rząd wielkości.
• Real-time pricing dla B2B: przy logowaniu sklep odpytuje Optimę o grupę rabatową przypisaną do NIP-u i przelicza koszyk w locie, zamiast trzymać tysiące wariacji cen w meta-polach WordPressa.
• Odciążenie bazy: cechy produktów przenosimy z rozdętej tabeli wp_postmeta do dedykowanych tabel niestandardowych (custom tables), co skraca TTFB przy filtrowaniu produktów.

#InsERT Subiekt GT / nexo (rynek polski)

Wymiana danych przez format EPP i API. Zamówienia trafiają z WooCommerce do Subiekta jako ZK (zamówienia od klienta).

• Twarda rezerwacja: po przejściu do kasy (również przy uproszczonym checkoutcie z BLIK-iem) towar jest blokowany w Subiekcie na kilkanaście minut. To zabezpiecza przed oversellingiem w szczytach typu Black Friday.
• Automatyzacja zwrotów: wygenerowanie korekty (ZKOR) w Subiekcie wysyła webhook do WooCommerce, który zmienia status zamówienia na zwrócone, przywraca produkt na stan i wyzwala mail korygujący.

#enova365 (Polska/CEE)

Integrator przez API enova365. Największym wyzwaniem są produkty o wysokiej złożoności wariantów (np. farby: kilkanaście pojemności × 200 kolorów, każdy z własnym EAN), gdzie standardowy importer generuje setki tysięcy postów product_variation.

• Płaskie warianty: zamiast struktury rodzic-dziecko mapujemy cechy (np. Kolor: RAL 9005) do struktury JSON ładowanej asynchronicznie przez REST API do frontendu, co przyspiesza wczytywanie kart produktowych.

#JTL-Wawi (Niemcy) - omnichannel i multi-warehouse

Rynek niemiecki to rygorystyczne RODO i wymagający klient B2B, często z wysyłką z kilku magazynów.

• Logic routing: przy zamówieniu skrypt analizuje kod pocztowy klienta i algorytmicznie przypisuje je do magazynu zapewniającego najszybszą dostawę (fulfillment logic).
• OSS i wielowalutowość: obsługa procedury One Stop Shop z przeliczaniem VAT w locie według kraju wysyłki, tak aby na fakturze w JTL-Wawi trafiła prawidłowa stawka (np. 21% ES zamiast 19% DE).
• Równoległy BaseLinker: WooCommerce spięty jednocześnie z ERP (JTL-Wawi) i z BaseLinkerem do wystawiania na Amazon.de i eBay.

#Holded (Hiszpania) - chmurowy ERP, API-first

Integracja całkowicie bezplikowa, na natywnym REST API Holded, z autoryzacją tokenami i webhookami.

• Kastomizacja fakturowania: skrypt rozpoznaje kwotę koszyka, a webhook przekazuje odpowiednią flagę do Holded, który generuje poprawny dokument (np. Factura Simplificada dla małych kwot) i odsyła PDF do podpięcia pod mail z WooCommerce.

#SAP Business One - skala i walka z tabelą wp_postmeta

Dystrybucja przemysłowa: dziesiątki tysięcy aktywnych produktów, częste aktualizacje cen (nawet kilka razy dziennie przez kursy walut), setki atrybutów. Domyślna struktura WordPressa (EAV) zapisuje każdy atrybut w wp_postmeta, która przy takiej skali puchnie do milionów rekordów, a aktualizacja cen w czasie rzeczywistym powoduje deadlocki na MySQL i błędy 504.

• HPOS i custom tables: rezygnujemy z zapisu atrybutów w wp_postmeta na rzecz dedykowanej, płaskiej tabeli MySQL pod zapytania z SAP B1.
• Elasticsearch jako warstwa wyszukiwania: SAP aktualizuje dane w Elasticu przez API, a front zaciąga wyniki i filtry stamtąd, omijając MySQL. Ta warstwa potrafi ściąć TTFB z sekund do rzędu ~150 ms.
• Kolejkowanie (RabbitMQ): aktualizacje z SAP wpadają do kolejki, a worker zaciąga pakiety po kilkaset produktów w tle, utrzymując płynność sklepu 24/7.

#Odoo (open source) - konfiguratory szyte na miarę

Producenci z konfiguracją w Odoo (BOM, bill of materials), gdzie cena komponentu zależy od innych wyborów. Warianty WooCommerce tego nie obsłużą, a przenoszenie logiki produkcyjnej do PHP kończy się kodem niemożliwym w utrzymaniu.

• Podejście decoupled/headless: WooCommerce pełni rolę koszyka i systemu transakcyjnego (płatność, maile), a frontend (Astro/Vue) komunikuje się bezpośrednio z API Odoo, pytając o wycenę i możliwości produkcyjne w locie. Po dodaniu do koszyka do WooCommerce trafia produkt niestandardowy ze spreparowaną w Odoo ceną i wygenerowanym PDF-em specyfikacji, bez duplikowania logiki biznesowej.

#Microsoft Dynamics 365 (+ BaseLinker i POS)

Duży e-commerce sprzedający przez WooCommerce, Allegro i Amazon (przez BaseLinker) oraz sklepy stacjonarne z POS pod Dynamics 365. Bez ścisłej hierarchii pojawia się efekt pętli synchronizacji i race conditions (ostatnia sztuka kupiona stacjonarnie i sekundę później na Allegro), skutkujący ujemnymi stanami.

• Single Source of Truth: wymuszamy hierarchię, w której Dynamics jest absolutnym masterem, a WooCommerce i BaseLinker są slave’ami.
• Warstwa Redis: aby nie odpytywać w kółko wolnego API Dynamics, wdrażamy Redis w pamięci RAM. Sprzedaż stacjonarna wysyła webhook aktualizujący Redis, a WooCommerce i BaseLinker sprawdzają dostępność w Redisie (czas odpowiedzi rzędu pojedynczych milisekund) przed finalizacją koszyka, eliminując overselling.

#Architektura enterprise: wydajność i niezawodność

Przy dużych bazach ERP odchodzimy od modelu “zainstaluj wtyczkę”. To twarda inżynieria:

• Headless / decoupled: WordPress pełni rolę silnika administracyjnego (backend), a sklep renderujemy w Astro albo Next.js. Frontend uderza przez GraphQL lub REST API, omijając powolne zapytania SQL, co czyni sklep szybszym i odporniejszym na ataki. Szerzej: rozwiązania Enterprise.
• Przetwarzanie asynchroniczne (kolejki): synchronizacja dziesiątek tysięcy produktów w zwykłym skrypcie PHP wygasa przez timeout. Opieramy ją na kolejkach (RabbitMQ lub Redis), które procesują małe pakiety danych (chunks) w tle.
• Obsługa błędów i logowanie: w razie braku odpowiedzi z API ERP blokujemy checkout z komunikatem dla klienta, żeby nie przyjmować zamówień “w próżnię”. Pełne logowanie błędów umożliwia szybką diagnostykę.

#Problemy techniczne, które rozwiązujemy

• API rate limiting (błąd 429): systemy chmurowe mają limity zapytań. Stosujemy exponential backoff (po napotkaniu 429 skrypt czeka i ponawia) oraz chunking, pakując dane w zbiorcze żądania bulk-update JSON zamiast tysięcy pojedynczych wywołań.
• Różnice typowania danych (grosze): ERP potrafi trzymać ceny z czterema miejscami po przecinku, a WooCommerce oczekuje dwóch. W middleware stosujemy ścisłe rzutowanie typów (strict type casting) i wyrównywanie groszy osobno dla każdej pozycji faktury, unikając błędów zaokrągleń narastających na setkach zamówień.
• Obrazy, transfer i limit inode: import fizycznych zdjęć do biblioteki mediów WordPressa (z generowaniem kilku miniatur na obraz) zapycha limit plików na serwerze. Zamiast tego serwujemy obrazy z zewnętrznego zasobu (np. Amazon S3 lub Cloudflare Image Resizing) po zmapowanych z ERP adresach URL, oszczędzając miejsce i przyspieszając samą synchronizację.

#Rozpoznanie przed integracją

Pierwszym rezultatem nie powinien być kod, tylko uzgodniona mapa odpowiedzialności za dane. Wspólnie wskazujemy system nadrzędny dla indeksu produktu, stanu, ceny, podatku, danych klienta i statusu zamówienia. Jeśli dwa systemy mogą swobodnie nadpisywać to samo pole, nawet poprawnie napisane API z czasem stworzy pętlę albo przywróci nieaktualną wartość.

Rozpoznanie obejmuje dokumentację API, sposób autoryzacji, limity zapytań, obsługę webhooków i dostęp do środowiska testowego. Sprawdzamy przykładowe rekordy, a nie tylko opis endpointów. W danych rzeczywistych wychodzą różnice między EAN a indeksem wewnętrznym, puste warianty, różne jednostki miary, stawki VAT zależne od kraju oraz ceny zapisane jako netto w jednym systemie i brutto w drugim.

Na końcu powstaje tabela przepływów: źródło, cel, klucz rekordu, częstotliwość, reguła konfliktu i zachowanie po błędzie. Dzięki niej dział handlowy, magazyn i księgowość mogą zatwierdzić logikę jeszcze przed implementacją. To ważniejsze niż wybór nazwy kolejki czy biblioteki HTTP, bo błąd w odpowiedzialności biznesowej jest znacznie droższy od błędu składni.

#Typowe awarie synchronizacji stanów, cen i zamówień

Stan magazynowy może być technicznie aktualny, ale handlowo błędny. ERP pokazuje ilość fizyczną, podczas gdy sklep powinien publikować ilość dostępną po odjęciu rezerwacji, bufora bezpieczeństwa i zamówień z innych kanałów. Ustalamy, którą wartość wolno sprzedać, co robić przy stanie ujemnym i jak długo sklep może korzystać z ostatniej poprawnej odpowiedzi, gdy ERP nie odpowiada.

Cena może zmienić się w połowie zakupu. Trzeba zdecydować, czy koszyk zachowuje cenę z momentu dodania produktu, czy weryfikuje ją ponownie przed płatnością. Osobno testujemy rabaty B2B, waluty, zaokrąglenia, promocje i podatek. Integracja nie może po cichu nadpisać ceny promocyjnej ceną katalogową ani wysłać do ERP sumy różniącej się od pobranej płatności.

Zamówienie może dotrzeć dwa razy albo nie dotrzeć wcale. Timeout po stronie API nie mówi, czy ERP zapisał rekord przed zerwaniem odpowiedzi. Dlatego operacja potrzebuje klucza idempotencji i bezpiecznego ponowienia, a nie ślepego wywołania drugi raz. Monitorujemy także kolejkę błędów, aby zamówienie wymagające ręcznej decyzji nie zniknęło między logami technicznymi.

#Dowody odbioru przed uruchomieniem

Odbiór opieramy na scenariuszach, które można powtórzyć. Przykładowy zestaw obejmuje nowy produkt, zmianę istniejącego wariantu, wyzerowanie i przywrócenie stanu, zmianę ceny, zamówienie wielopozycyjne, anulowanie, zwrot częściowy oraz ponowienie po przerwie w API. Dla każdego scenariusza zapisujemy dane wejściowe, oczekiwany stan w obu systemach i dowód rezultatu, na przykład identyfikator rekordu albo fragment logu bez danych osobowych.

Testujemy również warunki negatywne: brak wymaganej wartości, nieznany kod podatku, wygasły token, limit 429 i odpowiedź spoza schematu. Integracja jest gotowa nie wtedy, gdy ścieżka poprawna zadziałała raz, lecz gdy zespół wie, jak wykryć, ponowić albo skierować do ręcznej obsługi ścieżkę błędną. Lista scenariuszy staje się protokołem odbioru, więc zakres nie zależy od wrażenia po demonstracji.

#Przekazanie operacyjne

Po wdrożeniu przekazujemy opis źródeł prawdy, harmonogramów, alertów, lokalizacji logów i procedury ponowienia. Właściciel procesu powinien wiedzieć, kto reaguje na brak synchronizacji, kto zatwierdza zmianę mapowania i kiedy należy wstrzymać checkout zamiast sprzedawać na niepewnym stanie. Dostępy techniczne trzymamy poza dokumentacją, w uzgodnionym magazynie sekretów.

Ustalamy też zasady zmian. Nowe pole w ERP, aktualizacja wtyczki WooCommerce lub przebudowa statusów zamówień może zmienić kontrakt integracji, nawet jeśli endpoint pozostaje ten sam. Krótka checklista regresji i środowisko testowe ograniczają ryzyko, że pozornie mała zmiana administracyjna zatrzyma przepływ zamówień w produkcji.

#Co wpisać w briefie

Wyślij założenia w wiadomości email: nazwę i wersję ERP, link do dokumentacji API, liczbę aktywnych produktów i wariantów, kanały sprzedaży, oczekiwaną częstotliwość aktualizacji oraz listę danych płynących w każdą stronę. Dodaj przykładowy produkt, zamówienie i cennik po usunięciu danych osobowych. Napisz też, który system jest dziś źródłem prawdy i jakie błędy operacyjne integracja ma wyeliminować.

Na tej podstawie możemy odpowiedzieć zakresem rozpoznania, ryzykami i propozycją etapów bez zgadywania. Jeśli dokumentacji API jeszcze nie ma, napisz to wprost i wskaż osobę lub firmę utrzymującą ERP. Pisemny brief pozwala sprawdzić najważniejsze zależności przed wyceną i nie wymaga spotkania na start.

#Kiedy warto pomyśleć o integracji

• Aktualizujesz stany i ceny ręcznie albo importem plików, i to się nie skaluje.
• Zdarzają Ci się zamówienia na produkty, których dostawca nie ma na stanie.
• Ceny w sklepie rozjeżdżają się z cennikiem hurtowni albo ERP.
• Zamówienia trzeba ręcznie przepisywać do systemu księgowego czy magazynowego.

Ostatnia weryfikacja: 2026-07-04. Zakres integracji ERP, mapowanie pól i przykłady systemów zgodne z wdrożeniami w UE.