Karty podarunkowe

Moduł kart podarunkowych pozwala sprzedawać karty jako produkty WooCommerce. Klient kupuje kartę, otrzymuje kod i płaci nim przy kolejnych zamówieniach.

Jak to działa

1. Administrator oznacza zwykły produkt jako kartę podarunkową na zakładce Polski Pro w edytorze produktu
2. Klient kupuje kartę podarunkową w sklepie
3. Po opłaceniu zamówienia plugin generuje unikalny kod karty
4. Kod jest wysyłany do klienta (lub obdarowanego) e-mailem
5. Obdarowany wpisuje kod w koszyku i otrzymuje rabat równy wartości karty
6. Saldo karty zmniejsza się o wykorzystaną kwotę

Konfiguracja

Od Polski PRO 1.22.0 karty podarunkowe mają własny wiersz na ekranie Polski > Moduły (klucz modułu gift_cards). Tam włączasz moduł i tam ustawiasz wartości dla całego sklepu; zapis wiersza wpisuje je do opcji polski_gift_cards. Moduł jest domyślnie wyłączony.

Wiersz nie wystawia każdego klucza, który moduł czyta. Brakujące nadal można ustawić bezpośrednio na opcji, na przykład przez WP-CLI:

wp option patch update polski_gift_cards expiry_days 180

Wartości per produkt (czy produkt w ogóle jest kartą podarunkową, jego kwoty i granice kwoty dowolnej) są na zakładce Polski Pro w edytorze produktu, zobacz Ustawienia per produkt.

Ustawienia czytane przez moduł

Klucz	Domyślnie	Opis
show_on_single	true	Pokaż pola karty na stronie produktu
allow_custom_amount	true	Pozwól kupującemu wpisać własną kwotę
min_amount / max_amount	20 / 1000	Granice kwoty dowolnej
default_amounts	50,100,200	Kwoty proponowane na stronie produktu
code_prefix	SP	Prefiks generowanego kodu
expiry_days	365	Liczba dni ważności karty
show_in_account / account_label	true / Karty podarunkowe	Sekcja w Moim koncie z saldami kart
email_subject / email_heading	patrz kod	Treść e-maila z kartą
date_format	d.m.Y	Format daty w treściach dla klienta

Każda etykieta i każdy komunikat mają własny klucz (recipient_name_label, invalid_code_text, applied_code_text i tak dalej). Wartości domyślne są w Polski\Pro\Service\GiftCardService.

Tworzenie produktu karty podarunkowej

Nie ma typu produktu “Karta podarunkowa”. Karta podarunkowa to zwykły produkt z ustawionym na nim meta karty, a od Polski PRO 1.26.0 zapisuje je zakładka Polski Pro w polu danych produktu:

1. Przejdź do Produkty > Dodaj nowy i zbuduj zwykły produkt.
2. Ustaw cenę (wartość nominalna karty).
3. Otwórz zakładkę Polski Pro w polu Dane produktu i zaznacz Sell as a gift card. Zapisuje to _polski_gift_card_enabled, czyli klucz, na którym bramkuje się moduł.
4. Opcjonalnie ustaw kwoty do wyboru, zgodę na kwotę dowolną i jej granice.
5. Opublikuj produkt.

Wszystkie pola tej zakładki, klucze meta pod nimi i to, jak granice kwoty dowolnej cofają się do globalnych, opisuje Ustawienia per produkt.

Dla kwoty dowolnej klient widzi pole do wpisania wartości karty zamiast ustalonej ceny.

Generowanie kodów

Kody generują się automatycznie po opłaceniu zamówienia. Cechy kodów:

• znaki alfanumeryczne (A-Z, 0-9)
• wykluczenie znaków niejednoznacznych (0, O, I, L, 1)
• walidacja unikalności w bazie danych
• formatowanie z separatorami (np. ABCD-EFGH-JKMN-PQRS)

Każdy kod jest unikalny. Przy kolizji plugin generuje nowy kod.

Realizacja w koszyku

Pole kodu

W koszyku (i opcjonalnie na kasie) klient widzi pole do wpisania kodu:

[Wpisz kod karty podarunkowej] [Zastosuj]

Po wpisaniu prawidłowego kodu:

• saldo karty jest wyświetlane
• kwota rabatu jest odejmowana od sumy zamówienia
• jeśli saldo karty jest mniejsze niż wartość zamówienia - reszta do zapłaty innymi metodami
• jeśli saldo karty jest większe - pozostała kwota zostaje na karcie

Walidacja kodu

Plugin sprawdza kod przed zastosowaniem:

• sprawdzenie, czy kod istnieje w bazie
• sprawdzenie, czy karta nie wygasła
• sprawdzenie, czy saldo jest większe od zera
• sprawdzenie, czy karta nie została zablokowana

Klient widzi komunikat z przyczyną odrzucenia kodu.

Śledzenie sesji

Kod karty jest przechowywany w sesji WooCommerce:

• kod jest zapamiętywany nawet po odświeżeniu strony
• kod jest usuwany po złożeniu zamówienia lub wylogowaniu
• klient może usunąć zastosowany kod ręcznie

Śledzenie salda

Saldo karty zmniejsza się z każdym użyciem. Historia transakcji zawiera:

Pole	Opis
Data	Data transakcji
Typ	Doładowanie / Użycie / Zwrot
Kwota	Kwota operacji
Zamówienie	ID zamówienia (dla użycia i zwrotu)
Saldo po operacji	Aktualne saldo po transakcji

Panel administracyjny

W panelu WooCommerce > Karty podarunkowe administrator może:

• przeglądać listę wszystkich kart z saldami
• sprawdzić historię transakcji karty
• doładować kartę ręcznie
• zablokować kartę
• wyeksportować listę kart (CSV)

Panel Moje konto

Moduł dodaje sekcję w panelu Moje konto pod adresem:

/moje-konto/polski-gift-cards/

W panelu klient widzi:

• listę posiadanych kart podarunkowych
• aktualne saldo każdej karty
• historię użycia
• kod karty (z opcją kopiowania)
• datę ważności (jeśli ustawiona)

Hooki

polski_pro/gift_card/validate

Filtruje wynik walidacji kodu karty podarunkowej w koszyku.

/**
 * @param bool   $is_valid  Czy kod jest prawidłowy
 * @param string $code      Kod karty podarunkowej
 * @param float  $cart_total Suma koszyka
 */
apply_filters('polski_pro/gift_card/validate', bool $is_valid, string $code, float $cart_total): bool;

Przykład:

add_filter('polski_pro/gift_card/validate', function (bool $is_valid, string $code, float $cart_total): bool {
    // Blokowanie kart podarunkowych dla zamówień poniżej 50 zł
    if ($cart_total < 50.00) {
        wc_add_notice('Karty podarunkowe można wykorzystać przy zamówieniach od 50 zł.', 'error');
        return false;
    }
    return $is_valid;
}, 10, 3);

polski_pro/gift_card/applied

Akcja wywoływana po zastosowaniu karty podarunkowej w koszyku.

/**
 * @param string $code    Kod karty
 * @param float  $amount  Kwota do odliczenia
 * @param float  $balance Pozostałe saldo
 */
do_action('polski_pro/gift_card/applied', string $code, float $amount, float $balance);

Przykład:

add_action('polski_pro/gift_card/applied', function (string $code, float $amount, float $balance): void {
    // Logowanie użycia karty
    wc_get_logger()->info(
        "Karta {$code}: odliczono {$amount} zł, saldo: {$balance} zł",
        ['source' => 'polski-pro-gift-cards']
    );
}, 10, 3);

polski_pro/gift_card/order_created

Akcja wywoływana po utworzeniu zamówienia z użyciem karty podarunkowej.

/**
 * @param int    $order_id ID zamówienia
 * @param string $code     Kod karty
 * @param float  $amount   Kwota odliczona z karty
 */
do_action('polski_pro/gift_card/order_created', int $order_id, string $code, float $amount);

Przykład:

add_action('polski_pro/gift_card/order_created', function (int $order_id, string $code, float $amount): void {
    $order = wc_get_order($order_id);
    $order->add_order_note(
        sprintf('Użyto kartę podarunkową %s na kwotę %.2f zł', $code, $amount)
    );
}, 10, 3);

polski_pro/gift_card/calculate_totals

Filtruje kwotę do odliczenia z karty podarunkowej przy przeliczaniu sum koszyka.

/**
 * @param float  $discount   Kwota rabatu z karty
 * @param string $code       Kod karty
 * @param float  $cart_total Suma koszyka przed rabatem
 */
apply_filters('polski_pro/gift_card/calculate_totals', float $discount, string $code, float $cart_total): float;

E-mail z kodem

Po opłaceniu zamówienia plugin wysyła e-mail z kodem karty. E-mail zawiera:

• kod karty (sformatowany)
• wartość nominalną
• datę ważności (jeśli dotyczy)
• instrukcję wykorzystania

Szablon e-maila można dostosować w WooCommerce > Ustawienia > E-maile > Karta podarunkowa.

E-mail dla obdarowanego

Klient może podać e-mail obdarowanego. Wtedy:

• kod jest wysyłany na adres obdarowanego
• kupujący otrzymuje potwierdzenie zakupu (bez kodu)
• opcjonalnie: kupujący może dodać wiadomość dla obdarowanego

Najczęstsze problemy

Kod nie jest akceptowany w koszyku

1. Sprawdź, czy kod jest wpisany prawidłowo (bez spacji na początku/końcu)
2. Zweryfikuj, czy karta nie wygasła
3. Sprawdź saldo karty w panelu administracyjnym
4. Upewnij się, że karta nie jest zablokowana

Klient nie otrzymał kodu e-mailem

1. Sprawdź, czy zamówienie jest opłacone (status “Processing” lub “Completed”)
2. Zweryfikuj konfigurację e-maili WooCommerce
3. Sprawdź logi e-maili pod kątem błędów wysyłki

Saldo nie zmniejsza się po zamówieniu

1. Sprawdź, czy zamówienie zostało pomyślnie złożone (nie anulowane)
2. Zweryfikuj historię transakcji karty w panelu administracyjnym
3. Sprawdź logi pod kątem błędów PHP

Powiązane zasoby

• Przegląd PRO
• Zgłoś problem

Ta strona ma wyłącznie charakter informacyjny i nie stanowi porady prawnej. Przed wdrożeniem skonsultuj się z prawnikiem. Polski for WooCommerce jest oprogramowaniem open source (GPLv2) dostarczanym bez gwarancji.