Подарункові картки

Модуль подарункових карток дозволяє продавати картки як продукти WooCommerce. Клієнт купує картку, отримує код та оплачує ним наступні замовлення.

Як це працює

1. Адміністратор створює продукт типу “Подарункова картка”
2. Клієнт купує подарункову картку в магазині
3. Після оплати замовлення плагін генерує унікальний код картки
4. Код надсилається клієнту (або отримувачу подарунка) електронною поштою
5. Отримувач вводить код у кошику та отримує знижку, рівну вартості картки
6. Баланс картки зменшується на використану суму

Налаштування

Перейдіть до WooCommerce > Налаштування > Polski > Модулі PRO > Подарункові картки.

Модуль контролюється опцією:

polski_gift_cards

Загальні налаштування

Параметр	Опис
Увімкнути подарункові картки	Активує модуль
Довжина коду	Кількість символів коду (за замовчуванням 16)
Формат коду	Шаблон коду (наприклад, XXXX-XXXX-XXXX-XXXX)
Префікс коду	Необов’язковий префікс (наприклад, PL-)
Термін дії картки	Кількість днів дії (0 = без обмеження)
Поле коду в кошику	Позиція поля для введення коду

Створення продукту подарункової картки

1. Перейдіть до Продукти > Додати новий
2. Виберіть тип продукту: Подарункова картка
3. Встановіть ціну (номінальна вартість картки)
4. Необов’язково: увімкніть “Довільна сума” - клієнт сам вводить вартість картки
5. Необов’язково: встановіть мінімальну та максимальну суму для довільної суми
6. Опублікуйте продукт

Для довільної суми клієнт бачить поле для введення вартості картки замість фіксованої ціни.

Генерація кодів

Коди подарункових карток генеруються автоматично після оплати замовлення. Алгоритм:

• алфавітно-цифрові символи (A-Z, 0-9)
• виключення неоднозначних символів (0, O, I, L, 1)
• валідація унікальності в базі даних
• форматування з роздільниками (наприклад, ABCD-EFGH-JKMN-PQRS)

Кожний код унікальний у межах усього магазину. Плагін перевіряє унікальність перед збереженням і в разі колізії генерує новий код.

Реалізація в кошику

Поле коду

На сторінці кошика (і необов’язково на сторінці каси) відображається поле для введення коду подарункової картки:

[Введіть код подарункової картки] [Застосувати]

Після введення правильного коду:

• відображається баланс картки
• сума знижки віднімається від суми замовлення
• якщо баланс картки менший за вартість замовлення - решта оплачується іншими способами
• якщо баланс картки більший - залишок залишається на картці

Валідація коду

Плагін валідує код картки перед застосуванням:

• перевірка, чи код існує в базі
• перевірка, чи картка не прострочена
• перевірка, чи баланс більший за нуль
• перевірка, чи картка не заблокована

Повідомлення про помилку інформує клієнта про причину відхилення коду.

Відстеження сесії

Застосований код картки зберігається в сесії WooCommerce клієнта. Це означає, що:

• код запам’ятовується навіть після оновлення сторінки
• код видаляється після оформлення замовлення або виходу з облікового запису
• клієнт може видалити застосований код вручну

Відстеження балансу

Кожна подарункова картка має баланс, який зменшується з кожним використанням. Історія транзакцій картки містить:

Поле	Опис
Дата	Дата транзакції
Тип	Поповнення / Використання / Повернення
Сума	Сума операції
Замовлення	ID замовлення (для використання та повернення)
Баланс після операції	Поточний баланс після транзакції

Адміністративна панель

У панелі WooCommerce > Подарункові картки адміністратор може:

• переглядати список усіх карток із балансами
• перевіряти історію транзакцій картки
• поповнювати картку вручну
• блокувати картку
• експортувати список карток (CSV)

Панель Мій обліковий запис

Модуль додає ендпоінт /polski-gift-cards до панелі Мій обліковий запис клієнта. Ендпоінт доступний за адресою:

/moje-konto/polski-gift-cards/

У панелі клієнт бачить:

• список власних подарункових карток
• поточний баланс кожної картки
• історію використання
• код картки (з можливістю копіювання)
• дату закінчення терміну дії (якщо встановлена)

Хуки

polski_pro/gift_card/validate

Фільтрує результат валідації коду подарункової картки в кошику.

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

Приклад:

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

Дія, що викликається після застосування подарункової картки в кошику.

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

Приклад:

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

Дія, що викликається після створення замовлення з використанням подарункової картки.

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

Приклад:

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

Фільтрує суму для відрахування з подарункової картки при перерахунку сум кошика.

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

Електронний лист із кодом

Після оплати замовлення, що містить подарункову картку, плагін надсилає електронний лист із кодом. Лист містить:

• код картки (відформатований)
• номінальну вартість
• дату закінчення терміну дії (якщо застосовується)
• інструкцію використання

Шаблон листа можна налаштувати в WooCommerce > Налаштування > Електронні листи > Подарункова картка.

Електронний лист для отримувача подарунка

При покупці картки клієнт може вказати адресу електронної пошти отримувача подарунка. У такому випадку:

• код надсилається на адресу отримувача
• покупець отримує підтвердження покупки (без коду)
• необов’язково: покупець може додати повідомлення для отримувача

Найпоширеніші проблеми

Код не приймається в кошику

1. Перевірте, чи код введений правильно (без пробілів на початку/кінці)
2. Перевірте, чи картка не прострочена
3. Перевірте баланс картки в адміністративній панелі
4. Переконайтеся, що картка не заблокована

Клієнт не отримав код електронною поштою

1. Перевірте, чи замовлення оплачене (статус “Processing” або “Completed”)
2. Перевірте конфігурацію електронних листів WooCommerce
3. Перевірте логи листів на наявність помилок надсилання

Баланс не зменшується після замовлення

1. Перевірте, чи замовлення було успішно оформлене (не скасоване)
2. Перевірте історію транзакцій картки в адміністративній панелі
3. Перевірте логи на наявність помилок PHP

Пов’язані ресурси

• Огляд PRO
• Повідомити про проблему

Ця сторінка має виключно інформаційний характер і не є юридичною консультацією. Перед впровадженням зверніться до юриста. Polski for WooCommerce - це програмне забезпечення з відкритим кодом (GPLv2), що надається без гарантій.