WooCommerce API: jak połączyć sklep z innymi systemami

REST API udostępnia dane WooCommerce przez endpointy, czyli adresy dla określonych zasobów, takich jak produkty i zamówienia. System zewnętrzny wysyła żądanie HTTP, a sklep odpowiada między innymi danymi JSON. Interfejs administracyjny służy człowiekowi do zarządzania sklepem, natomiast API pozwala automatyzować wymianę danych między aplikacjami.

Webhook działa w odwrotnym rytmie: po zdarzeniu, na przykład zmianie zamówienia, WooCommerce wysyła powiadomienie na skonfigurowany adres. Dzięki temu odbiorca nie musi stale pytać sklepu, czy coś się zmieniło. API i webhook często uzupełniają się: webhook informuje o zdarzeniu, a API pozwala pobrać aktualny stan zasobu.

Gotowa wtyczka sprawdzi się, gdy obsługuje wymagane pola, kierunek synchronizacji i scenariusze błędów bez dopisywania kodu. Własne połączenie API wybieramy, gdy trzeba dostosować mapowanie, łączyć kilka systemów albo obsłużyć reguły firmy. Porównanie platform pod kątem integracji opisujemy w artykule WooCommerce vs Shopify: koszty, obsługa i integracje.

Przygotowanie zaczynamy od kopii zapasowej i środowiska testowego, które odzwierciedla wersje WordPressa, WooCommerce oraz istotnych wtyczek. Testy na kopii ograniczają ryzyko zmiany prawdziwych zamówień lub stanów. Zanim wykonawca otrzyma dostęp, warto zapisać, jakie dane będą odczytywane i zmieniane.

WooCommerce wymaga czytelnych bezpośrednich odnośników. W panelu WordPress przejdź do Ustawienia > Bezpośrednie odnośniki i wybierz strukturę inną niż Zwykłe. Komunikacja powinna odbywać się przez HTTPS. Dokumentacja WooCommerce wskazuje też, że obecna integracja REST API korzysta z WordPress REST API; stara REST API wymaga osobnej wtyczki Legacy REST API, jeśli nadal zależy od niej używane połączenie.

Przypisanie źródła prawdy zapobiega pętli, w której sklep nadpisuje ERP, a ERP po chwili przywraca poprzednią wartość. Dla każdego pola określ system nadrzędny, częstotliwość aktualizacji, identyfikator łączący rekordy i sposób rozstrzygania konfliktu. Więcej przykładów zebraliśmy w konfiguracji integracji WooCommerce krok po kroku.

Klucz API jest powiązany z kontem użytkownika WordPress, dlatego wygeneruj go dla dedykowanego użytkownika technicznego. Zaloguj się jako administrator i przejdź do WooCommerce > Ustawienia > Zaawansowane > REST API. Wybierz Dodaj klucz, podaj opis pozwalający rozpoznać integrację, przypisz użytkownika i ustaw potrzebny poziom uprawnień.

Po wygenerowaniu WooCommerce pokazuje Consumer Key i Consumer Secret. Dokumentacja podaje, że Consumer Secret jest widoczny tylko raz, więc skopiuj go od razu do menedżera sekretów lub bezpiecznego magazynu poświadczeń integratora. Nie umieszczaj klucza w publicznym repozytorium, kodzie frontendu ani zgłoszeniu dostępnym dla osób postronnych. Jeśli podejrzewasz ujawnienie sekretu, unieważnij klucz i wygeneruj nowy.

Nadaj wyłącznie uprawnienia wymagane przez uzgodniony zakres. Odczyt katalogu nie uzasadnia dostępu do zapisu, a integracja aktualizująca stany może wymagać zapisu, ale niekoniecznie zarządzania wszystkimi danymi. Gdy dane logowania zostaną przekazane wykonawcy, użyj uzgodnionego bezpiecznego kanału i nie wysyłaj ich w zwykłym, publicznym zgłoszeniu.

Pierwszy test wykonaj na środowisku testowym, używając operacji GET do pobrania danych, zanim dopuścisz zmiany. Przykładowy endpoint katalogu produktów to `https://twoj-sklep.pl/wp-json/wc/v3/products?per_page=5`. W kliencie HTTP, takim jak Postman, ustaw metodę GET, uwierzytelnianie zgodne z dokumentacją WooCommerce i sprawdź kod odpowiedzi, treść JSON oraz czas wykonania.

Dokumentacja WooCommerce wymienia 400, 401, 404 i 500 jako typowe rodzaje błędów API. Kod 429 może pochodzić z konfiguracji hostingu, zapory lub warstwy pośredniej, dlatego sprawdź nagłówki odpowiedzi i logi serwera zamiast zakładać, że limit pochodzi z samego WooCommerce. JSON powinien zawierać między innymi kod błędu, komunikat i dane statusu.

Przy większym katalogu pamiętaj o stronicowaniu. Wyniki są dzielone na strony, a odpowiedź zawiera nagłówki `X-WP-Total`, `X-WP-TotalPages` i `Link`; podążaj za adresem kolejnej strony zamiast zakładać, że pierwsza odpowiedź zawiera wszystkie rekordy. Zanotuj czas odpowiedzi, endpoint, metodę i identyfikator testowego zasobu. Nie zapisuj w logu sekretu ani pełnych danych klienta.

Najpierw projektujemy mapę pól i kierunek przepływu, a dopiero potem konfigurujemy synchronizację. SKU produktu może być wspólnym identyfikatorem między systemami, ale trzeba zweryfikować jego unikalność i zachowanie wariantów. Jeśli zewnętrzny system ma własny identyfikator, przechowuj mapowanie ID sklepu do ID systemu zewnętrznego, zamiast dopasowywać rekordy po nazwie.

Dla produktów określ, gdzie edytuje się tytuł, cenę, SKU, warianty i stan. Dla zamówień ustal, czy sklep wysyła je do ERP, czy ERP może zmieniać status, numer dokumentu i informację o wysyłce. Przy ustalaniu synchronizacji stanów testuj osobno produkt prosty, wariantowy, wycofany i brak towaru.

Perspektywa KC Mobile: w integracjach problemy często zaczynają się od nieuzgodnionej odpowiedzialności za dane, a nie od samego endpointu. Dlatego podczas odbioru sprawdzamy nie tylko, czy rekord dotarł, ale też czy system docelowy potrafi rozpoznać go przy kolejnej aktualizacji i nie tworzy duplikatu. Jeśli łączysz sklep z enova365, sprawdź zakres integracji enova365 z WooCommerce; przy połączeniu z Subiektem opisujemy integrację Subiekt z WooCommerce.

Webhook wybierz, gdy system docelowy ma szybko dostać informację o zdarzeniu, takim jak utworzenie lub aktualizacja zamówienia, produktu albo klienta. Skonfigurujesz go w WooCommerce > Ustawienia > Zaawansowane > Webhooki. W formularzu wybierz aktywny status, temat, docelowy adres URL i tajny klucz.

Odbiorca powinien weryfikować nagłówek `X-WC-Webhook-Signature`, który WooCommerce tworzy z treści żądania i sekretu. Poprawna weryfikacja potwierdza, że payload nie został zmieniony i pochodzi od nadawcy znającego sekret. Endpoint odbiorczy musi obsłużyć żądanie szybko i zwrócić poprawny status, a cięższe przetwarzanie może przekazać do kolejki.

Webhook nie zastępuje kontroli stanu. WooCommerce wyłącza webhook po więcej niż pięciu kolejnych nieudanych dostarczeniach; za niepowodzenie uznaje odpowiedź inną niż 2xx, 301 lub 302. Odbiorca powinien logować identyfikator dostarczenia, bezpiecznie ponawiać przetwarzanie i ignorować ponownie dostarczone zdarzenie, jeśli już je obsłużył. Okresowa synchronizacja kontrolna pozwala wykryć rekord, którego webhook nie dostarczył.

Diagnozę prowadź od połączenia i adresu do danych, aby nie zmieniać kilku ustawień naraz. Zapisz datę, endpoint, metodę HTTP, kod odpowiedzi, czas wykonania i identyfikator testowego zasobu. Następnie powtórz żądanie na środowisku testowym z tym samym zakresem uprawnień.

Jeżeli API zwraca błąd po aktualizacji, sprawdź logi WooCommerce w WooCommerce > Status > Logi oraz log błędów PHP hostingu. Przetestuj, czy reguła zapory, ModSecurity albo wtyczka bezpieczeństwa nie blokuje metody lub żądania. W przypadku rozbieżności porównaj identyfikatory zewnętrzne, SKU, wariant i znacznik czasu; nie poprawiaj ręcznie obu systemów, dopóki nie ustalisz, który ma prawo nadpisywać pole.

Sekrety przechowuj po stronie serwera lub w menedżerze sekretów, a nie w skryptach przeglądarki, repozytorium czy logach. Ogranicz dostęp do konta technicznego, ewidencjonuj właściciela klucza i ustal proces jego rotacji. Po zmianie sekretu przetestuj połączenie odczytu oraz każdą operację zapisu.

Monitoring powinien rozróżniać błąd chwilowy od błędu danych. Rejestruj czas, endpoint, kod HTTP, ID rekordu i liczbę ponowień, bez haseł, tokenów oraz zbędnych danych klienta. Alarm ustaw dla serii nieudanych żądań, wyłączonego webhooka i narastającej kolejki synchronizacji.

Po aktualizacji WooCommerce, WordPressa, wtyczki integracyjnej lub PHP wykonaj testy regresji: pobranie produktu, zmianę testowego stanu, odbiór zamówienia i ponowienie zdarzenia. Szczegóły wymagań oraz koszt wdrożenia opisujemy na stronie migracje i integracje WooCommerce. W szerszym kontekście rozwoju sklepu przyda się też poradnik WooCommerce dla sklepów online oraz materiał o architekturze headless WooCommerce.

• PrestaShop API: jak skonfigurować dostęp i bezpiecznie zintegrować sklep
• Magento API w praktyce: endpointy, integracje i bezpieczeństwo
• Automatyzacje WooCommerce: które procesy usprawnić i jak je wdrożyć
• Jak przenieść produkty między platformami e-commerce bez utraty danych
• imoje w WooCommerce: jak skonfigurować i przetestować płatności