# DF Quantity Tiers: dokumentacja
> Prezentacja i wymagania DF Quantity Tiers zamienia natywne rabaty ilościowe PrestaShop w czytelny i klikalny blok sprzedażowy. Moduł nie wprowadza żadnej nowej logiki cenowej: odczytuje ceny specyficzne „od N sztuk”…
- Strona:
- Język: pl
- Zaktualizowano: 2026-10-28
- Inne języki: [fr](https://www.datafirefly.com/documentation/df-quantity-tiers/index.md), [en](https://www.datafirefly.com/en/documentation/df-quantity-tiers/index.md), [es](https://www.datafirefly.com/es/documentation/df-quantity-tiers/index.md), [de](https://www.datafirefly.com/de/documentation/df-quantity-tiers/index.md), [it](https://www.datafirefly.com/it/documentation/df-quantity-tiers/index.md), [pt](https://www.datafirefly.com/pt/documentation/df-quantity-tiers/index.md), [nl](https://www.datafirefly.com/nl/documentation/df-quantity-tiers/index.md)
- Indeks:
## Prezentacja i wymagania
DF Quantity Tiers zamienia natywne rabaty ilościowe PrestaShop w czytelny i klikalny blok sprzedażowy. Moduł nie wprowadza żadnej nowej logiki cenowej: odczytuje ceny specyficzne „od N sztuk” już skonfigurowane w Twoim katalogu i prezentuje je w formie kart lub tabeli, z przyciskiem dodania do koszyka dla każdego progu.
- Zgodny z PrestaShop 8.0 do 9.x, szablon Classic i szablony pochodne.
- PHP 7.4 do 8.3.
- Multisklep i wielojęzyczność: interfejs przetłumaczony na angielski, francuski, niemiecki, włoski, hiszpański, niderlandzki, portugalski i polski. W każdym innym języku teksty wyświetlają się po angielsku.
- Brak nadpisywania plików: wyłącznie natywne hooki.
Progi pochodzą z **Katalog > Produkt > Ceny > Ceny specyficzne**, pole „Od ilości”. Jeśli produkt nie ma cen specyficznych według ilości, blok nie wyświetla się dla tego produktu.
## Instalacja
Zainstaluj moduł jak każdy inny moduł PrestaShop:
1. Pobierz archiwum `dfquantitytiers-1.2.2.zip` ze swojego konta klienta.
2. W panelu administracyjnym przejdź do **Moduły > Menedżer modułów**.
3. Kliknij **Wgraj moduł** i wskaż archiwum.
4. Po instalacji kliknij **Konfiguruj**.
Podczas instalacji moduł rejestruje swoje hooki, tworzy tabelę statystyk i wstępnie wypełnia tytuł bloku przetłumaczony na każdy język sklepu. Twoje istniejące ceny progowe wyświetlają się natychmiast na odpowiednich kartach produktów.
## Aktualizacja
Aktualizacja przebiega standardowo z poziomu Menedżera modułów: wystarczy wgrać nowe archiwum na poprzednią wersję. Twoja dotychczasowa konfiguracja zostaje zachowana.
- **Z wersji 1.0.0**: wbudowany skrypt aktualizacji tworzy tabelę statystyk, rejestruje hook strony koszyka i ustawia wartości domyślne opcji wprowadzonych w wersji 1.1.0.
- **Z wersji 1.1.x lub 1.2.0**: żadna migracja nie jest potrzebna.
Po aktualizacji wyczyść pamięć podręczną w **Zaawansowane > Wydajność**. Bez tego kroku PrestaShop może nadal serwować stare szablony i stare teksty (na przykład francuskie etykiety w sklepie włoskim).
## Konfiguracja ogólna
Strona konfiguracji skupia wszystkie ustawienia wyświetlania:
- **Tytuł bloku**: tekst wyświetlany nad progami, tłumaczony per język. Pozostaw puste, aby całkowicie ukryć tytuł.
- **Układ**: „Karty (zalecane)”, czyli jedna karta na próg, lub „Kompaktowa tabela”, czyli jeden wiersz na próg.
- **Pozycja na stronie produktu**: pod blokiem zakupu (hook `displayProductAdditionalInfo`, domyślnie) lub bezpośrednio pod ceną (hook `displayProductPriceBlock`).
- **Kolor akcentu**: stosowany do progu „Najlepsza oferta”, odznak i przycisków.
- **Wyświetlanie oszczędności**: w procentach („-10%”), jako kwota oszczędności na sztuce („Oszczędzasz 0,78 € / szt.”) lub oba naraz („Procent + kwota”).
- **Pokaż cenę całkowitą progu**: dodaje sumę dla dokładnie tej ilości, jaką określa próg, z opisem „Razem za 6 szt.: 42,12 €”. Domyślnie wyłączone.
- **Pokaż próg „za sztukę”**: wyświetla cenę bazową jako pierwszy próg porównawczy.
Oszczędność jest podawana na sztuce, aby pozostała poprawna niezależnie od zamówionej ilości: klient, który bierze 7 sztuk przy progu „6+”, rzeczywiście oszczędza 0,78 € na każdej sztuce. Cena całkowita jest natomiast prawdziwa tylko dla dokładnej ilości progu, dlatego domyślnie jest wyłączona.
Próg z najniższą ceną jednostkową otrzymuje automatycznie odznakę „Najlepsza oferta” (tylko wtedy, gdy istnieją co najmniej dwa progi rabatowe). Gdy klient zmienia ilość, karta odpowiadająca jego wyborowi jest podświetlana w czasie rzeczywistym.
## Tryb podatkowy (B2B)
Tryb podatkowy decyduje, czy ceny progów są wyświetlane netto czy brutto:
- **Automatyczny (grupa klientów)**: podąża za ustawieniem wyświetlania bieżącej grupy klienta (standardowe zachowanie PrestaShop).
- **Wymuś netto**: zawsze wyświetla ceny netto, z oznaczeniem „netto” obok każdej ceny jednostkowej. Idealne dla sklepu profesjonalnego.
- **Wymuś brutto**: zawsze wyświetla ceny brutto, z oznaczeniem „brutto”.
Wybrany tryb stosuje się jednocześnie do kart na stronie produktu, do bloku zachęty w koszyku i do danych strukturalnych. Oznaczenie jest tłumaczone na język odwiedzającego (na przykład „IVA escl.” po włosku, „zzgl. MwSt.” po niemiecku).
## Etykiety opakowań
Możesz przypisać etykietę branżową do każdej ilości, na przykład „karton” albo „paleta”. W polu **Etykiety opakowań** wpisz jedno przypisanie na wiersz w formacie `ilość=etykieta`:
```
12=Karton 12 szt.
48=Pół palety
96=Paleta
```
Etykieta wyświetla się pod ilością odpowiedniego progu. Pole jest tłumaczone: uzupełnij je w każdym języku z poziomu przełącznika języków w formularzu.
## Stan magazynowy, minimalna ilość i widoczność cen
Blok respektuje reguły sprzedaży PrestaShop:
- **Minimalna ilość zamówienia**: jeśli produkt sprzedawany jest wyłącznie po 6 sztuk, przycisk progu „za sztukę” dodaje 6 sztuk i wyświetla „Dodaj 6”.
- **Stan magazynowy**: gdy zarządzanie stanami jest włączone, a zamówienia przy braku towaru są odrzucane, przyciski progów, których ilość przekracza dostępny stan, są wyłączane z komunikatem „Niewystarczający stan magazynowy”.
- **Produkt niedostępny do zamówienia** (odznaczona opcja „Dostępny do zamówienia”, tryb katalogu): progi pozostają widoczne informacyjnie, bez przycisku dodania.
- **Ukryte ceny** (tryb katalogu bez cen, grupa klientów bez wyświetlania cen, odznaczona opcja „Pokaż cenę”): blok nie jest wyświetlany.
## Zachęta do wyższego progu
Dostępne są dwa mechanizmy zachęty, włączane niezależnie od siebie.
### Na stronie produktu
Pasek postępu wyświetla komunikat typu „Dodaj jeszcze 3 szt., aby zaoszczędzić 15%”, przeliczany w czasie rzeczywistym według wpisanej ilości. Gdy klient osiąga najkorzystniejszy próg, komunikat zmienia się na „Masz najwyższy rabat!”.
### Na stronie koszyka
Dla każdego produktu w koszyku, dla którego wyższy próg pozostaje osiągalny, moduł wyświetla pod koszykiem blok „Dodaj jeszcze N szt., aby płacić X € za sztukę” wraz z przyciskiem dodania jednym kliknięciem. Przycisk korzysta z natywnego mechanizmu aktualizacji koszyka PrestaShop, po czym odświeża stronę.
- Jeśli rabaty ilościowe są liczone per produkt (ustawienie PrestaShop _Rabaty ilościowe na podstawie: Produkty_), ilości wszystkich wariantów produktu są sumowane, tak jak robi to PrestaShop przy wyliczaniu ceny.
- Żadna propozycja nie jest wyświetlana, jeśli stan magazynowy nie pozwala osiągnąć progu, ani dla produktów gratisowych.
- Jeśli PrestaShop odrzuci dodanie (stan magazynowy, maksymalna ilość…), komunikat o błędzie wyświetla się bezpośrednio w bloku.
## Dane strukturalne (JSON-LD)
Gdy opcja jest włączona, moduł dodaje na stronie produktu znaczniki JSON-LD `Product` z ofertą `Offer`, której pole `priceSpecification` zawiera jeden `UnitPriceSpecification` na próg, z minimalną kwalifikującą ilością (`eligibleQuantity`) i informacją netto/brutto. To forma zalecana dla cen progowych oferowanych przez jednego sprzedawcę. Znaczniki obejmują też dostępność, zdjęcie główne i indeks (SKU).
Jeśli Twój szablon lub inny moduł SEO generuje już kompletne znaczniki `Product` / `Offer` dla produktów, wyłącz tę opcję, aby uniknąć zdublowanych znaczników zgłaszanych w Search Console.
## Statystyki kliknięć per próg
Gdy opcja jest włączona, każde kliknięcie przycisku dodania per próg jest rejestrowane anonimowo: produkt, wariant, ilość i rabat klikniętego progu. Nie są używane żadne dane osobowe ani pliki cookie, co czyni funkcję zgodną z RODO.
Próg jest ponownie weryfikowany po stronie serwera, a rabat przeliczany na podstawie Twoich rzeczywistych cen: danych nie da się sfałszować spreparowanymi żądaniami. Kliknięcia starsze niż rok są automatycznie usuwane, aby tabela pozostała lekka.
Strona konfiguracji wyświetla pulpit z ostatnich 30 dni: łączną liczbę kliknięć oraz ranking najczęściej klikanych kombinacji produkt / próg / rabat. Te dane pomagają skalibrować rabaty przez wskazanie progów, które faktycznie wywołują dodania do koszyka.
## Tłumaczenia
Teksty modułu są dostarczane po angielsku, francusku, niemiecku, włosku, hiszpańsku, niderlandzku, portugalsku i polsku. Dopasowują się automatycznie do języka odwiedzającego i panelu administracyjnego. Aby zmienić sformułowanie, przejdź do **Międzynarodowy > Tłumaczenia > Tłumaczenia zainstalowanych modułów** i wybierz _dfquantitytiers_.
Teksty wpisywane w konfiguracji (tytuł bloku, etykiety opakowań) uzupełnia się osobno dla każdego języka z poziomu przełącznika języków w formularzu.
## FAQ i rozwiązywanie problemów
### Blok nie wyświetla się na produkcie
Sprawdź, czy produkt ma ceny specyficzne z ilością początkową większą niż 1, czy te ceny obowiązują dla bieżącej grupy klienta, waluty i kraju oraz czy ceny są widoczne dla tego klienta (zobacz „Stan magazynowy, minimalna ilość i widoczność cen”).
### Teksty wyświetlają się po francusku w sklepie w innym języku
Używasz wersji starszej niż 1.2.0, w której teksty nie były przetłumaczone. Zainstaluj najnowszą wersję, a następnie wyczyść pamięć podręczną w **Zaawansowane > Wydajność**.
### Pola „Tytuł bloku” i „Etykiety opakowań” nie mają pola do wpisania tekstu
Ten błąd wyświetlania formularza konfiguracji został poprawiony w wersji 1.2.0. Po aktualizacji oba pola pojawiają się wraz z przełącznikiem języków.
### Wyświetlana suma lub oszczędność nie odpowiada zamówionej ilości
Od wersji 1.2.1 oszczędność jest podawana na sztuce i pozostaje poprawna dla każdej ilości w ramach progu. Cena całkowita jest prawdziwa tylko dla dokładnej ilości progu: wyłącz opcję **Pokaż cenę całkowitą progu**, jeśli nie chcesz jej wyświetlać.
### Przycisk dodania nie działa z moim szablonem
Moduł opiera się na standardowym przycisku dodania do koszyka szablonu Classic. W silnie zmodyfikowanym szablonie upewnij się, że pole ilości (`name="qty"`) i przycisk dodania (`data-button-action="add-to-cart"`) zachowują standardowy kod HTML PrestaShop.
### Blok nie pojawia się w szybkim podglądzie (quickview)
To celowe: okno szybkiego podglądu nie ładuje stylów modułu. Progi wyświetlają się na pełnej stronie produktu.
### Czy działa z wariantami?
Tak. Progi są przeliczane dla każdej kombinacji, a blok aktualizuje się automatycznie przy zmianie wariantu, bez przeładowania strony.
### Co dzieje się przy odinstalowaniu?
Odinstalowanie czysto usuwa hooki, zmienne konfiguracyjne i tabelę statystyk. W bazie nie pozostają żadne dane resztkowe.