# Product Return Manager — Kompletny przewodnik
> DataFirefly Product Return Manager zamienia obsługę zwrotów PrestaShop 8 w zautomatyzowany przepływ od początku do końca: zgłoszenie klienta w self-service (konto klienta lub gość), etykieta PDF z kodem QR, walidacja…
- Strona:
- Język: pl
- Zaktualizowano: 2026-08-12
- Inne języki: [fr](https://www.datafirefly.com/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-product-return-manager-prestashop-8/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-product-return-manager-prestashop-8/index.md)
- Indeks:
DataFirefly Product Return Manager zamienia obsługę zwrotów PrestaShop 8 w zautomatyzowany przepływ od początku do końca: zgłoszenie klienta w self-service (konto klienta lub gość), etykieta PDF z kodem QR, walidacja skanem przy odbiorze, analityka w 13 wymiarach, kupon lub zwrot pieniędzy, ręczny zwrot admina, automatyczne tłumaczenie powodów przez ChatGPT i integracja z ERP przez hook. Ta dokumentacja obejmuje instalację, pełną konfigurację i codzienne użytkowanie.
## Instalacja
Standardowa instalacja PrestaShop: przejdź do **Moduły → Menedżer modułów → Zainstaluj moduł**, wybierz plik `dfproductreturn.zip` i potwierdź. Moduł automatycznie tworzy 9 tabel z prefiksami `df_return_*` i `df_product_return*`, instaluje domyślne powody zwrotu, rejestruje hooki (`displayCustomerAccount`, `displayMyAccountBlock`, `displayHeader` itd.) i dodaje dwie pozycje menu do back-office: **Zwroty produktów** (zarządzanie) i **Analityka zwrotów** (statystyki).
Wymagania: PrestaShop 8.0 do 8.99, PHP 8.0 do 8.3. PrestaShop 1.7 nie jest obsługiwany. Multistore jest obsługiwany natywnie. Aktualizacja z wcześniejszej wersji jest idempotentna (skrypty upgrade'u dołączone, w tym dodanie kolumny `manual_amount` w 1.7).
## Konfiguracja
Przejdź do **Moduły → Menedżer modułów → DataFirefly Product Return Manager → Konfiguruj**. Główne ustawienia:
- **Termin zwrotu (dni)** — okno, w którym klient może zgłosić zwrot po zamówieniu. Domyślnie 30 dni. Dotyczy tylko zwrotów inicjowanych po stronie klienta; ręczny zwrot admina go ignoruje.
- **Kwalifikujące statusy zamówień** — tylko zamówienia w tych statusach pokazują przycisk „Zgłoś zwrot” (zwykle „Dostarczone”).
- **Włącz kupon** — proponuje opcję kuponu jako formę rekompensaty.
- **Włącz zwrot pieniędzy** — proponuje opcję zwrotu na pierwotną metodę płatności.
- **E-mail admina** — adres powiadamiany o każdym nowym zgłoszeniu zwrotu.
- **Status zwrotu częściowego / pełnego** — dwa statusy zamówienia stosowane zależnie od rodzaju zrealizowanego zwrotu.
- **Klucz API OpenAI** — wymagany tylko do automatycznego tłumaczenia powodów zwrotu przez ChatGPT (patrz dedykowana sekcja).
## Powody zwrotu i kategorie
Moduł organizuje powody na dwóch poziomach: **kategorie** („Problem z produktem”, „Problem logistyczny”, „Zmiana zdania”…) i **powody** przypisane do każdej kategorii („Nieprawidłowy rozmiar”, „Wadliwy artykuł”, „Zbyt długa dostawa”…). Ta hierarchia zasila analitykę: widzisz rozkład makro per kategoria, a potem szczegóły per powód.
Zarządzaj nimi z zakładki **Powody** konfiguracji: tworzenie, edycja, dezaktywacja, kolejność wyświetlania. Domyślne powody są instalowane z modułem — dostosuj je do katalogu.
Dobre praktyki: trzymaj poniżej 10 widocznych powodów na kategorię, aby nie zalać klienta, i formułuj powody z jego punktu widzenia („Artykuł nie odpowiada zdjęciu” zamiast „Niezgodność wizualna”).
### Automatyczne tłumaczenie przez ChatGPT
Po wpisaniu klucza API OpenAI w konfiguracji przy każdym powodzie i kategorii pojawia się przycisk **Tłumacz**. Kliknięcie tłumaczy etykietę na wszystkie aktywne języki sklepu, ze skontekstualizowanym słownictwem e-commerce. Tłumaczenia pozostają edytowalne ręcznie po wygenerowaniu. Klucz uzyskasz na `platform.openai.com` — koszt jednego tłumaczenia jest pomijalny (ułamki centa).
## Ścieżka klienta (konto klienta)
Zalogowany klient widzi link **„Moje zwroty”** w swoim panelu. Aby zainicjować zwrot:
1. Otwiera kwalifikujące się zamówienie i klika „Zgłoś zwrot”.
2. Zaznacza produkty do zwrotu i dostosowuje ilości.
3. Wybiera kategorię powodu, potem konkretny powód, i dodaje opcjonalny komentarz.
4. Zatwierdza — zwrot przechodzi w status „Oczekujący” i wychodzą dwa e-maile: potwierdzenie do klienta z PDF-em etykiety w załączniku oraz powiadomienie do admina.
Klient śledzi potem stan zwrotu (oczekujący, zaakceptowany, odrzucony, zwrócony) w „Moich zwrotach”, z możliwością ponownego pobrania etykiety PDF w każdej chwili.
## Zwrot gościa (v1.7+)
Klienci, którzy zamówili **bez zakładania konta**, mają dostęp do zwrotu z tego samego URL co zalogowani. Niezalogowany odwiedzający widzi formularz **„Numer zamówienia + e-mail”** zamiast listy „Moje zamówienia”. Działanie:
- Walidacja odbywa się po stronie serwera: para referencja zamówienia + e-mail musi dokładnie odpowiadać istniejącemu zamówieniu (porównanie e-maila bez rozróżniania wielkości liter).
- Przy braku dopasowania komunikat błędu jest celowo ogólny — ochrona przed enumeracją, żadne informacje o istniejących referencjach nie są ujawniane.
- Po walidacji odwiedzający uzyskuje dostęp do standardowego przepływu zwrotu _tylko dla tego zamówienia_ (sesja PrestaShop scoped).
- PDF etykiety pozostaje dostępny z linku otrzymanego e-mailem **bez logowania**, chroniony losowym tokenem 64 znaków, unikalnym dla zwrotu.
- Baner „Use a different order” pozwala zresetować sesję gościa i przełączyć się na inne zamówienie.
## PDF etykiety i kod QR
Każdy zwrot generuje PDF zawierający: adres zwrotu, numer zwrotu, listę produktów i ilości, instrukcje oraz **unikalny kod QR** z kryptograficznym tokenem weryfikacyjnym. Klient drukuje go i nakleja na paczkę.
### Wiele adresów zwrotu
Skonfiguruj kilka adresów w zakładce **Adresy** (główny magazyn, ośrodek obsługi dużych wolumenów, adres UE vs poza UE…). Każdy zwrot jest powiązany z adresem, który pojawia się na jego etykiecie.
## Walidacja skanem QR przy odbiorze
Gdy paczka dociera, Twój operator skanuje QR telefonem lub czytnikiem USB. Skan otwiera zabezpieczoną stronę walidacji — **wymagana jest aktywna sesja admina PrestaShop**; bez sesji strona przekierowuje do logowania back-office. Operator widzi pełne szczegóły zwrotu, sprawdza fizyczny stan produktów i klika **Zatwierdź** lub **Odrzuć**.
Zatwierdzenie uruchamia kaskadowo: przejście zamówienia w skonfigurowany status (zwrot częściowy lub pełny), generowanie kuponu lub zwrotu pieniędzy, e-mail aktualizacji do klienta oraz dispatch hooka `actionOrderSlipAdd` dla integracji zewnętrznych.
Token QR jest unikalny per zwrot i weryfikowany po stronie serwera: sfałszowany lub użyty ponownie QR jest odrzucany. Nigdy nie udostępniaj adresów URL walidacji poza swoim zespołem.
## Ręczny zwrot admina (v1.6+)
Obsługa klienta może utworzyć zwrot dla **dowolnego zamówienia**, niezależnie od skonfigurowanego terminu zwrotu i statusu zamówienia — zaprojektowane dla gestów handlowych, zwrotów negocjowanych telefonicznie i regularyzacji wstecznych.
1. Kliknij **„Create manual return”** w nagłówku listy zwrotów w back-office.
2. **Krok 1** — wpisz referencję lub ID zamówienia (akceptowane jest zamówienie z 2022, anulowane lub w wersji roboczej).
3. **Krok 2** — zaznacz produkty do zwrotu, ich ilości, powód, rodzaj rekompensaty (kupon lub nota kredytowa) i w razie potrzeby dostosuj **kwotę zwrotu per linia**.
4. Zatwierdź: zwrot jest przetwarzany natychmiast — kupon lub nota generowane od ręki, stan magazynowy przywracany, status zamówienia aktualizowany, hook Fastmag dispatchowany.
Checkbox **„Powiadom klienta”** (domyślnie odznaczony) wysyła standardowy e-mail potwierdzenia, jeśli chcesz. Do zwrotu można dołączyć dowolną notatkę admina.
### Personalizowana kwota zwrotu (v1.7+)
Każda linia ręcznego zwrotu ma edytowalne pole **„Refund amount”**. Wartość domyślna (cena jednostkowa × ilość) jest automatycznie przeliczana przy zmianie ilości, aż do ręcznego wpisania — wpisana wartość jest wtedy respektowana dosłownie. Proporcjonalny współczynnik rabatów zamówienia, stosowany przy klasycznych zwrotach klienta, jest **wyłączony dla zwrotów ręcznych**: wpisana kwota jest dokładnie kwotą zwracaną. Przydatne przy zwrocie częściowym (uszkodzony produkt zwracany w 50%), geście handlowym lub regularyzacji. Wygenerowana nota kredytowa zachowuje proporcjonalny podział netto/brutto według stawki VAT pierwotnej linii.
## Kupon lub zwrot pieniędzy
Zależnie od konfiguracji zatwierdzenie zwrotu generuje albo **kupon** (natywna reguła koszyka PrestaShop, do użycia przy kolejnym zamówieniu), albo **zwrot pieniędzy** do zrealizowania na pierwotnej metodzie płatności. Dwa dedykowane statusy zamówienia (częściowy / pełny) pozwalają rozróżnić przypadki w eksportach i raportach księgowych.
## Dashboard analityki
Menu **Analityka zwrotów** udostępnia 13 wymiarów analizy, wszystkie filtrowane po okresie i sklepie:
- **Globalne KPI** — wolumen zwrotów, wskaźnik zwrotów, zwrócona wartość, podział kupon / zwrot pieniędzy.
- **Per kategoria powodu** i **per powód** — identyfikuj dominujące przyczyny.
- **Per kraj** — wykrywaj anomalie geograficzne (zawodny przewoźnik w danej strefie).
- **Top zwracanych produktów** — referencje do zbadania (tabela rozmiarów, jakość dostawcy).
- **Krzyżówki powód × kraj i powód × produkt** — poziom szczegółu do działania.
- **Trend miesięczny (12 miesięcy) i dzienny** — sezonowość i piki.
- **Średni czas obsługi** — wydajność Twojej obsługi klienta.
- **Rozkład po dniach tygodnia** i **top klientów zwracających** — wykrywanie nadużyć.
Przycisk **Eksport CSV** pobiera wszystkie zwroty z filtrowanego okresu (nr zwrotu, zamówienie, klient, produkty, powód, status, daty, kwota) do analizy zewnętrznej lub importu BI.
## Integracja Fastmag i ERP
Przy każdym zatwierdzonym zwrocie moduł dispatchuje hook PrestaShop `actionOrderSlipAdd` z zamówieniem, listą produktów i ilościami. Każdy moduł nasłuchujący tego hooka (moduł Fastmag DataFirefly, konektory ERP, Systempay…) otrzymuje powiadomienie w czasie rzeczywistym. Ręczne zwroty admina dispatchują ten sam hook.
Przycisk **„Re-sync past returns to Fastmag”** (pasek narzędzi listy zwrotów) ponownie wyzwala hook na wszystkich przeszłych zwrotach — niezbędne po instalacji konektora ERP późniejszej niż ten moduł albo po incydencie synchronizacji.
## E-maile transakcyjne
Trzy automatyczne e-maile, dostarczane w 6 językach (FR, EN, ES, IT, PT, DE): potwierdzenie zgłoszenia do klienta (z załączonym PDF-em), powiadomienie do admina, aktualizacja statusu do klienta (zatwierdzenie / odrzucenie / zwrot pieniędzy). Przy ręcznych zwrotach admina e-mail do klienta jest opcjonalny (checkbox domyślnie odznaczony). Dostosuj szablony w `modules/dfproductreturn/mails//` lub przez natywny system tłumaczeń e-mail PrestaShop.
## Multistore
Wszystkie tabele mają `id_shop`: każdy sklep ma własne powody, adresy zwrotu i analitykę. Selektor multistore back-office naturalnie filtruje listę zwrotów i dashboard.
## Rozwiązywanie problemów
### Przycisk „Zgłoś zwrot” się nie pojawia
Sprawdź trzy punkty: zamówienie jest w kwalifikującym statusie (konfiguracja), termin zwrotu nie minął, moduł jest aktywny w danym sklepie (kontekst multistore). Przypomnienie: dla zwrotu po terminie użyj ręcznego zwrotu admina.
### Formularz gościa odrzuca ważne zamówienie
Wpisany e-mail musi być dokładnie tym z zamówienia (wielkość liter jest ignorowana, ale nie literówki). Sprawdź referencję zamówienia — to referencja alfanumeryczna (np. XKBKNABJK), nie ID numeryczne.
### Skan QR pokazuje „Access denied”
To oczekiwane zachowanie bez sesji admina: operator musi być zalogowany do back-office PrestaShop w tej samej przeglądarce. Zaloguj się i zeskanuj ponownie.
### Tłumaczenie ChatGPT zawodzi
Sprawdź klucz API w konfiguracji, dostępny kredyt na koncie OpenAI oraz czy serwer zezwala na połączenia wychodzące do `api.openai.com` (port 443).
### Fastmag nie otrzymuje zwrotów
Sprawdź, czy moduł Fastmag jest zainstalowany i podpięty pod hook `actionOrderSlipAdd`, potem użyj „Re-sync past returns to Fastmag”, aby nadrobić historię.