Return Portal + Auto-Label: kompletna dokumentacja

Wersja: 1.0.7
Zgodność: WordPress 6.2+ • WooCommerce 8.0+ • PHP 8.0+ • HPOS oraz bloki Cart/Checkout

Przegląd

Return Portal + Auto-Label automatyzuje cały cykl życia zwrotu produktu w Twoim sklepie WooCommerce:

• Po stronie klienta: klient zgłasza zwrot bez kontaktu ze wsparciem, wybiera artykuły, wskazuje powód i natychmiast otrzymuje etykietę PDF.
• Po stronie administratora: panel z osią czasu, inspekcja pozycja po pozycji, pełny dziennik aktywności i automatyczne rozstrzygnięcie.
• 6 przewoźników: Ręczny (natywny PDF), Colissimo, Mondial Relay, Chronopost, UPS, DPD.
• 3 rozstrzygnięcia: natywny zwrot pieniędzy WooCommerce, powiększony kredyt sklepowy (+X%) albo automatyczna wymiana.

Statusy zwrotu

Zwrot przechodzi maksymalnie 7 etapów:

Status	Opis
requested	Zgłoszenie przyjęte, oczekuje na zatwierdzenie
approved	Zatwierdzone przez administratora (albo automatycznie poniżej progu)
label_sent	Etykieta wygenerowana i wysłana do klienta
in_transit	Paczka w drodze
received	Paczka odebrana w magazynie
inspecting	Trwa inspekcja artykułów
resolved	Zastosowano rozstrzygnięcie (zwrot / kredyt / wymiana)

Dwa dodatkowe statusy końcowe: rejected (odrzucenie) i cancelled (anulowanie).

Instalacja

Metoda 1: przez panel WordPressa

1. Pobierz ZIP dfreturnportal.zip.
2. W WordPressie przejdź do Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer.
3. Wybierz ZIP, kliknij Zainstaluj teraz.
4. Włącz wtyczkę.

Metoda 2: przez FTP/SSH

cd wp-content/plugins/
unzip dfreturnportal.zip
# Następnie włącz z panelu WordPressa

Weryfikacja po instalacji

• W pasku bocznym WordPressa pojawia się menu Zwroty.
• Endpoint /moje-konto/zwroty/ tworzony jest automatycznie.
• Powstają własne tabele wp_dfrp_returns, wp_dfrp_return_items, wp_dfrp_history, wp_dfrp_attachments.

Konfiguracja początkowa

Przejdź do Zwroty → Ustawienia.

Ogólne

Ustawienie	Opis
Okno kwalifikowalności	Liczba dni po zamówieniu, w których zwrot jest dozwolony. Domyślnie: 30 dni.
Strona portalu klienta	Strona WordPressa, na której wyświetlany będzie shortcode [dfrp_portal]. Opcjonalne, jeśli używasz wyłącznie endpointu Mojego konta.
Powiadomienia administratora	Adres e-mail otrzymujący powiadomienia o nowych zgłoszeniach. Domyślnie: administrator witryny.

Przewoźnik

Wybierz aktywnego przewoźnika spośród 6 dostępnych. Możesz też ustawić format etykiety (A4, A5, A6, 10×15).

Adres zwrotów

Podaj fizyczny adres, na który będą wysyłane paczki zwrotne. Obowiązkowy do generowania etykiet. Pola: Firma, Ulica, Miasto, Kod pocztowy, Kraj (dwuliterowy kod ISO), Telefon, E-mail.

Dane dostępowe przewoźników

Dla każdego przewoźnika API (Colissimo, Mondial Relay i pozostali) rozwijany blok zawiera wymagane dane dostępowe. Uzupełnij wyłącznie dane przewoźnika, z którego korzystasz.

Rozstrzygnięcie

Ustawienie	Opis
Bonus kredytu (%)	Procent doliczany do zwracanej kwoty, gdy klient wybiera powiększony kredyt sklepowy. Domyślnie: 10%.
Próg automatycznego zatwierdzania	Poniżej tej kwoty (w walucie sklepu) zgłoszenia są zatwierdzane automatycznie, a etykieta generowana bez udziału administratora. Wpisz 0, aby wyłączyć.
Rozstrzygnięcie proponowane per powód	Dla każdego powodu (domyślnie 8 powodów) wybierz proponowane rozstrzygnięcie: zwrot pieniędzy / powiększony kredyt / wymiana.

Wykluczenia

• Wykluczone kategorie: identyfikatory WooCommerce rozdzielone przecinkami. Produkty z tych kategorii nigdy nie kwalifikują się do zwrotu.
• Wykluczone SKU: jedno SKU na linię. Analogicznie.

Doświadczenie klienta

Przez stronę Moje konto (zalogowani klienci)

Najprostsza i najczęściej używana ścieżka. Zakładka Zwroty pojawia się automatycznie w menu /moje-konto/ obok „Zamówienia”, „Adresy” i pozostałych.

Klient klika Zwroty, widzi listę kwalifikujących się zamówień (bez wpisywania adresu e-mail i numeru), klika Rozpocznij zwrot przy odpowiednim zamówieniu, wybiera artykuły, wskazuje powód i ilość dla każdej pozycji, w razie potrzeby dodaje zdjęcia (jeśli powód tego wymaga), wybiera preferowane rozstrzygnięcie i natychmiast otrzymuje numer RMA (np. RMA-20260523-A1B2C3) oraz e-mail z potwierdzeniem.

Przez stronę publiczną (klienci bez konta)

Utwórz stronę WordPressa i wstaw shortcode:

[dfrp_portal]

Klient będzie musiał podać numer zamówienia + swój adres e-mail, aby się uwierzytelnić. Reszta ścieżki jest identyczna.

Śledzenie istniejącego zgłoszenia

Na publicznej stronie portalu blok „Śledź istniejące zgłoszenie” pozwala klientom-gościom sprawdzić stan swojego RMA (status, numer śledzenia przewoźnika, link do etykiety).

Personalizacja shortcode’u

[dfrp_portal title="Zgłoszenie zwrotu" context="page"]

Atrybut	Wartości	Opis
title	dowolny tekst	Tytuł portalu (rzadko widoczny wizualnie).
context	page albo myaccount	Wymusza kontekst. myaccount pomija etapę wyszukiwania dla zalogowanych użytkowników.

Workflow administratora

Panel

Dostępny przez Zwroty → Panel. Zawiera 9 kolorowych kart statystyk (liczba per status, klikalnych do filtrowania listy), 10 ostatnich RMA z szybkim dostępem do szczegółów oraz baner z adresem URL portalu klienta i przyciskiem „Kopiuj” do udostępnienia.

Lista zgłoszeń

Dostępna przez Zwroty → Wszystkie zgłoszenia. Tabela z filtrami per status, wyszukiwaniem (RMA, e-mail klienta, numer zamówienia) i paginacją (20 na stronę).

Strona szczegółów zgłoszenia

Komponenty:

1. Nagłówek: kod RMA + odznaka statusu + powrót do listy.
2. Oś czasu: 7 kolorowych punktów pokazujących wizualny postęp.
3. Artykuły do zwrotu: tabela z produktem, SKU, ilością, ceną jednostkową, powodem oraz inspekcją per artykuł (lista Zgodny / Częściowo / Odrzucony, aktywna od statusu received).
4. Zdjęcia klienta: galeria, jeśli klient przesłał materiały.
5. Dziennik aktywności: pełna chronologiczna historia.
6. Informacje: e-mail klienta, link do zamówienia, preferowane rozstrzygnięcie, notatka klienta.
7. Etykieta zwrotna: przewoźnik, numer śledzenia, przycisk pobrania PDF, przycisk regeneracji.
8. Akcje: przyciski „Przejdź do: [następny status]” zgodnie z maszyną stanów.
9. Rozstrzygnij (widoczny przy statusie received albo inspecting): selektor rozstrzygnięcia + przycisk „Zastosuj”.

Możliwe przejścia

Maszyna stanów blokuje nieprawidłowe przejścia:

requested  → approved | rejected | cancelled
approved   → label_sent | rejected | cancelled
label_sent → in_transit | cancelled
in_transit → received
received   → inspecting
inspecting → resolved | rejected

Statusy resolved, rejected i cancelled są końcowe.

Automatyczne zatwierdzanie

Jeśli skonfigurowano próg automatycznego zatwierdzania (np. 50 €), każde zgłoszenie o łącznej kwocie mniejszej lub równej progowi przechodzi automatycznie z requested do approved, etykieta jest generowana natychmiast i wysyłana do klienta, bez interwencji administratora.

Obsługiwani przewoźnicy

Ręczny (bez API)

Idealny na start. Generuje natywny druk zwrotny PDF z kodem QR, bez żadnej zewnętrznej zależności API. Zero konfiguracji, za darmo, działa od razu. Ograniczenie: brak automatycznego śledzenia. Zastosowanie: klient drukuje, Ty wkładasz go do paczki przy pierwotnej wysyłce albo klient przykleja go na paczkę przy klasycznym zwrocie pocztowym.

Colissimo (La Poste)

Oficjalne API REST (usługa Sls generateLabel). Wymagane dane: Contract Number, Password. Specyfika: generuje kod kreskowy parcelNumber, typ zwrotu „3″ (zwrot z korespondencją), domyślny format PDF.

Mondial Relay

API SOAP (WSI4_CreationEtiquette). Wymagane dane: Enseigne, Private Key, Pickup Point. Specyfika: tryb odbioru CCC (Colis Confié Client), obowiązkowy podpis MD5.

Chronopost

API SOAP (shippingMultiParcelV5). Wymagane dane: Account Number, Password, Subaccount. Specyfika: Product Code 8R (zwrot do punktu), tryb zwrotu 2.

UPS

API REST v2403 (/ship). Wymagane dane: Client ID (OAuth2), Client Secret, Shipper Number. Specyfika: ReturnService.Code = 8 (Electronic Return Label), domyślny format GIF base64.

DPD

API REST (endpoint cargonet). Wymagane dane: Username, Password, Customer ID. Specyfika: uwierzytelnianie Basic Auth, format PDF A6.

Rozstrzygnięcia

Zwrot pieniędzy

Korzysta z natywnej funkcji wc_create_refund() WooCommerce. Zwraca środki na pierwotną metodę płatności, automatycznie przywraca stany magazynowe artykułów (konfigurowalne), dodaje notatkę o zwrocie w zamówieniu i generuje natywny e-mail potwierdzający WooCommerce.

Powiększony kredyt sklepowy (Store Credit)

Automatycznie tworzy kupon WooCommerce:

• Kwota = suma zwrotu + bonus (procent konfigurowalny, domyślnie 10 %).
• Ograniczenie e-mail: kupon użyteczny wyłącznie dla adresu e-mail klienta.
• Wygaśnięcie: domyślnie 6 miesięcy.
• Jednorazowy.

Klient otrzymuje e-mail z wyeksponowanym kodem kuponu.

Wymiana

Tworzy nowe zamówienie WooCommerce na 0 € (bezpłatne dla klienta). Adresy dostawy i rozliczeniowy kopiowane z zamówienia źródłowego, artykuły identyczne ze zwróconymi artykułami zgodnymi, status początkowy processing (wysyłasz normalnie). Klient otrzymuje e-mail z numerem nowego zamówienia.

Propozycja automatyczna

Silnik analizuje powody zwracanych artykułów i proponuje najtrafniejsze rozstrzygnięcie. Konfiguracja w Zwroty → Ustawienia → Rozstrzygnięcie proponowane per powód. Domyślne mapowanie:

Powód	Proponowane rozstrzygnięcie
Artykuł uszkodzony	Wymiana
Artykuł wadliwy	Wymiana
Otrzymano niewłaściwy artykuł	Wymiana
Zgodny z opisem, ale nie odpowiada	Zwrot pieniędzy
Zmiana zdania	Powiększony kredyt
Niewłaściwy rozmiar lub kolor	Powiększony kredyt
Opóźniona dostawa	Zwrot pieniędzy
Inny	Zwrot pieniędzy

Personalizacja

Nadpisywanie szablonów

Wszystkie szablony e-maili można nadpisać w motywie. Skopiuj plik źródłowy templates/emails/*.php do twojmotyw/dfreturnportal/emails/*.php.

Hooki (akcje)

do_action('dfrp_after_return_created', int $returnId, array $return);
do_action('dfrp_status_changed', int $returnId, string $fromStatus, string $toStatus);
do_action('dfrp_label_generated', int $returnId, array $label);
do_action('dfrp_before_resolution', int $returnId, string $resolution);
do_action('dfrp_after_resolution', int $returnId, string $resolution, array $result);

Filtry

// Customize eligible order statuses (default: ['completed', 'processing'])
add_filter('dfrp_eligible_order_statuses', function($statuses) {
    $statuses[] = 'on-hold';
    return $statuses;
});

// Customize return reasons
add_filter('dfrp_reasons', function($reasons) {
    $reasons[] = [
        'code'          => 'custom_motif',
        'label'         => 'My custom reason',
        'require_photo' => false,
    ];
    return $reasons;
});

// Customize the My Account endpoint slug (default: 'returns')
add_filter('dfrp_myaccount_endpoint', function() {
    return 'moje-zwroty';
});

// Customize the My Account menu label
add_filter('dfrp_myaccount_menu_label', function() {
    return 'Moje zwroty produktów';
});

// Register a custom carrier
add_filter('dfrp_register_carriers', function($carriers) {
    $carriers[] = new MyCustomCarrier();
    return $carriers;
});

Czysta deinstalacja

Domyślnie deinstalacja zachowuje dane (tabele i opcje). Aby całkowicie wyczyścić dane przy deinstalacji, dodaj w wp-config.php:

define('DFRP_DELETE_DATA_ON_UNINSTALL', true);

API REST

Wszystkie endpointy znajdują się w przestrzeni nazw dfrp/v1. Bazowy adres URL: https://twojawitryna.com/wp-json/dfrp/v1/.

Endpointy publiczne

Endpoint	Metoda	Opis
/lookup	POST	Wyszukuje zamówienie po numerze + adresie e-mail.
/create	POST	Tworzy nowe zgłoszenie zwrotu.
/track	POST	Śledzi RMA po kodzie + adresie e-mail.
/upload-photo	POST	Przesyła zdjęcie potwierdzające (multipart).

Endpointy zalogowanego klienta

Endpoint	Metoda	Opis
/my-orders	GET	Lista kwalifikujących się zamówień zalogowanego klienta.

Endpointy administracyjne (zdolność manage_woocommerce)

Endpoint	Metoda	Opis
/admin/returns	GET	Lista z paginacją i filtrami.
/admin/returns/{id}	GET	Szczegóły zwrotu.
/admin/returns/{id}/transition	POST	Zmiana statusu.
/admin/returns/{id}/inspect-item	POST	Wynik inspekcji artykułu.
/admin/returns/{id}/resolve	POST	Zastosowanie rozstrzygnięcia.
/admin/returns/{id}/regenerate-label	POST	Regeneracja etykiety.

Rozwiązywanie problemów

Portal wyświetla „Ładowanie…” bez końca

• Sprawdź konsolę przeglądarki (F12): powinien pojawić się wpis [Return Portal] script frontend.js exécuté.
• Jeśli nic się nie pojawia, wtyczka bezpieczeństwa (Wordfence, Sucuri, NinjaFirewall) blokuje skrypt inline. Wyłącz ją tymczasowo do testu.
• Sprawdź też optymalizatory JS (WP Rocket „Delay JS”, Autoptimize, Cloudflare Rocket Loader): wtyczka emituje już wymagane atrybuty opt-out, ale niektóre agresywne konfiguracje wciąż mogą blokować.

Zakładka „Zwroty” nie pojawia się w Moim koncie

Przejdź do Ustawienia → Bezpośrednie odnośniki i kliknij „Zapisz zmiany” (bez żadnej zmiany). To wymusza na WordPressie regenerację reguł przepisywania.

Błąd „Constant DFRP_VERSION already defined”

Katalog wtyczki jest zdublowany. Sprawdź:

ls -la wp-content/plugins/ | grep dfreturnportal

Usuń zdublowane kopie (np. dfreturnportal-old/, dfreturnportal-1/).

Klient nie otrzymuje e-maili

• Sprawdź, czy wysyłka e-maili działa globalnie.
• Skonfiguruj porządny SMTP (WP Mail SMTP, FluentSMTP).
• Sprawdź logi spamu domeny odbiorcy.

Etykieta PDF jest pusta albo uszkodzona

• Sprawdź, czy adres zwrotów jest w pełni uzupełniony.
• Dla przewoźników API zweryfikuj dane dostępowe najpierw w trybie testowym.
• Przejrzyj logi PHP (/wp-content/debug.log, jeśli WP_DEBUG_LOG jest aktywny).

FAQ

Czy wtyczka wymaga abonamentu u przewoźnika?
Nie. Tryb Ręczny generuje natywny druk zwrotny PDF bez żadnej zależności API. Tryby API (Colissimo i pozostałe) są opcjonalne.

Zgodność z HPOS (High-Performance Order Storage)?
Tak, w pełni. Wtyczka deklaruje zgodność przy starcie WooCommerce.

Zgodność z blokami Cart/Checkout?
Tak.

Czy warianty produktów są obsługiwane?
Tak, każdy wariant traktowany jest jako osobny artykuł.

A produkty wirtualne albo do pobrania?
Są automatycznie wykluczone ze zwrotów.

Czy klient może zwrócić zamówienie częściowo?
Tak. Kwalifikowalność uwzględnia ilości zwrócone już we wcześniejszych RMA.

Wielojęzyczność?
Wtyczka jest przygotowana do tłumaczenia (Text Domain dfreturnportal, dołączony plik .pot). Zgodna z WPML, Polylang, TranslatePress.

Czy zdjęcia klientów są przechowywane bezpiecznie?
Tak, w bibliotece mediów WordPressa z regułami dostępu .htaccess uniemożliwiającymi listowanie katalogu.