Commerce Gift Card
Proporciona funcionalidad completa de tarjetas de regalo para Drupal Commerce, incluyendo creación, venta, canje, gestión de saldo y seguimiento de transacciones.
commerce_giftcard
Overview
Commerce Gift Card es una solución integral para implementar funcionalidad de tarjetas de regalo en tiendas Drupal Commerce. Introduce dos nuevos tipos de entidad: Tarjetas de Regalo (entidades de contenido que almacenan códigos únicos y saldos) y Tipos de Tarjetas de Regalo (entidades de configuración que definen patrones de generación de códigos y configuraciones de visualización).
El módulo soporta el ciclo de vida completo de las tarjetas de regalo: los comerciantes pueden crear manualmente tarjetas de regalo individuales, generar tarjetas en masa con longitudes de código configurables, o configurar productos que generen automáticamente tarjetas de regalo al momento de la compra. Los clientes pueden canjear tarjetas de regalo durante el checkout a través de un panel de canje integrado, con el saldo aplicado automáticamente como ajuste del pedido.
Cada cambio de saldo se registra como una transacción, proporcionando un historial completo de auditoría del uso de tarjetas de regalo. El módulo también incluye funcionalidad de reembolso, permitiendo a los administradores devolver montos a las tarjetas de regalo desde pedidos completados. Las restricciones específicas de tienda pueden limitar dónde son válidas las tarjetas de regalo, y la validación de moneda asegura que las tarjetas de regalo coincidan con las monedas de los pedidos.
Features
- Crear y gestionar tarjetas de regalo con códigos alfanuméricos únicos y saldos monetarios
- Definir múltiples tipos de tarjetas de regalo con patrones de generación de código configurables (longitud personalizable)
- Generar tarjetas de regalo en masa por lotes con tipo, saldo y restricciones de tienda especificados
- Vender tarjetas de regalo como productos añadiendo el trait de compra a los tipos de variación de producto
- Canjear tarjetas de regalo durante el checkout mediante un panel de checkout dedicado con soporte configurable para múltiples tarjetas
- Deducción automática del saldo cuando se realizan pedidos con registro de transacciones
- Historial completo de transacciones rastreando todos los cambios de saldo con referencias a entidades relacionadas
- Reembolsar montos de tarjetas de regalo de pedidos completados a las tarjetas de regalo originales
- Restricciones específicas de tienda para limitar la validez de tarjetas de regalo a tiendas seleccionadas
- Etiquetas de visualización basadas en Token para personalizar cómo aparecen las tarjetas de regalo como ajustes de pedido
- Integración con Views con vistas de administración preconfiguradas para gestionar tarjetas de regalo y transacciones
- Sistema de eventos extensible para personalizar cálculos de montos de tarjetas de regalo y operaciones CRUD
Use Cases
Vender tarjetas de regalo como productos
Crea un tipo de variación de producto con el trait 'Permite comprar tarjetas de regalo'. Crea productos con este tipo de variación y configura el tipo de tarjeta de regalo y opcionalmente un monto fijo de tarjeta de regalo (o déjalo vacío para usar el precio del producto). Cuando los clientes compran estos productos, las tarjetas de regalo se generan automáticamente y se les asignan, con los códigos disponibles en el mensaje de finalización del checkout.
Tarjetas de regalo promocionales
Usa la función de generación masiva para crear tarjetas de regalo para campañas de marketing. Navega a /admin/commerce/giftcards/generate, selecciona el tipo, establece el saldo promocional y especifica la cantidad. Distribuye los códigos generados a través de tus canales de marketing.
Recompensas de fidelización de clientes
Crea programáticamente tarjetas de regalo como recompensas usando el entity storage. Crea una entidad commerce_giftcard con un saldo específico y asigna al cliente como propietario. Luego podrán canjearla en compras futuras.
Pagos parciales con tarjetas de regalo
Los clientes pueden aplicar tarjetas de regalo durante el checkout incluso si el saldo de la tarjeta de regalo es menor que el total del pedido. El saldo completo de la tarjeta de regalo se aplica, y el cliente paga el resto con otro método de pago.
Restricciones de tarjetas de regalo multi-tienda
Para configuraciones multi-tienda, las tarjetas de regalo pueden restringirse a tiendas específicas. Al crear o generar tarjetas de regalo, selecciona las tiendas permitidas. Las tarjetas de regalo solo serán canjeables en esas tiendas.
Reembolsos de tarjetas de regalo
Cuando los pedidos con pagos de tarjetas de regalo se cancelan o reembolsan parcialmente, usa la pestaña 'Reembolsar tarjeta de regalo' en el pedido para devolver el monto al saldo de la tarjeta de regalo. Esto crea una transacción positiva y actualiza los ajustes del pedido.
Tips
- Usa tokens en la etiqueta de visualización (ej. 'Tarjeta de Regalo [commerce_giftcard:code:value]') para mostrar el código específico de la tarjeta de regalo en los resúmenes de pedidos
- El procesador de pedidos se ejecuta con prioridad -1000, lo que significa que las tarjetas de regalo se aplican después de todos los demás ajustes incluyendo promociones e impuestos
- Las tarjetas de regalo sin propietario (uid es null) pueden ser canjeadas por cualquiera, mientras que las tarjetas de regalo con propietario pueden ser vistas por sus propietarios con el permiso 'view own giftcards'
- Los comentarios de transacciones soportan variables de traducción, por lo que mensajes como 'Usado en pedido con id @order_id' son correctamente traducibles
- El generador masivo crea 2x la cantidad solicitada de códigos, luego filtra por unicidad, asegurando altas tasas de éxito incluso con longitudes de código más cortas
Technical Details
Admin Pages 8
/admin/commerce/giftcards
Página principal de administración para ver y gestionar todas las tarjetas de regalo. Muestra una tabla con código de tarjeta de regalo, tipo, estado (habilitada/deshabilitada), saldo actual, propietario, cantidad de transacciones y fechas de creación/actualización. Proporciona operaciones para editar, eliminar y añadir transacciones a cada tarjeta de regalo.
/admin/commerce/giftcards/add/{commerce_giftcard_type}
Formulario para crear una nueva tarjeta de regalo de un tipo específico. Permite establecer el código único, saldo inicial, propietario, estado y restricciones de tienda.
/admin/commerce/giftcards/generate
Formulario de generación masiva para crear múltiples tarjetas de regalo a la vez. Usa procesamiento por lotes para generar tarjetas en grupos de 25.
/admin/commerce/giftcards/{commerce_giftcard}/transactions
Muestra todas las transacciones de una tarjeta de regalo específica, mostrando el historial completo de cambios de saldo.
/admin/commerce/giftcards/add-transaction
Formulario para crear manualmente una transacción de tarjeta de regalo. Puede añadir o restar del saldo de la tarjeta de regalo.
/admin/commerce/config/giftcard_types
Página de configuración para gestionar bundles de tipos de tarjetas de regalo. Cada tipo define configuraciones para generación de códigos y etiquetas de visualización.
/admin/commerce/config/giftcard_types/add
Formulario para crear un nuevo tipo de tarjeta de regalo con configuraciones de generación de código y configuración de visualización.
/admin/commerce/orders/{commerce_order}/giftcard-refund
Formulario para reembolsar montos de tarjetas de regalo a las tarjetas de regalo usadas en un pedido completado. Solo disponible para pedidos que no son borradores y que tienen ajustes de tarjetas de regalo.
Permisos 6
Hooks 3
hook_entity_base_field_info
Añade el campo commerce_giftcards a las entidades commerce_order para almacenar referencias de tarjetas de regalo aplicadas.
hook_preprocess_commerce_checkout_completion_message
Proporciona los códigos de tarjetas de regalo comprados en un pedido a la plantilla del mensaje de finalización del checkout.
hook_theme
Define el hook de tema commerce_giftcard_redemption_form para el formulario inline de canje.
Troubleshooting 5
Los códigos de tarjetas de regalo deben ser únicos. La validación no distingue mayúsculas de minúsculas, por lo que 'ABC123' y 'abc123' se consideran iguales. Verifica las tarjetas de regalo existentes o usa el generador automático de códigos.
Las tarjetas de regalo solo pueden usarse en pedidos con monedas coincidentes. Asegúrate de que la moneda del saldo de la tarjeta de regalo coincida con la moneda predeterminada de la tienda.
Si una tarjeta de regalo tiene restricciones de tienda configuradas, solo puede canjearse en esas tiendas específicas. Verifica la configuración de tiendas de la tarjeta de regalo.
Las transacciones que resultarían en un saldo negativo de tarjeta de regalo se rechazan. Esto previene el sobrecanje. La validación asegura que los montos de transacción negativos no excedan el saldo actual.
Asegúrate de que el tipo de variación de producto tenga el trait 'Permite comprar tarjetas de regalo' y que el campo commerce_giftcard_type esté configurado en la variación. Las tarjetas de regalo se crean durante la transición de colocación del pedido.
Security Notes 5
- Los códigos de tarjetas de regalo deben tratarse como datos sensibles similares a contraseñas o claves API
- El permiso 'administer commerce_giftcard' otorga acceso completo incluyendo generación masiva y visualización de todos los saldos
- Almacena los códigos de tarjetas de regalo de forma segura y transmítelos a través de conexiones encriptadas
- Considera implementar limitación de velocidad en el formulario de canje para prevenir intentos de adivinación de códigos por fuerza bruta
- El generador de códigos usa el servicio generador de contraseñas de Drupal para cadenas aleatorias criptográficamente seguras