# Return Portal + Auto-Label: kompletna dokumentacja

> Samoobsługowy portal zwrotów dla klienta, automatycznie generowane etykiety zwrotne dla wielu przewoźników, administracyjny workflow inspekcji oraz silnik rozstrzygnięć (zwrot pieniędzy, powiększony kredyt sklepowy, wymiana) dla WooCommerce. Wersja: 1.0.7 Zgodność: WordPress…

- Strona: <https://www.datafirefly.com/pl/documentation/dfreturnportal/>
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/dfreturnportal/index.md), [en](https://www.datafirefly.com/en/documentation/dfreturnportal/index.md), [es](https://www.datafirefly.com/es/documentation/dfreturnportal/index.md), [de](https://www.datafirefly.com/de/documentation/dfreturnportal/index.md), [it](https://www.datafirefly.com/it/documentation/dfreturnportal/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfreturnportal/index.md), [pt](https://www.datafirefly.com/pt/documentation/dfreturnportal/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

Samoobsługowy portal zwrotów dla klienta, automatycznie generowane etykiety zwrotne dla wielu przewoźników, administracyjny workflow inspekcji oraz silnik rozstrzygnięć (zwrot pieniędzy, powiększony kredyt sklepowy, wymiana) dla WooCommerce.

**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

```bash
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`.

Jeśli zakładka „Zwroty" nie pojawia się w Moim koncie, przejdź do **Ustawienia → Bezpośrednie odnośniki** i kliknij „Zapisz", aby odświeżyć reguły przepisywania.

## 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, 10x15).

### 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)

```php
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

```php
// 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`:

```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ź:

```bash
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.