Programista Next.js we Wrocławiu

Programista Next.js dla firm z Wrocławia. Headless WooCommerce przez Store API: koszyk, nonce i Cart-Token, checkout, płatności, i kiedy lepszy jest klasyczny motyw. Pracuję zdalnie, umowa B2B.

Programista Next.js

Moje miejsce w społeczności WordPress

  • Konto na wordpress.org mam od 2006 roku.
  • Współtworzyłem rdzeń WordPressa w wersjach 7.0 i 7.1.
  • Utrzymuję 30 wtyczek na wordpress.org.
  • Organizuję WordCampy i występuję na nich jako prelegent.
  • Byłem na każdym WordCamp Europe od 2017 do 2026 roku.
  • Lokalne spotkania WordPressa: WordPress Wrocław

Mój profil na WordPress.org

#Sklep na WooCommerce, front w Next.js: co daje Store API

Firmy z Wrocławia, które mają sklep na WooCommerce i myślą o nowym froncie w Next.js, pytają o jedno: czy da się zostawić WooCommerce jako zaplecze, a koszyk i zamówienie obsłużyć z własnej aplikacji. Da się, a punktem wejścia jest Store API.

Według dokumentacji to publiczne endpointy REST do budowy koszyka, checkoutu i listy produktów po stronie klienta sklepu. Leżą w przestrzeni wc/store/v1, na przykład GET /wp-json/wc/store/v1/products i GET /wp-json/wc/store/v1/cart. API jest nieuwierzytelnione i nie wymaga kluczy, a zwracane dane dotyczą bieżącego klienta. Sesje klientów są oparte na ciasteczkach. Przez Store API nie wyszukasz cudzych zamówień po ID ani nie zmienisz ustawień sklepu, do tego służy osobne, uwierzytelnione REST API WooCommerce.

Dla frontu to dobra wiadomość z jednego powodu: nic, co wystawia Store API, nie ujawnia danych sklepu, których klient nie widziałby i tak. Dokumentacja dodaje, że API nie zakłada, gdzie treść zostanie wyświetlona, więc nie zwraca gotowego HTML-a, chyba że sam typ danych jest HTML-em. Wygląd, układ i makiety przychodzą od ciebie, ja wdrażam je w komponenty.

#Koszyk i sesja: nonce albo Cart-Token

Najwięcej błędów przy pierwszym podejściu bierze się z tego, że żądania zapisujące dane odrzuca serwer, zanim cokolwiek się wydarzy. Dokumentacja nonce mówi, że wymagają go żądania POST do endpointów /cart i wszystkie żądania do /checkout. Nonce wysyła się w nagłówku Nonce, a po udanym żądaniu odpowiedź zwraca zaktualizowany nagłówek, który front musi zapisać i użyć przy następnym wywołaniu. Tworzy się go w WordPressie funkcją wp_create_nonce z kluczem wc_store_api, innego sposobu nie ma.

Dla frontu headless jest druga droga: Cart-Token. Może zastąpić sesję opartą na ciasteczkach, a przy jego użyciu nonce nie jest potrzebny. Token zwracają udane odpowiedzi z endpointów /cart w nagłówku Cart-Token, a wysyła się go w nagłówku kolejnych żądań do koszyka i checkoutu. Najprościej zobaczyć go po GET /wp-json/wc/store/v1/cart.

Dokumentacja nie mówi, gdzie front ma token przechowywać. Mój wybór, nie wymóg: route handler w Next.js wywołuje WooCommerce po stronie serwera i zapisuje token w ciasteczku z flagami httpOnly, secure i sameSite, które cookies().set obsługuje w route handlerach i Server Actions. Skrypt w przeglądarce nie widzi wtedy tokena, a przeglądarka nie musi rozmawiać z WordPressem bezpośrednio.

Operacje na koszyku są wygodne: add-item przyjmuje id produktu i quantity, a w odpowiedzi zwraca cały koszyk, nie tylko dodaną pozycję. Dokumentacja podaje to jako świadome uproszczenie, żeby klient nie robił kilku zapytań. Dla wariantów atrybut globalny przekazujesz jako slug z prefiksem pa_, na przykład pa_color, a atrybuty produktu jako nazwę z uwzględnieniem wielkości liter.

#Checkout: tu headless sprawia najwięcej pracy

Endpoint checkout tworzy zamówienie z bieżącego koszyka. GET zwraca szkic zamówienia ze statusem checkout-draft i adresami klienta. PUT zapisuje pola checkoutu, wybraną metodę płatności i uwagi do zamówienia. POST przyjmuje adres rozliczeniowy, adres wysyłki i payment_method, próbuje zrealizować płatność i zwraca wynik. W payment_result jest redirect_url, czyli adres, na który front kieruje klienta po płatności.

Z dokumentacji wynikają trzy rzeczy, które planuję przed pierwszą linijką kodu.

  • Bramka płatności wchodzi z własnymi danymi. Pole payment_data zależy od bramki. Dokumentacja pisze wprost, że nie wylicza danych dla wszystkich bramek, i odsyła do autorów wtyczek bramek. W przykładzie ze Stripe front przekazuje tam parę klucz i wartość, na przykład stripe_source. Zanim zgodzę się na headless, sprawdzam więc, czy twoja bramka (BLIK, przelewy, karty, raty) obsługuje płatność przez Store API.
  • Suma kontrolna chroni przed zmianą ceny. Parametr expected_total to kwota w najmniejszej jednostce waluty, którą klient potwierdził. Jeśli suma policzona na serwerze jest inna, zamówienie jest odrzucane kodem 409 (woocommerce_rest_checkout_total_mismatch), a front dostaje odświeżony koszyk do pokazania. Pomija się go tylko tam, gdzie końcowej sumy nie da się znać z góry, na przykład przy niektórych płatnościach ekspresowych.
  • Zamówienie można dokończyć osobno. Dla istniejącego zamówienia jest endpoint POST /checkout/{id}, który wymaga klucza zamówienia, a dla gości adresu e-mail.

Dochodzi limit żądań. Według dokumentacji limitowanie jest opcjonalne i domyślnie wyłączone. Po włączeniu domyślny próg to 25 żądań w 10 sekund, liczonych tylko dla POST, a limit zamówienia włączony w ustawieniach WooCommerce to 3 żądania na 60 sekund. Nieuwierzytelnione żądania są grupowane po adresie IP, a obsługa serwerów pośredniczących ma osobny przełącznik, też domyślnie wyłączony. Z tego wynika sprawdzenie, które robię przy każdym froncie wołającym WordPress z serwera: jeśli wszystkie żądania klientów przychodzą z jednego adresu serwera Next.js, limit może policzyć je jako jednego użytkownika. To moje wnioskowanie z opisu, nie zapis w dokumentacji, więc testuję je na środowisku testowym.

#Katalog produktów

Lista produktów jest najłatwiejszą częścią. Endpoint products obsługuje wyszukiwanie, filtry po kategorii, marce, atrybutach, cenie i statusie magazynowym oraz sortowanie, a stronicowanie zwraca w nagłówkach X-WP-Total i X-WP-TotalPages. Na stronę można pobrać najwyżej 100 pozycji. To wystarcza na kartę produktu i listę kategorii, ale oznacza, że filtry zaawansowane i wyszukiwarkę z dużym katalogiem trzeba osobno zaplanować.

#Kiedy klasyczny motyw WooCommerce jest lepszym wyborem

Headless dokłada drugi system do wdrażania i pilnowania. Za tę cenę dostajesz pełną kontrolę nad frontem, ale nie dostajesz nic za darmo w koszyku i zamówieniu. Dlatego w wielu sklepach radzę zostać przy WordPressie.

SytuacjaMoja rekomendacja
Standardowy proces zakupu, kilka wtyczek bramek i wysyłekKlasyczny motyw lub bloki WooCommerce, popraw to, co boli
Wtyczki dokładają pola i elementy do koszyka i checkoutuZostaje klasyczny motyw, chyba że wtyczki mają obsługę Store API
Wolny sklep, a przyczyną są wtyczki i obrazyNajpierw audyt i poprawki w istniejącym motywie
Jeden katalog i kilka frontów (sklep, aplikacja, portal B2B)Headless ma sens, Store API obsłuży każdy z nich
Potrzebujesz własnej aplikacji w Reakcie z autorskim procesem zakupuHeadless, z zaplanowanym budżetem na checkout i płatności

Rozszerzenia to osobny powód. Dokumentacja opisuje, że Store API pozwala rozszerzać wybrane trasy i schematy przez klasę ExtendSchema, co jest podejściem bardziej ograniczającym niż klasyczne haki, bo zmniejsza ryzyko, że rozszerzenie zepsuje odpowiedź. Z tego wynika praktyczny skutek: wtyczka, która dziś dokłada coś do koszyka przez hak szablonu, w froncie headless nie pojawi się sama. Trzeba ją zbadać pojedynczo.

Most Tumski we Wrocławiu

Zdjęcie: Diego Delso, CC BY-SA 4.0, Wikimedia Commons.

#Lokalnie: rozmowa o sklepie zaczyna się od rynku

Miasto opisuje na stronie Przedsiębiorczy Wrocław strategię rozwoju przedsiębiorczości do 2030 roku, wynikającą ze Strategii Wrocław 2030 przyjętej uchwałą Rady Miejskiej 15 lutego 2018 roku. Jej założeniem jest inteligentne miasto o gospodarce opartej na wiedzy. W dziale dla przedsiębiorców jest też podstrona o wsparciu eksportu, na pomoc przy organizacji przedsięwzięć promocyjnych. Jeśli planujesz sklep na rynki zagraniczne, zajrzyj tam, zanim ustalisz zakres frontu.

#Jak wygląda praca ze mną

Mieszkam w Gdyni, a projekty prowadzę wyłącznie zdalnie i pisemnie. Dostajesz brief, pytania, zakres i założenia na piśmie, wdrożenie na środowisku testowym, odbiór i opcjonalną opiekę po uruchomieniu. Projekt graficzny, makiety i układ elementów dostarczasz ty albo twój projektant, ja je implementuję.

Do startu potrzebuję:

  • adresu sklepu i dostępu do środowiska testowego z kopią danych,
  • listy wtyczek, bramek płatności i wysyłek,
  • opisu, co dziś boli: szybkość, wygląd, proces zakupu czy integracje,
  • projektów widoków albo arkusza z rozmieszczeniem elementów.

#Lista kontrolna przed decyzją o headless

PytanieDlaczego
Czy bramka płatności obsługuje płatność przez Store API?payment_data zależy od bramki
Które wtyczki dokładają coś do koszyka i checkoutu?Mogą nie działać w froncie headless
Gdzie trzymasz Cart-Token i jak front go odświeża?Bez tego koszyk ginie po odświeżeniu
Czy limit żądań widzi prawdziwy adres klienta?Jeden adres serwera może zablokować wszystkich
Kto utrzymuje WordPress i front po starcie?Dwa systemy to dwa cykle aktualizacji

#Powiązane strony

#Pytania i odpowiedzi

#Czy Store API wymaga kluczy API?

Nie. Store API jest nieuwierzytelnione i zwraca tylko dane bieżącego klienta, więc klucze nie są potrzebne. Do pełnego dostępu do zamówień, klientów i ustawień służy osobne, uwierzytelnione REST API WooCommerce, i nie powinno trafić do przeglądarki.

#Nonce czy Cart-Token?

Do frontu headless wybieram Cart-Token, bo działa zamiast sesji opartej na ciasteczkach i wtedy nonce nie jest wymagany. Nonce ma sens, gdy front stoi w tej samej domenie co WordPress i korzysta z jego sesji.

#Czy każda bramka płatności zadziała z frontem w Next.js?

Nie ma takiej gwarancji. Każda bramka oczekuje własnych danych w polu payment_data, a dokumentacja WooCommerce odsyła do autorów wtyczek bramek. Przed decyzją o headless sprawdzam więc, czy twoja bramka obsługuje płatność przez Store API.

#Dlaczego zamówienie zwróciło błąd 409?

Jeśli front wysłał parametr expected_total, a suma policzona na serwerze jest inna, checkout odrzuca zamówienie kodem 409 i zwraca odświeżony koszyk. Front pokazuje wtedy klientowi nową kwotę do potwierdzenia.

#Kiedy lepiej zostać przy klasycznym motywie WooCommerce?

Gdy sklep ma standardowy proces zakupu, kilka wtyczek rozszerzających koszyk i nikt nie zgłasza problemu z samym frontem. Headless dokłada drugi system do utrzymania, a wtyczki dodające elementy do koszyka muszą być do niego dopasowane. Wtedy poprawa motywu daje więcej niż nowy front.

#Jak zaczyna się współpraca?

Piszesz do mnie, jaki sklep masz, jakich wtyczek i bramek używa i co chcesz zmienić na froncie. Odpisuję w dni robocze: dopytuję o szczegóły i przedstawiam wstępną wycenę. Pierwsza pisemna wycena jest bezpłatna.

#Napisz do mnie

Wyślij mi adres sklepu, to, co chcesz zmienić na froncie, termin i listę wtyczek oraz bramek płatności. Odpowiem pisemnie z pytaniami i propozycją pierwszych kroków. Pierwsza wstępna wycena jest bezpłatna. Napisz przez formularz kontaktowy, resztę ustalimy w pytaniach pisemnych.

Zobacz też w innych miastach Polski

Najbliższe wydarzenia WordPress

Spotkaj się z nami na WordCampie

Dołącz do społeczności WordPress we Wrocławiu. Regularnie bywam na meetupach i WordCampach w całej Polsce - WordUp Trójmiasto, WordCamp Polska i WordCamp Europe. Podejdź i porozmawiajmy.

Dodaj kalendarz WP

Potrzebujesz usługi: Programista Next.js we Wrocławiu?

Opisz projekt mailem. Odpowiadam w ciągu 48 godzin.

Opisz projekt

Sprawdź inne usługi WordPress i bazę wiedzy