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

Модуль подарункових карток дозволяє продавати картки як продукти 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)

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

Модуль додає секцію в панелі Мій обліковий запис за адресою:

/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 > Налаштування > Листи > Подарункова картка.

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

Клієнт може вказати email отримувача подарунка. Тоді:

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

Найчастіші проблеми

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

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

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

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

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

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

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

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

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