Gift cards

El módulo de tarjetas regalo le permite vender tarjetas como productos de WooCommerce. El cliente compra una tarjeta, recibe un código y paga con él en pedidos futuros.

Cómo funciona

El administrador crea un producto de tipo “Tarjeta regalo”
El cliente compra una tarjeta regalo en la tienda
Tras el pago del pedido, el plugin genera un código de tarjeta único
El código se envía por correo electrónico al cliente (o al destinatario)
El destinatario introduce el código en el carrito y recibe un descuento igual al valor de la tarjeta
El saldo de la tarjeta se reduce por el importe utilizado

Configuración

Vaya a WooCommerce > Ajustes > Polski > Módulos PRO > Tarjetas regalo.

El módulo se controla mediante la opción:

polski_gift_cards

Ajustes generales

Ajuste	Descripción
Activar tarjetas regalo	Activa el módulo
Longitud del código	Número de caracteres del código (por defecto 16)
Formato del código	Patrón del código (p. ej. `XXXX-XXXX-XXXX-XXXX`)
Prefijo del código	Prefijo opcional (p. ej. `PL-`)
Validez de la tarjeta	Número de días de validez (0 = sin límite)
Campo del código en el carrito	Posición del campo de entrada del código

Creación de un producto de tarjeta regalo

Vaya a Productos > Añadir nuevo
Seleccione el tipo de producto: Tarjeta regalo
Establezca el precio (valor nominal de la tarjeta)
Opcionalmente: active “Importe personalizado” - el cliente introduce él mismo el valor de la tarjeta
Opcionalmente: establezca un importe mínimo y máximo para los importes personalizados
Publique el producto

Para importes personalizados, el cliente ve un campo para introducir el valor de la tarjeta en lugar de un precio fijo.

Generación de códigos

Los códigos de las tarjetas regalo se generan automáticamente tras el pago del pedido. Algoritmo:

caracteres alfanuméricos (A-Z, 0-9)
exclusión de caracteres ambiguos (0, O, I, L, 1)
validación de unicidad en la base de datos
formateo con separadores (p. ej. ABCD-EFGH-JKMN-PQRS)

Cada código es único en toda la tienda. El plugin verifica la unicidad antes de guardar y genera un nuevo código en caso de colisión.

Canje en el carrito

Campo del código

En la página del carrito (y opcionalmente en la página de pago) se muestra un campo para introducir el código de la tarjeta regalo:

[Wpisz kod karty podarunkowej] [Zastosuj]

Tras introducir un código válido:

se muestra el saldo de la tarjeta
el importe del descuento se resta del total del pedido
si el saldo de la tarjeta es menor que el valor del pedido - el resto se paga con otros métodos
si el saldo de la tarjeta es mayor - el importe restante permanece en la tarjeta

Validación del código

El plugin valida el código de la tarjeta antes de aplicarlo:

comprueba si el código existe en la base de datos
comprueba si la tarjeta no ha caducado
comprueba si el saldo es mayor que cero
comprueba si la tarjeta no ha sido bloqueada

El mensaje de error informa al cliente sobre el motivo del rechazo del código.

Seguimiento de la sesión

El código de tarjeta aplicado se almacena en la sesión de WooCommerce del cliente. Esto significa que:

el código se recuerda incluso tras actualizar la página
el código se elimina tras realizar un pedido o cerrar sesión
el cliente puede eliminar manualmente el código aplicado

Seguimiento del saldo

Cada tarjeta regalo tiene un saldo que se reduce con cada uso. El historial de transacciones de la tarjeta contiene:

Campo	Descripción
Fecha	Fecha de la transacción
Tipo	Recarga / Uso / Reembolso
Importe	Importe de la operación
Pedido	ID del pedido (para uso y reembolso)
Saldo tras la operación	Saldo actual tras la transacción

Panel de administración

En el panel WooCommerce > Tarjetas regalo, el administrador puede:

consultar la lista de todas las tarjetas con sus saldos
comprobar el historial de transacciones de una tarjeta
recargar una tarjeta manualmente
bloquear una tarjeta
exportar la lista de tarjetas (CSV)

Panel Mi cuenta

El módulo añade un endpoint /polski-gift-cards al panel Mi cuenta del cliente. El endpoint está disponible en:

/moje-konto/polski-gift-cards/

En el panel, el cliente puede ver:

lista de tarjetas regalo propias
saldo actual de cada tarjeta
historial de uso
código de la tarjeta (con opción de copia)
fecha de caducidad (si se ha establecido)

Hooks

`polski_pro/gift_card/validate`

Filtra el resultado de la validación del código de la tarjeta regalo en el carrito.

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

Ejemplo:

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`

Acción que se dispara tras aplicar una tarjeta regalo en el carrito.

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

Ejemplo:

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`

Acción que se dispara tras crear un pedido utilizando una tarjeta regalo.

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

Ejemplo:

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`

Filtra el importe a deducir de la tarjeta regalo al recalcular los totales del carrito.

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

Correo electrónico con el código

Tras el pago de un pedido que contiene una tarjeta regalo, el plugin envía un correo electrónico con el código. El correo incluye:

código de la tarjeta formateado
valor nominal
fecha de caducidad (si procede)
instrucciones de uso

La plantilla del correo electrónico se puede personalizar en WooCommerce > Ajustes > Correos electrónicos > Tarjeta regalo.

Correo electrónico para el destinatario

Al comprar una tarjeta, el cliente puede indicar la dirección de correo electrónico del destinatario. En ese caso:

el código se envía a la dirección del destinatario
el comprador recibe una confirmación de compra (sin el código)
opcionalmente: el comprador puede añadir un mensaje para el destinatario

Problemas frecuentes

El código no se acepta en el carrito

Compruebe si el código está introducido correctamente (sin espacios al principio/final)
Verifique que la tarjeta no haya caducado
Compruebe el saldo de la tarjeta en el panel de administración
Asegúrese de que la tarjeta no esté bloqueada

El cliente no recibió el código por correo electrónico

Compruebe si el pedido está pagado (estado “Procesando” o “Completado”)
Verifique la configuración de los correos electrónicos de WooCommerce
Revise los registros de correo electrónico en busca de errores de envío

El saldo no se reduce tras un pedido

Compruebe si el pedido se realizó correctamente (no cancelado)
Verifique el historial de transacciones de la tarjeta en el panel de administración
Revise los registros en busca de errores de PHP

Recursos relacionados

Esta página tiene únicamente carácter informativo y no constituye asesoramiento legal. Consulte a un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) proporcionado sin garantía.