W sklepie internetowym integracje rzadko kończą się na imporcie produktów. Szybko dochodzą zamówienia, stany magazynowe, faktury, statusy płatności i synchronizacja z ERP, więc ręczna obsługa przestaje mieć sens. REST API WooCommerce daje techniczny dostęp do danych sklepu, ale dobrze działa dopiero wtedy, gdy od początku ustalisz, co ma być źródłem prawdy, jakie zasoby będą synchronizowane i jak zabezpieczysz połączenie.
Najważniejsze rzeczy, które warto wiedzieć przed integracją
-
Aktualna wersja to v3, a nowe integracje warto budować na endpointach z prefiksem
/wp-json/wc/v3/. - Dostęp zwykle opiera się o Consumer Key i Consumer Secret, generowane dla konkretnego użytkownika i konkretnego zakresu uprawnień.
- Bezpieczne połączenie realizuje się przez HTTPS i Basic Auth, a przy problemach z nagłówkiem Authorization czasem stosuje się awaryjnie parametry query string.
- Store API to osobna warstwa do koszyka, checkoutu i frontu sklepu, bez dostępu do wrażliwych danych administracyjnych.
- Najczęściej używane zasoby to produkty, zamówienia, klienci, kupony, zwroty i notatki do zamówień.
Czym jest REST API WooCommerce i po co je wdrażać
Najprościej mówiąc, to warstwa, która pozwala innym systemom rozmawiać ze sklepem bez klikania w panel administracyjny. W praktyce traktuję ją jako most między WooCommerce a resztą firmy: ERP, magazynem, CRM, narzędziem do fakturowania, marketplace'em albo własną aplikacją. Dzięki temu można automatycznie pobierać dane o produktach, aktualizować ceny i stany, zapisywać zamówienia, zmieniać statusy i budować procesy, które nie opierają się na ręcznej pracy zespołu.
To szczególnie ważne w sklepach, które rosną szybciej niż ich zaplecze operacyjne. Jeśli katalog liczy kilkaset lub kilka tysięcy produktów, a zamówienia spływają z kilku kanałów, ręczne przenoszenie informacji zwykle kończy się błędami. Ja zawsze zaczynam od pytania, który system ma być źródłem prawdy dla cen, stanów i zamówień, bo bez tego integracja szybko zamienia się w dwie sprzeczne wersje tej samej informacji.
Dokumentacja WooCommerce wskazuje, że v3 jest obecnie zalecaną wersją dla nowych integracji. To dobry punkt startu, bo pozwala od razu pracować na aktualnym modelu zasobów i uniknąć budowania czegoś na starszym wariancie, który później trzeba będzie przepisywać.
Jak działa autoryzacja i co ustawić od razu
W przypadku WooCommerce najczęściej używa się pary kluczy: Consumer Key i Consumer Secret. Generuje się je w panelu administracyjnym, dla konkretnego użytkownika i z określonym zakresem dostępu, najczęściej tylko do odczytu albo do odczytu i zapisu. To ważne, bo integracja nie powinna mieć większych uprawnień niż potrzebuje. Jeśli synchronizujesz tylko zamówienia, nie ma sensu dawać jej pełnej kontroli nad wszystkim.
Najbezpieczniej od razu założyć osobnego użytkownika integracyjnego i nie podpinać do niego zwykłego konta administratora. Klucze są widoczne tylko w momencie tworzenia, więc trzeba je od razu skopiować i bezpiecznie zapisać po stronie serwera. Jeśli użytkownik, do którego przypisano klucz, zostanie usunięty, dostęp przestaje działać. To drobiazg, który potrafi zatrzymać integrację w najmniej wygodnym momencie.
curl -u consumer_key:consumer_secret https://twoj-sklep.pl/wp-json/wc/v3/ordersPrzy połączeniu przez HTTPS wystarcza zwykle Basic Auth, czyli nazwa użytkownika i hasło przekazane w nagłówku Authorization. Jeśli serwer źle obsługuje ten nagłówek i pojawia się błąd w stylu „Consumer key is missing”, dokumentacja WooCommerce dopuszcza awaryjne przekazanie kluczy w query string. Traktuję to jednak jako obejście, a nie domyślną praktykę, bo bezpieczniej i czyściej jest naprawić konfigurację serwera.
Przy połączeniach przez HTTP trzeba przejść na OAuth 1.0a, bo inaczej klucze mogą zostać przechwycone. Zwracam też uwagę na ograniczenie czasowe, ponieważ timestamp w żądaniu jest akceptowany tylko w oknie około 15 minut. Jeśli budujesz własną aplikację, WooCommerce udostępnia też endpoint autoryzacyjny /wc-auth/v1/authorize, który ułatwia użytkownikowi nadanie dostępu bez ręcznego przepisywania kluczy. Jeśli pracujesz również z innymi endpointami WordPressa, pomocne bywają Application Passwords, ale do samego sklepu najczęściej wystarczają klucze WooCommerce.
Jakie zasoby i operacje obsłużysz najczęściej
W praktyce nie zaczynam od wszystkiego naraz. Największą wartość dają zwykle trzy obszary: produkty, zamówienia i klienci. Dopiero później dochodzą kupony, zwroty, notatki do zamówień, kategorie czy atrybuty. Taki porządek pozwala szybko dowieźć działającą integrację i nie rozbudować projektu o funkcje, które jeszcze nie są potrzebne.
| Zasób | Co możesz zrobić | Kiedy ma to największy sens |
|---|---|---|
| Produkty | Tworzyć, aktualizować, usuwać, zmieniać ceny, stany i warianty | Synchronizacja katalogu z ERP, PIM albo hurtownią |
| Zamówienia | Odczytywać, aktualizować statusy, dodawać notatki i obsługiwać zwroty | Automatyzacja obsługi, fulfillment, księgowość |
| Klienci | Tworzyć i aktualizować dane klientów | CRM, segmentacja, synchronizacja kont |
| Kupony | Dodawać i modyfikować rabaty | Kampanie promocyjne i automatyzacje marketingowe |
| Warianty, kategorie, tagi, atrybuty | Porządkować katalog i strukturę produktów | Import dużych kart produktowych i merchandising |
| Zwroty i notatki do zamówień | Obsługiwać wyjątki i historię operacji | Obsługa klienta i kontrola procesu |
W WooCommerce API indeks zasobów można podejrzeć bez logowania, ale już konkretne operacje wymagają autoryzacji. To dobry podział, bo pozwala najpierw sprawdzić strukturę dostępnych endpointów, a dopiero potem przejść do rzeczywistych operacji na danych sklepu.
Jak wdrożyć pierwszą integrację krok po kroku
Ja zwykle zaczynam od bardzo wąskiego zakresu. Najpierw ustalam, czy integracja ma tylko odczytywać dane, czy też je zmieniać. Potem wybieram jeden prosty scenariusz testowy, na przykład pobranie listy zamówień albo jednej grupy produktów. Dopiero po przejściu takiego testu rozbudowuję połączenie o zapisy, aktualizacje i obsługę błędów.
- Określ zakres synchronizacji. Zdecyduj, które dane mają się przenosić i który system jest źródłem prawdy dla cen, stanów, statusów i danych klienta.
- Utwórz osobne konto integracyjne. Daj mu tylko te uprawnienia, które są potrzebne do działania, najlepiej read albo read/write w ograniczonym zakresie.
- Wygeneruj klucze i zapisz je poza kodem. Sekretu nie trzymaj w repozytorium ani we frontendowym JavaScriptcie, tylko w bezpiecznym magazynie po stronie serwera.
-
Przetestuj pierwszy odczyt. Zacznij od żądania typu
GET /wp-json/wc/v3/ordersalboGET /wp-json/wc/v3/productsi sprawdź, czy odpowiedź jest kompletna. - Dodaj paginację. Przy większych sklepach nie zakładaj, że jeden request wystarczy. Stronicowanie jest konieczne, jeśli nie chcesz gubić danych.
- Dopiero potem uruchom zapisy. Aktualizacja produktu albo statusu zamówienia powinna wejść po etapie testów, a nie na samym początku.
- Włącz logowanie i obsługę błędów. Bez tego trudno odróżnić błąd sieci od problemu z uprawnieniami, limitem lub niepoprawnym formatem danych.
W przypadku sklepów, które mają reagować na zdarzenia niemal natychmiast, warto rozważyć webhooks jako uzupełnienie odpytywania API. To nie jest zastępstwo całej integracji, ale bardzo praktyczny sposób, żeby nie sprawdzać co minutę, czy status zamówienia już się zmienił.
Kiedy wybrać REST API, a kiedy Store API
To rozróżnienie naprawdę robi różnicę. Najczęstszy błąd, jaki widzę, to próba użycia jednej warstwy do wszystkiego. Tymczasem REST API WooCommerce i Store API służą do trochę innych zadań. Pierwsze jest narzędziem administracyjnym i integracyjnym, drugie obsługuje sklep od strony klienta, głównie koszyk, checkout i publiczne elementy produktu.
| Aspekt | REST API WooCommerce | Store API |
|---|---|---|
| Dostęp | Autoryzowany, oparty o klucze API | Publiczny, bez kluczy API |
| Zakres danych | Produkty, zamówienia, klienci, kupony, zwroty, notatki | Koszyk, checkout, produkty widoczne dla klienta |
| Wrażliwe informacje | Tak, dlatego dostęp musi być kontrolowany | Nie daje dostępu do danych innych klientów ani poufnych informacji sklepu |
| Najlepsze zastosowanie | ERP, CRM, PIM, fulfillment, automatyzacja back-office | Frontend sklepu, koszyk, interfejs zakupowy |
| Ważne ograniczenie | Wymaga prawidłowej autoryzacji i bezpiecznego przechowywania sekretów | Nie służy do zarządzania ustawieniami sklepu ani do pobierania cudzych zamówień |
Jeśli budujesz synchronizację stanów, obsługę zamówień albo integrację z systemem magazynowym, wybieram REST API. Jeśli chcesz tylko zasilić koszyk, checkout lub widok produktów po stronie klienta, lepszy będzie Store API. To proste rozróżnienie oszczędza sporo czasu i usuwa wiele błędów projektowych już na starcie.
Co sprawdzić, żeby integracja nie rozpadła się po aktualizacji wtyczek
Stabilność integracji rzadko zależy od jednego wielkiego elementu. Zwykle wygrywają drobiazgi: osobne konto, minimalne uprawnienia, sensowny sposób logowania błędów i przewidziane scenariusze awaryjne. Jeśli mam wskazać kilka rzeczy, które realnie chronią projekt, to wyglądają one tak:
- używaj osobnego użytkownika integracyjnego, a nie konta administratora;
- nadaj tylko tyle uprawnień, ile naprawdę potrzebujesz;
- przechowuj sekret po stronie serwera, nie w kodzie frontendu;
- zadbaj o HTTPS na produkcji, bez wyjątków;
- loguj odpowiedzi API i błędy autoryzacji, szczególnie na początku wdrożenia;
- planuj idempotencję, czyli odporność na ponowne wysłanie tego samego żądania bez tworzenia duplikatów;
- przy większych katalogach i zamówieniach stosuj paginację oraz synchronizację przyrostową;
- jeśli serwer zwraca problem z nagłówkiem Authorization, napraw konfigurację, zanim pójdziesz w obejścia;
- zarezerwuj staging do testów, bo pierwsze wdrożenie bez środowiska testowego prawie zawsze kończy się chaosem;
- rozważ webhooki tam, gdzie potrzebujesz reakcji na zdarzenie, a nie okresowego odpytywania.
Jeśli miałbym zostawić jedną praktyczną radę, to taką: traktuj integrację jak osobny produkt, a nie jednorazowy skrypt. Wtedy REST API WooCommerce staje się stabilnym łącznikiem między sklepem a resztą systemów, a nie kolejnym miejscem, które trzeba ręcznie ratować po aktualizacji wtyczek.
