Shipping Cost by Zip Code — Koszty wysyłki według kodu pocztowego

Shipping Cost by Zip Code to moduł PrestaShop, który pozwala naliczać dokładne koszty wysyłki na podstawie kodu pocztowego klienta. Tworzysz własne strefy pocztowe (bez limitu), przypisujesz kody pocztowe (pojedyncze lub w formie zakresów liczbowych), a następnie definiujesz cenniki dla przewoźników z użyciem progów wagowych lub progów wartości koszyka.

W przeciwieństwie do natywnego podejścia (strefy/kraje), to rozwiązanie jest idealne, gdy koszty różnią się znacząco między centrum miasta, obszarami wiejskimi, wyspami, terenami górskimi czy terytoriami zamorskimi. Moduł nie dodaje przewoźników — dostosowuje stawki Twoich istniejących przewoźników w checkout, zgodnie z kodem pocztowym.

Najważniejsze zalety:

• Nielimitowane strefy pocztowe (pojedyncze kody i zakresy liczbowe)
• Cenniki per przewoźnik + nielimitowane progi (waga lub wartość koszyka)
• Darmowa dostawa (per próg, per strefa lub od kwoty)
• Import / eksport CSV do konfiguracji masowej
• System priorytetów przy nakładających się strefach
• Multistore, wielojęzyczność, brak override’ów

---

Opis

Domyślnie PrestaShop oblicza koszty wysyłki na podstawie stref geograficznych i krajów, co często bywa zbyt mało precyzyjne. Sklep może potrzebować różnych stawek w zależności od odległości, dostępności lub realnych kosztów przewozu, nawet w obrębie jednego kraju.

Dzięki Shipping Cost by Zip Code konfigurujesz reguły na poziomie kodu pocztowego:

1. Tworzysz strefę pocztową (np. „Centrum miasta”, „Strefa górska”, „Wyspy/terytoria”).
2. Dodajesz kody pocztowe (lista) lub zakresy (np. 75001 → 75020).
3. Ustawiasz cennik dla przewoźników z logiką wg wagi lub wg wartości koszyka.

Jeśli żaden kod nie pasuje do strefy, zachowanie jest konfigurowalne: zastosować standardowe stawki PrestaShop lub zablokować wysyłkę (przewoźnicy ukryci).

---

Funkcje

Strefy dostawy wg kodów pocztowych

• Tworzenie nielimitowanej liczby stref pocztowych
• Format kodów pocztowych:
  • Pojedyncze kody (jeden kod lub lista)
  • Zakresy liczbowe (np. 75001–75020)
• Możliwość użycia wielu krajów w jednej strefie
• Włączanie/wyłączanie stref
• Opcja „Wysyłka wyłączona”: ukrywa przewoźników w checkout dla danej strefy
• System priorytetów do obsługi nakładających się stref

Zaawansowana wycena dla przewoźników

• Stawki per przewoźnik i per strefa
• Tryb obliczeń:
  • Waga (kg)
  • Cena (wartość koszyka)
• Nielimitowane progi (0–5, 5–10 itd.)
• Opłaty stałe lub procentowe
• Darmowa dostawa:
  • per próg
  • per strefa / przewoźnik
  • automatycznie od ustawionej kwoty koszyka
• Opcja „Wszyscy przewoźnicy”: zastosuj regułę do wszystkich przewoźników naraz

Wygoda w back office

• Interfejs w back office w sekcji Wysyłka
• Lista stref z wyszukiwaniem / filtrami / sortowaniem oraz pozycjonowaniem (drag & drop)
• Edytor „all-in-one”: ustawienia ogólne + kody + cenniki na jednej stronie
• Import CSV z raportem błędów
• Eksport CSV pełnej konfiguracji
• Przykładowy plik CSV w zestawie

Podejście techniczne

• Zgodność z PrestaShop 1.7.7, 8.x i 9.x
• Obsługa multistore
• Obsługa wielojęzyczna (tłumaczalne nazwy stref)
• Brak override’ów core PrestaShop
• Wykorzystanie id_carrier_reference (odporne na zmiany przewoźników)
• Zoptymalizowane zapytania + cache w pamięci (dopasowanie kod → strefa)

---

Wymagania

• PrestaShop: minimum 1.7.7.0 (zgodność 1.7.7 → 9.x)

Ważne ograniczenie: obsługiwane są wyłącznie kody pocztowe numeryczne. Kraje z kodami alfanumerycznymi (np. Wielka Brytania, Kanada, Holandia) nie są wspierane.

---

Instalacja

Metoda 1 — przez Back Office (zalecana)

1. Przejdź do Moduły > Menedżer modułów
2. Kliknij Wgraj moduł
3. Wybierz wepresta_shipping_cost_by_zip.zip
4. Poczekaj na zakończenie instalacji
5. Kliknij Konfiguruj

Metoda 2 — przez FTP

1. Rozpakuj archiwum
2. Wgraj folder wepresta_shipping_cost_by_zip/ do /modules/
3. W back office: Moduły > Menedżer modułów
4. Znajdź moduł i kliknij Zainstaluj
5. Kliknij Konfiguruj

Co robi instalacja

• Tworzy 4 tabele: wep_zip_zone, wep_zip_zone_lang, wep_zip_range, wep_zip_delivery
• Rejestruje wymagane hooki
• Dodaje zakładkę „Shipping by Zip Code” w sekcji Wysyłka
• Inicjalizuje konfigurację domyślną

Uwaga: moduł nie tworzy przewoźników. Modyfikuje koszty istniejących przewoźników na podstawie kodu pocztowego.

---

Konfiguracja

Dostęp:

• Moduły > Menedżer modułów > Konfiguruj
• lub Wysyłka > Shipping by Zip Code

Ustawienia globalne

• Włącz moduł: aktywuje/dezaktywuje kalkulację wg kodu pocztowego
• Zachowanie domyślne (gdy brak dopasowania strefy):
  • Użyj stawek standardowych: PrestaShop stosuje stawki natywne (zalecane na start)
  • Zablokuj wysyłkę: przewoźnicy nie pojawią się w checkout

---

Zarządzanie strefami

Dostęp: Wysyłka > Shipping by Zip Code

Utwórz strefę

1. Kliknij Dodaj nową strefę
2. Uzupełnij:
   • Nazwa strefy (wielojęzyczna)
   • Aktywna (Tak/Nie)
   • Wysyłka wyłączona (Tak/Nie)
3. Kliknij Zapisz

Dodaj kody pocztowe

W edytorze strefy, sekcja Kody pocztowe:

1. Wybierz kraj
2. Dodaj:
   • Listę kodów (oddzielone przecinkami):
     • 75001, 75002, 75003
   • lub zakres:
     • od 75001 do 75020
3. Kliknij + Dodaj

Obsługiwane są tylko kody numeryczne.

Skonfiguruj przewoźników i ceny

W sekcji Przewoźnicy i cenniki:

1. Wybierz przewoźnika (lub Wszyscy przewoźnicy)
2. Wybierz typ:
   • Waga (kg) lub Cena (wartość koszyka)
3. Ustaw próg:
   • min / max
4. Wpisz opłatę
5. Opcje:
   • Procent (jeśli włączone, opłata jest % koszyka)
   • Darmowa dostawa
   • Za darmo od (próg kwoty koszyka)
6. Kliknij + Dodaj regułę cenową

---

Import / eksport CSV

Format CSV

• Separator: średnik ;
• Kodowanie: UTF-8

Główne kolumny:

• zone_name (wymagane)
• country_iso (wymagane)
• postal_code_from (wymagane)
• postal_code_to (opcjonalnie: puste = pojedynczy kod)
• carrier_reference (wymagane)
• calculation_type: weight / price (wymagane)
• range_from, range_to, price (wymagane)
• is_percentage, is_free, free_from_amount (opcjonalnie)

Import

1. Wysyłka > Shipping by Zip Code
2. Importuj CSV
3. Wybierz plik
4. Importuj i sprawdź raport (OK / zaktualizowane / błędy)

Przydatne zachowania:

• Istniejąca strefa o tej samej nazwie jest ponownie używana (bez duplikatów)
• Istniejące zakresy nie są duplikowane
• Identyczna reguła cenowa jest aktualizowana

Eksport

• Kliknij Eksportuj CSV
• Plik pobierany ma ten sam format co import

---

System priorytetów

Każda strefa ma pozycję (sortowalną). Jeśli kod pocztowy pasuje do wielu stref, używana jest strefa z najniższą pozycją.

Kolejność dopasowania:

1. Dopasowanie dokładne (pojedynczy kod)
2. Dopasowanie zakresowe
3. Jeśli jest wiele dopasowań, decyduje pozycja strefy

---

Multistore

Moduł wspiera multistore:

• Strefy i cenniki są widoczne zależnie od kontekstu (wszystkie sklepy / grupa / sklep)
• Strefa jest przypisana do aktywnego kontekstu sklepu w momencie tworzenia
• Aby zastosować identyczną konfigurację w wielu sklepach: eksport/import CSV

---

Działanie po stronie klienta

W checkout moduł działa w tle:

1. Klient wpisuje adres (z kodem pocztowym)
2. PrestaShop wyświetla przewoźników
3. Moduł dostosowuje koszty zgodnie z dopasowaną strefą

Klient zobaczy:

• koszty dopasowane do kodu pocztowego
• potencjalnie mniej przewoźników, jeśli strefa jest „niedostarczalna”
• darmową dostawę, jeśli skonfigurowano

---

Typowe scenariusze

Terytoria zamorskie / wyspy / obszary odległe

Utwórz osobną strefę (np. 97100 → 97490) z wyższymi stawkami niż obszar główny.

Darmowa dostawa lokalna

Utwórz strefę „lokalną” (pobliskie kody) z darmową dostawą, zachowując standardowe stawki dla reszty.

Blokada dostawy w obszarach nieobsługiwanych

Utwórz strefę „niedostarczalną” i włącz Wysyłka wyłączona, aby ukryć przewoźników.

Stawki procentowe

Przydatne dla koszyków o wysokiej wartości: np. 3% wartości koszyka, a potem za darmo od progu.

---

FAQ

Czy moduł tworzy przewoźników?

Nie. Korzysta z istniejących przewoźników i modyfikuje kalkulację kosztów na podstawie kodu pocztowego.

Co jeśli żadna strefa nie pasuje?

Zależnie od ustawień globalnych:

• PrestaShop zastosuje stawki standardowe
• albo wysyłka zostanie zablokowana (przewoźnicy ukryci)

Czy obsługuje alfanumeryczne kody (UK, CA)?

Nie, tylko kody numeryczne.

Czy zadziała z One Page Checkout?

Tak. Koszt jest liczony po stronie serwera przez getOrderShippingCost(), zgodne z checkout standardowym i OPC.

---

Rozwiązywanie problemów

Moduł nie jest widoczny w menu Wysyłka

• Sprawdź, czy jest zainstalowany i włączony
• Wyczyść cache: Parametry zaawansowane > Wydajność > Wyczyść cache
• Sprawdź uprawnienia pracowników

Koszty nie zmieniają się w checkout

• Moduł włączony?
• Czy istnieje aktywna strefa pasująca do kodu?
• Czy są reguły cenowe dla tej strefy i przewoźnika?
• Czy progi obejmują wagę/wartość koszyka?
• Cache wyczyszczony?

Przewoźnik znika w checkout

• Strefa ma włączone Wysyłka wyłączona
• Zachowanie domyślne = Zablokuj wysyłkę i brak dopasowania strefy
• Brak reguły cenowej dla tego przewoźnika w dopasowanej strefie

Changelog

Wersja 1.0.0

• Nielimitowane strefy pocztowe
• Pojedyncze kody + zakresy liczbowe
• Cenniki wg wagi lub wartości koszyka
• Procent od wartości koszyka
• Darmowa dostawa (per próg / próg kwoty)
• Blokada wysyłki per strefa
• Priorytety stref
• Import / eksport CSV
• Multistore + wielojęzyczność
• Zgodność PrestaShop 1.7.7 → 9.x

---

Wsparcie

• Wsparcie przez stronę modułu (PrestaShop Addons) lub panel klienta WePresta
• Typowy czas odpowiedzi: 24–48 godzin roboczych

Przed kontaktem przygotuj:

• wersję PrestaShop
• wersję PHP
• jasny opis problemu
• zrzuty ekranu
• logi PrestaShop (jeśli dostępne)

---

Licencja

Academic Free License (AFL 3.0).
Copyright © WePresta. Wszelkie prawa zastrzeżone.