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

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

Configuración

Desde Polski PRO 1.22.0 las tarjetas regalo tienen su propia fila en Polski > Módulos (clave de módulo gift_cards). Ahí se activa el módulo y en esa misma fila se establecen los valores de toda la tienda; al guardar se escriben en la opción polski_gift_cards. El módulo se entrega apagado.

La fila no muestra todas las claves que lee el módulo. Lo que falte se puede seguir estableciendo directamente en la opción, por ejemplo con WP-CLI:

wp option patch update polski_gift_cards expiry_days 180

Los valores por producto (si un producto es o no una tarjeta regalo, sus importes y los límites del importe libre) están en la pestaña Polski Pro del editor de productos, consulte Per-product settings.

Ajustes que lee el módulo

Clave	Por defecto	Descripción
show_on_single	true	Mostrar los campos de tarjeta regalo en la página de producto
allow_custom_amount	true	Permitir que el comprador escriba su propio importe
min_amount / max_amount	20 / 1000	Límites del importe personalizado
default_amounts	50,100,200	Importes propuestos en la página de producto
code_prefix	SP	Prefijo del código generado
expiry_days	365	Días de validez de la tarjeta
show_in_account / account_label	true / Tarjetas regalo	Sección de Mi cuenta con los saldos de las tarjetas
email_subject / email_heading	ver el código	Texto del correo de la tarjeta regalo
date_format	d.m.Y	Formato de fecha en los textos para el cliente

Cada etiqueta y cada aviso tienen también su propia clave (recipient_name_label, invalid_code_text, applied_code_text, etc.). Los valores por defecto están en Polski\Pro\Service\GiftCardService.

Creación de un producto de tarjeta regalo

1. Vaya a Productos > Añadir nuevo
2. Seleccione el tipo de producto: Tarjeta regalo
3. Establezca el precio (valor nominal de la tarjeta)
4. Opcionalmente: active “Importe personalizado” - el cliente introduce él mismo el valor de la tarjeta
5. Opcionalmente: establezca un importe mínimo y máximo para los importes personalizados
6. 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

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

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

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

El saldo no se reduce tras un pedido

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

Recursos relacionados

• Resumen de PRO
• Informar de un problema

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.