Woo — integracja WooCommerce (core/woocommerce)

Instancja modułu obsługuje jeden sklep. Można zainstalować kilka instancji w tej samej firmie. Import, płatności, zmiany statusów i numery przesyłek przechodzą przez kontrakty hooków Orbito. Moduł nie zależy od kodu ani bazy innego modułu.

Uruchomienie

W WooCommerce → Ustawienia → Zaawansowane → REST API utwórz klucz

z uprawnieniem Odczyt/Zapis. Włącz przyjazne bezpośrednie odnośniki WordPress.

W Orbito zezwól firmie na wychodzące zapytania do domeny sklepu.
W konfiguracji instancji zapisz URL HTTPS sklepu, Consumer Key i Consumer

Secret. Klucze mają format SECRET; nie umieszczaj ich w plikach ani logach. Moduł wyłącza zrzuty transportu RPC SDK, zachowując logi operacji biznesowych.

W „Import zamówień i płatności” wskaż status początkowy oraz wybierz datę

i godzinę początku importu w kalendarzu. Formularz używa strefy czasowej firmy ustawionej w Orbito i domyślnie uzupełnia bieżący czas w nowej konfiguracji. Przy jednym dostawcy zamówień pole wyboru instancji jest ukryte; kilku wymaga jawnego wyboru. Zapisany niedostępny dostawca pozostaje widoczny do naprawy.

Wybierz tryb bieżący lub historyczny. Historyczny import zapisuje zamówienia

bez automatyzacji sprzedaży. Daty są czytane z pól *_gmt Woo, niezależnie od strefy serwera. Wybrany w kalendarzu czas firmy jest przeliczany do UTC na potrzeby API WooCommerce. Datę można edytować do pierwszego udanego pobrania zamówień (automatycznie lub ręcznie po ID). Wtedy zostaje trwale zablokowana i formularz pokazuje ją jako informację. Pusta odpowiedź importu również blokuje datę; błąd pobrania nie blokuje. Test połączenia i podgląd nie blokują daty. Blokada chroni też przed zapisem ze starego formularza lub przez API, przetrwa restart i wyłączenie harmonogramu. Działające integracje zachowują swoją datę.

Zmapuj statusy Orbito → Woo. Każdy status Orbito ma osobny wybór; puste pole

wyłącza jego wysyłkę. Listy zachowują zapisane ID podczas awarii dostawcy.

Włącz oficjalną wtyczkę WooCommerce Shipment Tracking i skonfiguruj jej

API w bloku „WooCommerce Shipment Tracking”. Bieżący namespace to wc-shipment-tracking/v3; dla starszej wersji można wybrać wc/v3.

Konfiguracja jest dostępna wyłącznie w Ustawienia → Moduły → Woo.

Moduł nie dodaje osobnego widoku ani skrótu w głównej nawigacji. Metody testConnection i importOrder są dostępne dla narzędzi administracyjnych.

Automatyczny import i synchronizacja są początkowo wyłączone. Po włączeniu zadanie działa co minutę, przetwarza do 250 nowych zamówień i kontroluje do 25 wcześniej zaimportowanych. Długie okno importu zapisuje numer strony i jest kontynuowane w kolejnym cyklu. Kolejka kontroli obejmuje także stare zamówienia oczekujące na płatność i uzupełnia zgubione zdarzenia; pełny obieg dużego zbioru może trwać dłużej niż minutę. Wyłączenie zatrzymuje synchronizację ze sklepem. Ręczny import po ID działa niezależnie od harmonogramu. Nieudany import zapisuje ID zamówienia w trwałej kolejce; co cykl ponawianych jest do 5 zaległych importów z przerwą 5 minut po błędzie. Wadliwe zamówienie nie blokuje importu pozostałych. Strona importu jest przesuwana dopiero po zapisaniu wyniku lub trwałego zlecenia ponowienia dla każdego ID.

Filtry dat API wysyłają sekundy UTC bez sufiksu strefy, z dates_are_gmt=true. Wersja 1.0.6 jednorazowo sprawdza ponownie zakres od zablokowanej daty początku importu: starszy format z Z mógł zwracać puste okna i przesuwać kursor mimo pominiętych zamówień. Istniejące powiązania nie są tworzone ponownie.

Zakres danych

Import obejmuje pozycje i warianty, SKU, EAN udostępniony w zamówieniu, zdjęcie, ilości, ceny po rabatach, VAT, opłaty, rabaty zapisane jako ujemne opłaty, adresy, dane kontaktowe, sposób i koszt dostawy, walutę, metodę płatności, potwierdzoną wpłatę i wiadomość klienta. Kupony nie są odejmowane ponownie od kwot pozycji. Nietypowe zaokrąglenia, zwroty i niezgodne sumy trafiają do trybu weryfikacji z zachowaniem źródłowej sumy. Brak kwot nie jest zastępowany zerem.

Woo nie ma jednego standardowego pola NIP ani punktu odbioru. Opcjonalne klucze metadanych pozwalają odczytać te pola z głównego meta_data zamówienia. Nazwę pola znajdziesz w odpowiedzi REST API GET /wp-json/wc/v3/orders/ID dla przykładowego zamówienia z NIP lub punktem odbioru: skopiuj key przy wpisie, którego value zawiera właściwe dane. Dokumentacja wtyczki checkoutu lub dostawy również może podawać nazwę. Formularz pokazuje te instrukcje bezpośrednio pod polami. Dla innego schematu wtyczki sklepu potrzebny będzie osobny adapter. Katalog i skład zestawów pozostają zarządzane po stronie dostawcy zamówień. Kolejne kontrole nie nadpisują ręcznie poprawionych danych, pozycji ani statusu Orbito danymi z Woo. Zmiana kwoty lub waluty Woo wymaga sprawdzenia przed automatycznym dopisaniem wpłaty.

Pobieranie katalogu produktów

W Ustawienia → Moduły → Woo → Import produktów kliknij Pobierz wszystkie aktywne produkty. Zadanie działa w tle, niezależnie od automatycznego importu zamówień. Przycisk Odśwież postęp pokazuje podsumowanie. Import obejmuje produkty ze statusem publish, również ukryte w katalogu i bez dostępnego zapasu, oraz opublikowane warianty aktywnych produktów. Szkice, produkty prywatne i nieaktywne warianty są pomijane.

Do bazy produktów trafiają nazwa, SKU, dostępny EAN, marka, zdjęcie, waga w kg, cena bazowa netto i VAT możliwy do jednoznacznego ustalenia z ustawień sklepu. Kontenery wariantów i grup nie otrzymują pozornej pojedynczej ceny. Brak danych lub niejednoznaczne regionalne reguły VAT nie są zastępowane zerem; podsumowanie wskazuje pominięte pola. Nie zmieniamy zapasów ani danych w WooCommerce.

Katalog łączy produkty po SKU i tożsamości źródła, z osobną tożsamością każdej instancji Woo. Identyfikatory produktu/wariantu są takie same jak w imporcie zamówień. Ponowne pobranie aktualizuje dane źródłowe bez tworzenia duplikatów; lokalne podmiany, ręczny skład zestawu i wybór rozbijania w zamówieniu pozostają po stronie bazy produktów. Import nie usuwa wcześniej zapisanych produktów.

Postęp i bieżąca strona są trwałe. Po restarcie kontenera zadanie kontynuuje pobieranie. Błąd odczytu sklepu wstrzymuje zadanie — po naprawie wybierz Wznów import. Rozłączenie bazy również zachowuje bieżącą pozycję i uruchamia do trzech ponowień z odstępami 10, 30 i 60 sekund; po ich wyczerpaniu zadanie jest wstrzymywane. Pewne błędy danych pojedynczych pozycji nie blokują pozostałych; podsumowanie pokazuje ich liczbę i pierwsze 20 przykładów. Po naprawie przyczyny można ponowić pobranie całego katalogu. Zakończ import zatrzymuje zadanie, zachowując już zapisane produkty. Import produktów nie blokuje daty zamówień.

Metody administracyjne: startProductImport, productImportStatus, resumeProductImport; wymagają uprawnienia products.import.

Integracja używa idempotentnego kontraktu hooków products.catalog.ingest, obsługiwanego przez core/products od 1.4.3 i zgodnych dostawców. Pole wyboru bazy jest widoczne przy kilku dostawcach; jedna baza jest wybierana automatycznie. Potwierdzenie zawiera identyfikator zapisanej kartoteki również przy braku SKU.

Płatności i statusy

Status jest sterowany przez Orbito. Początkowy status importu nie jest odsyłany do Woo. Zmiana zmapowanego statusu powoduje wysłanie bieżącego stanu Orbito, również gdy zdarzenie dotarło z opóźnieniem. Woo może uruchomić własne wiadomości, hooki i zmianę zapasów. Moduł nie wysyła set_paid.

Wpłata jest potwierdzana przez date_paid_gmt, z identyfikatorem transakcji, kwotą i walutą. Sam status processing lub completed nie stanowi potwierdzenia. Woo potrafi jednak automatycznie ustawić datę opłacenia przy zmianie statusu: moduł zapisuje stan sprzed własnego zapisu i odrzuca tak wygenerowaną datę. Przy utracie odpowiedzi najpierw odczytuje i rozlicza wynik zapisu. Nowa transakcja bramki może później potwierdzić rzeczywistą wpłatę. Jeżeli bramka nie zmienia ani identyfikatora transakcji, ani daty wygenerowanej wcześniej przez status, REST API nie pozwala rozpoznać tego zdarzenia — wpłatę trzeba wtedy zweryfikować w Orbito.

Pobranie bez identyfikatora transakcji nie jest automatycznie oznaczane jako opłacone. Zwroty są raportowane do ręcznego rozliczenia; moduł nie tworzy ujemnych płatności. Synchronizacja docelowej sumy wpłat używa kontraktu orders.payments.syncExternalTotal, zachowuje ręczne korekty i deduplikuje ponowienia. Import zamówień wymaga idempotentImport i sourcePaymentReconciliation od dostawcy zamówień.

Przesyłki

Hook event:shipment:created odczytuje kanoniczne przesyłki przez kontrakt shipping.shipments.getByOrderId uwierzytelnionego nadawcy. Zdarzenie służy wyłącznie jako sygnał, nie jest źródłem numeru listu. Kontrola okresowa korzysta ze wskazanej instancji przesyłek albo jedynego dostępnego dostawcy. Kilku dostawców wymaga wyboru; brak zainstalowanego dostawcy nie blokuje samego importu. Moduł nie wybiera arbitralnie pierwszej odpowiedzi.

Każda paczka trafia do API Shipment Tracking jako osobny wpis: numer, przewoźnik i data utworzenia. Przewoźnik jest dopasowywany do listy Woo; niestandardowy wymaga linku HTTPS zwróconego przez dostawcę przesyłek. Przesyłki anulowane, usunięte i należące do zamówień powiązanych są pomijane. Dostępne numery są zapisywane przed zmianą statusu na completed, dzięki czemu mogą trafić do wiadomości statusowej Woo. Sam zapis numeru w oficjalnej wtyczce nie wysyła wiadomości do klienta.

Potwierdzone numery nie są ponownie tworzone. Moduł nie usuwa ani nie zmienia już przekazanych wpisów po anulowaniu lub korekcie listu w Orbito; taką korektę wykonuje operator w WooCommerce.

Niepewne odpowiedzi i diagnostyka

Przed PUT statusu i POST numeru listu moduł utrwala próbę w swojej bazie. Po timeout lub restarcie wykonuje wyłącznie odczyt. Zgodny stan potwierdza zapis, niezgodny wymaga weryfikacji historii Woo — nie powtarza automatycznie operacji, która mogła wysłać mail lub utworzyć list.

Powiązania i błędy zwraca metoda listImports. Błędy są widoczne w Problemach firmy. Metody diagnostics, verifyContracts, testConnection, listImports i pendingWrites służą diagnostyce. Po ręcznym sprawdzeniu historii Woo można wywołać acknowledgeNotApplied z wooOrderId, kind (status albo tracking), konkretnym attemptId z pendingWrites i confirmNotApplied: true. Wymaga uprawnienia sync.manage, ponownie sprawdza stan Woo i zapisuje potwierdzenie operatora w logach. Następny cykl może ponowić tak odblokowany zapis. Nie używaj tego do potwierdzonych efektów. previewLatestOrder sprawdza rzeczywiste dane ostatniego zamówienia bez importu i zwraca kontrolę finansową bez danych osobowych klienta. testConnection z tracking: false pozwala oddzielnie sprawdzić główne API WooCommerce. diagnostics pokazuje też kursor i okno importu; previewOrderPolling porównuje odczyt od daty początkowej, od kursora i wokół najnowszego zamówienia bez tworzenia zamówień ani zmian w WooCommerce.

URL sklepu po pierwszym imporcie jest przypięty do instancji. Dla innego sklepu zainstaluj nową instancję. Mapowania utrwalają też instancję dostawcy zamówień; zmiana domyślnego dostawcy nie przenosi istniejących zamówień.

Favicon sklepu jest pobierany przez Core.fetch z publicznej strony bez kluczy WooCommerce i rejestrowany jako ikona źródła zamówień przez hook orders.source.register. Dotyczy także istniejących zamówień; nie jest potrzebny ich ponowny import. Obsługiwane są PNG, ICO, JPEG, WebP i GIF do 45 KiB z tej samej domeny HTTPS. Błąd odświeżenia zachowuje poprzednią ikonę. Metoda refreshSourceIcon umożliwia ręczne odświeżenie; zwykła kontrola korzysta z cache.

Numer widoczny w sklepie (pole Woo number, np. 11363) jest udostępniany przez sources.orders.presentation z lokalnych powiązań, bez odpytywania Woo przy otwieraniu listy. Dotyczy też istniejących importów. Zwracany jest wyłącznie zapisanej instancji dostawcy zamówień, po sprawdzeniu pełnej tożsamości źródła. Techniczne ID Woo i klucz deduplikacji pozostają bez zmian.

Starsza data importu zapisana jako UTC jest prezentowana w czasie firmy z zachowaniem jej momentu i istniejącego kursora importu. Wybrana godzina, która nie istnieje przy wiosennej zmianie czasu, jest odrzucana. Dla dwukrotnie występującej nowej godziny jesienią wybierane jest pierwsze wystąpienie; starszy zapis UTC zachowuje swoje konkretne wystąpienie.

Wykrywanie NIP-u i punktu odbioru

W konfiguracji dostępna jest zakładka Wykryj NIP i punkt odbioru:

Wybierz numer zamówienia widoczny w sklepie lub ID WooCommerce (z adresu edycji).
Podaj przykład z NIP-em, punktem odbioru lub oba; może to być jedno zamówienie.
Kliknij Zapisz, następnie Wykryj pola. Akcje konfiguracji korzystają

z zapisanych wartości formularza.

Sprawdź podgląd wartości. Jedna propozycja jest zaznaczona; przy kilku wybierz

właściwą i zapisz formularz. Kliknij Zastosuj wybrane pola.

Wykrywanie czyta meta_data zamówienia i dostaw w shipping_lines, także zagnieżdżone obiekty i tablice. NIP jest rozpoznawany po formacie, sumie kontrolnej i nazwie pola, punkt po nazwie pola i wartości. Są to propozycje do sprawdzenia; moduł nie wybiera arbitralnie spośród kilku pól. Różnych punktów kilku dostaw nie sprowadza do jednego punktu. Gdy wtyczka nie udostępnia danych w REST API lub używa niestandardowego kodowania, może być potrzebny adapter.

Numer widoczny w sklepie nie jest traktowany bezwarunkowo jako ID REST API. Własna numeracja wtyczki musi być wyszukiwalna; w przeciwnym razie wybierz ID. Wykrywanie niczego nie importuje, nie zapisuje w Woo ani nie blokuje daty importu. Zapisane propozycje zawierają tylko wskazania pól i podgląd NIP-u/punktu, osobno dla użytkownika. Zastosowanie ponownie sprawdza przykład i zapisuje pola w konfiguracji importu całej instancji. Ustawienie jednego pola zachowuje drugie. Nowe ustawienia dotyczą kolejnych importów, bez zmiany już utworzonych zamówień.

Zwykłe klucze meta_data pozostają zgodne z ręczną konfiguracją. Dla pól zagnieżdżonych i dostawy używany jest identyfikator woo-meta: z zakodowaną ścieżką. Formularz pokazuje obok niego czytelny opis pola; nie zmieniaj go ręcznie. Plik assets/woo-icon.png zawiera dostarczoną ikonę karty modułu. Nazwa wyświetlana to Woo; kod integracji core/woocommerce pozostaje zachowany dla zgodności i wyszukiwania po WooCommerce.

Weryfikacja

npm test sprawdza mapowanie finansów, daty UTC, ochronę przed fikcyjną wpłatą, idempotencję, utratę odpowiedzi, kilka paczek, izolację instancji, stronicowanie oraz rzeczywistą ścieżkę protokołu hooków z alternatywnymi dostawcami. Pełny workspace z module-contracts/*.test.js nie jest dostępny w tym katalogu. Test produkcyjnego sklepu wymaga kluczy wpisanych przez administratora oraz zamówienia testowego. Sam poprawny start kontenera nie potwierdza integracji Woo.

Dokumentacja źródłowa: