Gift cards

Das Geschenkkarten-Modul ermöglicht Ihnen, Karten als WooCommerce-Produkte zu verkaufen. Der Kunde kauft eine Karte, erhält einen Code und bezahlt damit bei zukünftigen Bestellungen.

Funktionsweise

1. Der Administrator erstellt ein Produkt vom Typ “Geschenkkarte”
2. Der Kunde kauft eine Geschenkkarte im Shop
3. Nach Bezahlung der Bestellung generiert das Plugin einen eindeutigen Kartencode
4. Der Code wird per E-Mail an den Kunden (oder an den Beschenkten) gesendet
5. Der Beschenkte gibt den Code im Warenkorb ein und erhält einen Rabatt in Höhe des Kartenwerts
6. Das Kartenguthaben verringert sich um den verwendeten Betrag

Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski > PRO-Module > Geschenkkarten.

Das Modul wird über die folgende Option gesteuert:

polski_gift_cards

Allgemeine Einstellungen

Einstellung	Beschreibung
Geschenkkarten aktivieren	Aktiviert das Modul
Code-Länge	Anzahl der Zeichen im Code (Standard 16)
Code-Format	Code-Muster (z. B. XXXX-XXXX-XXXX-XXXX)
Code-Präfix	Optionales Präfix (z. B. PL-)
Gültigkeit der Karte	Anzahl der Gültigkeitstage (0 = keine Begrenzung)
Code-Feld im Warenkorb	Position des Eingabefelds für den Code

Erstellen eines Geschenkkarten-Produkts

1. Gehen Sie zu Produkte > Erstellen
2. Wählen Sie den Produkttyp: Geschenkkarte
3. Legen Sie den Preis fest (Nennwert der Karte)
4. Optional: Aktivieren Sie “Freier Betrag” - der Kunde gibt den Kartenwert selbst ein
5. Optional: Legen Sie einen Mindest- und Höchstbetrag für freie Beträge fest
6. Veröffentlichen Sie das Produkt

Bei freien Beträgen sieht der Kunde anstelle eines festen Preises ein Feld zur Eingabe des Kartenwerts.

Code-Generierung

Geschenkkarten-Codes werden automatisch nach Bezahlung der Bestellung generiert. Algorithmus:

• alphanumerische Zeichen (A-Z, 0-9)
• Ausschluss mehrdeutiger Zeichen (0, O, I, L, 1)
• Prüfung der Eindeutigkeit in der Datenbank
• Formatierung mit Trennzeichen (z. B. ABCD-EFGH-JKMN-PQRS)

Jeder Code ist im gesamten Shop eindeutig. Das Plugin prüft die Eindeutigkeit vor dem Speichern und generiert bei einer Kollision einen neuen Code.

Einlösung im Warenkorb

Code-Feld

Auf der Warenkorb-Seite (und optional auf der Kassen-Seite) wird ein Feld zur Eingabe des Geschenkkarten-Codes angezeigt:

[Wpisz kod karty podarunkowej] [Zastosuj]

Nach Eingabe eines gültigen Codes:

• wird das Kartenguthaben angezeigt
• wird der Rabattbetrag von der Bestellsumme abgezogen
• wenn das Kartenguthaben geringer ist als der Bestellwert - wird der Restbetrag mit anderen Methoden bezahlt
• wenn das Kartenguthaben höher ist - verbleibt der Restbetrag auf der Karte

Code-Validierung

Das Plugin validiert den Kartencode vor der Anwendung:

• prüft, ob der Code in der Datenbank vorhanden ist
• prüft, ob die Karte nicht abgelaufen ist
• prüft, ob das Guthaben größer als null ist
• prüft, ob die Karte nicht gesperrt wurde

Die Fehlermeldung informiert den Kunden über den Grund der Ablehnung des Codes.

Sitzungsverfolgung

Der angewendete Kartencode wird in der WooCommerce-Sitzung des Kunden gespeichert. Das bedeutet:

• der Code wird auch nach dem Aktualisieren der Seite gespeichert
• der Code wird nach dem Aufgeben einer Bestellung oder dem Abmelden entfernt
• der Kunde kann den angewendeten Code manuell entfernen

Guthabenverfolgung

Jede Geschenkkarte hat ein Guthaben, das sich mit jeder Verwendung verringert. Der Transaktionsverlauf der Karte enthält:

Feld	Beschreibung
Datum	Datum der Transaktion
Typ	Aufladung / Verwendung / Rückerstattung
Betrag	Betrag der Operation
Bestellung	Bestell-ID (bei Verwendung und Rückerstattung)
Guthaben nach Operation	Aktuelles Guthaben nach der Transaktion

Admin-Bereich

Im Bereich WooCommerce > Geschenkkarten kann der Administrator:

• die Liste aller Karten mit Guthaben durchsuchen
• den Transaktionsverlauf einer Karte prüfen
• eine Karte manuell aufladen
• eine Karte sperren
• die Kartenliste exportieren (CSV)

Bereich Mein Konto

Das Modul fügt dem Bereich Mein Konto des Kunden einen Endpunkt /polski-gift-cards hinzu. Der Endpunkt ist verfügbar unter:

/moje-konto/polski-gift-cards/

Im Bereich kann der Kunde einsehen:

• Liste der eigenen Geschenkkarten
• aktuelles Guthaben jeder Karte
• Nutzungsverlauf
• Kartencode (mit Kopieroption)
• Ablaufdatum (falls festgelegt)

Hooks

polski_pro/gift_card/validate

Filtert das Ergebnis der Validierung des Geschenkkarten-Codes im Warenkorb.

/**
 * @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;

Beispiel:

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

Aktion, die nach der Anwendung einer Geschenkkarte im Warenkorb ausgelöst wird.

/**
 * @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);

Beispiel:

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

Aktion, die nach der Erstellung einer Bestellung unter Verwendung einer Geschenkkarte ausgelöst wird.

/**
 * @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);

Beispiel:

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

Filtert den von der Geschenkkarte abzuziehenden Betrag beim Neuberechnen der Warenkorbsummen.

/**
 * @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 mit Code

Nachdem eine Bestellung mit einer Geschenkkarte bezahlt wurde, sendet das Plugin eine E-Mail mit dem Code. Die E-Mail enthält:

• formatierten Kartencode
• Nennwert
• Ablaufdatum (falls zutreffend)
• Nutzungshinweise

Die E-Mail-Vorlage kann unter WooCommerce > Einstellungen > E-Mails > Geschenkkarte angepasst werden.

E-Mail für den Beschenkten

Beim Kauf einer Karte kann der Kunde die E-Mail-Adresse des Beschenkten angeben. In diesem Fall:

• wird der Code an die Adresse des Beschenkten gesendet
• erhält der Käufer eine Kaufbestätigung (ohne den Code)
• optional: der Käufer kann eine Nachricht für den Beschenkten hinzufügen

Häufige Probleme

Code wird im Warenkorb nicht akzeptiert

1. Prüfen Sie, ob der Code korrekt eingegeben wurde (keine Leerzeichen am Anfang/Ende)
2. Überprüfen Sie, ob die Karte nicht abgelaufen ist
3. Prüfen Sie das Kartenguthaben im Admin-Bereich
4. Stellen Sie sicher, dass die Karte nicht gesperrt ist

Kunde hat den Code nicht per E-Mail erhalten

1. Prüfen Sie, ob die Bestellung bezahlt ist (Status “In Bearbeitung” oder “Abgeschlossen”)
2. Überprüfen Sie die WooCommerce-E-Mail-Konfiguration
3. Prüfen Sie die E-Mail-Protokolle auf Versandfehler

Guthaben verringert sich nach einer Bestellung nicht

1. Prüfen Sie, ob die Bestellung erfolgreich aufgegeben wurde (nicht storniert)
2. Überprüfen Sie den Transaktionsverlauf der Karte im Admin-Bereich
3. Prüfen Sie die Protokolle auf PHP-Fehler

Verwandte Ressourcen

• PRO-Übersicht
• Ein Problem melden

Diese Seite dient ausschließlich Informationszwecken und stellt keine Rechtsberatung dar. Konsultieren Sie vor der Umsetzung einen Anwalt. Polski for WooCommerce ist Open-Source-Software (GPLv2), die ohne Gewährleistung bereitgestellt wird.