Commerce Currency Resolver
Módulo de mejora multi-moneda para Drupal Commerce 3 que proporciona resolución flexible de moneda y conversión automática de precios.
commerce_currency_resolver
Instalar
composer require 'drupal/commerce_currency_resolver:^2.0'
Overview
Commerce Currency Resolver es una mejora integral para el manejo de funcionalidad multi-moneda en Drupal Commerce 3. Aunque Commerce 3 soporta múltiples monedas de forma nativa, este módulo extiende esa capacidad proporcionando métodos flexibles para resolver la moneda activa y calcular o convertir precios automáticamente entre diferentes monedas.
El módulo soporta múltiples estrategias de resolución de moneda incluyendo basada en tienda (comportamiento predeterminado de Commerce), selección del usuario basada en cookie, mapeo basado en idioma, y detección basada en geolocalización a través de los módulos GeoIP o Smart IP. Cuando se combina con el módulo Commerce Exchanger, permite la conversión automática de precios utilizando tasas de cambio en tiempo real de varios proveedores externos.
El módulo maneja la conversión de moneda no solo para precios de productos sino también para promociones, tarifas, ajustes personalizados, impuestos y tarifas de envío, asegurando un manejo consistente de la moneda a lo largo de todo el ciclo de vida del pedido. Incluye soporte adecuado de contexto de caché para renderizado de contenido personalizado y funciona perfectamente con Dynamic Page Cache.
Features
- Múltiples estrategias de resolución de moneda: basada en tienda (predeterminado), selección del usuario basada en cookie, mapeo basado en idioma, y geolocalización vía GeoIP o Smart IP
- Tres modos de manejo de precios: campos de precio dedicados por moneda, conversión automática vía tasas de cambio, o modo combinado que combina ambos enfoques
- Conversión automática de moneda para artículos del pedido, promociones, tarifas, ajustes personalizados y tarifas de envío durante el procesamiento del pedido
- Bloque selector de moneda que permite a los visitantes elegir manualmente su moneda preferida almacenada en una cookie
- Mapeo de idioma a moneda con interfaz de administración para asignar monedas a cada idioma del sitio
- Mapeo de país a moneda vía servicios de geolocalización (GeoIP o Smart IP) con configuración de matriz flexible
- Sobrescritura de ofertas de promoción del core de Commerce (OrderFixedAmountOff, OrderItemFixedAmountOff) para soportar cantidades multi-moneda
- Sobrescritura de plugins de Commerce Fee (OrderFixedAmount, OrderItemFixedAmount) para cálculos de tarifas multi-moneda
- Sobrescritura de métodos de tarifa plana de Commerce Shipping para conversión automática de moneda en tarifas de envío
- Contexto de caché personalizado (currency_resolver) para el cacheo adecuado de contenido dependiente de la moneda
- Procesador de pedidos que detecta discrepancias de moneda y activa el recálculo del pedido cuando es necesario
- Suscriptor de eventos que monitorea las cargas de pedidos y actualiza la moneda cuando la moneda resuelta del usuario difiere de la moneda del pedido
- Patrón de prefijo de campo configurable para crear campos de precio dedicados por moneda (ej., field_price_eur, field_price_usd)
- Integración con Commerce VADO para compatibilidad con precios de descuento
Use Cases
Comercio electrónico internacional con múltiples monedas
Una tienda en línea que vende productos internacionalmente con precios mostrados en la moneda local del cliente. Usa el submódulo GeoIP o Smart IP para detectar automáticamente la ubicación del visitante y mostrar precios en su moneda local. Habilita el submódulo Exchanger para conversión automática de precios desde tu moneda base.
Sitio multilingüe con moneda por idioma
Un sitio web con múltiples versiones de idioma donde cada idioma debe usar una moneda específica (ej., sitio en Inglés usa USD, sitio en Alemán usa EUR). Habilita el submódulo Language y configura el mapeo de idioma a moneda. Los precios cambiarán automáticamente cuando los usuarios cambien de idioma.
Preferencia de moneda seleccionable por el usuario
Permite a los visitantes elegir manualmente su moneda preferida independientemente de su ubicación o idioma. Habilita el submódulo Cookie y coloca el bloque selector de moneda en tu tema. Los usuarios pueden seleccionar su moneda preferida que persiste entre sesiones vía cookie.
Precios dedicados por moneda con respaldo
Los productos tienen precios específicos establecidos para monedas principales pero deben convertirse automáticamente para otras monedas. Usa el modo combo con campos de precio dedicados (ej., field_price_eur, field_price_usd) para monedas principales. Cuando un campo está vacío, el submódulo Exchanger calcula automáticamente el precio desde tu moneda base.
Tienda multi-moneda completamente automática
Administra productos en una única moneda base con todas las demás monedas calculadas automáticamente. Habilita el submódulo Exchanger y establece el origen de moneda a 'Conversión automática'. Todos los precios, promociones, tarifas y tarifas de envío se convertirán automáticamente usando tu proveedor de tasas de cambio configurado.
Envío con soporte multi-moneda
Ofrece tarifas de envío que se ajustan automáticamente a la moneda del cliente. Habilita tanto el submódulo Exchanger como el de Shipping. Tus métodos de envío de tarifa plana convertirán automáticamente las tarifas, o puedes configurar cantidades específicas por moneda en los ajustes del método de envío.
Tips
- Para mejor rendimiento de caché, usa el contexto de caché 'currency_resolver' en cualquier render array que dependa de la moneda actual.
- El nombre de la cookie para selección de moneda puede personalizarse vía settings.php usando Settings::set('commerce_currency_cookie', 'tu_nombre_cookie').
- Al agregar artículos de pedido programáticamente, usa el servicio commerce_currency_resolver.price_resolver para resolver el precio correcto antes de crear el artículo de pedido.
- Las prioridades del resolutor de moneda determinan la precedencia: Cookie (1000) > GeoIP/Smart IP (900) > Language (800) > Store (predeterminado). Los resolutores de mayor prioridad se verifican primero.
- Para configuraciones de proxy inverso con el submódulo Cookie, la moneda puede pasarse vía X-header (X_COMMERCE_CURRENCY por defecto) en lugar de leer la cookie directamente.
- Usa la configuración 'fields' en promociones, tarifas y métodos de envío para establecer cantidades específicas por moneda. Los campos vacíos recurrirán a conversión automática.
- La bandera CURRENCY_RESOLVER_SKIP_REFRESH puede establecerse en los datos del pedido para prevenir la actualización automática de moneda para pedidos específicos.
- La bandera CURRENCY_RESOLVER_FORCE_REFRESH puede usarse para forzar la actualización de moneda en pedidos programáticamente, incluso para pedidos que normalmente no activarían la actualización.
Technical Details
Admin Pages 4
/admin/commerce/config/commerce_currency_resolver/settings
Página de configuración principal para Commerce Currency Resolver. Configura cómo se resuelven las monedas y cómo se calculan los precios para diferentes monedas.
/admin/commerce/config/commerce_currency_resolver/language
Mapea idiomas del sitio a monedas. Cuando está habilitado, la moneda se resolverá según el idioma actual del usuario. Requiere el submódulo Language.
/admin/commerce/config/commerce_currency_resolver/geoip
Mapea países a monedas usando geolocalización GeoIP. Cuando está habilitado, la moneda se resolverá según el país detectado del visitante. Requiere el submódulo GeoIP.
/admin/commerce/config/commerce_currency_resolver/smart_ip
Mapea países a monedas usando geolocalización Smart IP. Funcionalmente idéntico al mapeo GeoIP pero usa el módulo Smart IP para geolocalización. Requiere el submódulo Smart IP.
Permisos 1
Hooks 5
hook_commerce_promotion_offer_info_alter
Modifica las definiciones de plugins de ofertas de promoción para reemplazar OrderFixedAmountOff y OrderItemFixedAmountOff del core con versiones conscientes de la moneda.
hook_commerce_fee_info_alter
Modifica las definiciones de plugins de tarifas para reemplazar OrderFixedAmount y OrderItemFixedAmount del core con versiones conscientes de la moneda.
hook_commerce_condition_info_alter
Modifica las definiciones de plugins de condición para reemplazar OrderTotalPrice del core con una versión consciente de la moneda.
hook_commerce_shipping_method_info_alter
Modifica las definiciones de plugins de métodos de envío para reemplazar flat_rate y flat_rate_per_item con versiones conscientes de la moneda.
hook_entity_view_alter
Agrega el contexto de caché currency_resolver a entidades commerce product y product variation para asegurar el cacheo adecuado.
Troubleshooting 7
Asegúrate de haber habilitado uno de los submódulos de resolución de moneda (Cookie, Language, GeoIP o Smart IP). El módulo base solo agrega soporte de campos de precio. También verifica que el módulo Internal Dynamic Page Cache esté habilitado y el módulo Page Cache esté deshabilitado.
El módulo Page Cache no soporta contenido personalizado. Deshabilítalo y usa solo el módulo Internal Dynamic Page Cache, que está diseñado para contenido dinámico como precios dependientes de la moneda.
Asegúrate de haber instalado y configurado Commerce Exchanger, habilitado el submódulo commerce_currency_resolver_exchanger, creado al menos un proveedor de tasas de cambio, y seleccionado en los ajustes de Currency Resolver.
Verifica que tus campos de precio específicos por moneda sigan el patrón de nomenclatura configurado en los ajustes. El predeterminado es 'field_price_[código_moneda]' en minúsculas (ej., field_price_eur para Euro). Asegúrate de que el campo exista en tu tipo de variación de producto.
Los pedidos en estado 'draft' se actualizan automáticamente cuando cambia la moneda. Una vez que un pedido pasa a un estado no-draft (ej., completado), la moneda se bloquea. Este es el comportamiento esperado para preservar datos históricos del pedido.
Habilita el submódulo commerce_currency_resolver_shipping si necesitas que las tarifas de envío se conviertan. También asegúrate de que el submódulo Exchanger esté habilitado. Alternativamente, usa la condición 'Order currency' en los métodos de envío para proporcionar tarifas en monedas específicas.
Habilita el submódulo Exchanger que sobrescribe los plugins de ofertas de promoción para soportar cantidades multi-moneda. Luego puedes configurar cantidades específicas por moneda en los ajustes de promoción, o dejar que se calculen automáticamente.
Security Notes 3
- Los valores de moneda de cookies y headers no deben confiarse ciegamente. El módulo valida los códigos de moneda contra las monedas habilitadas antes de usarlos.
- Los proveedores de tasas de cambio pueden tener límites de solicitudes. Monitorea tu uso para evitar interrupciones del servicio.
- La resolución de moneda basada en geolocalización depende de direcciones IP que pueden ser falsificadas o enmascaradas por VPNs. Considera esto al tomar decisiones de negocio sensibles a la seguridad basadas en la ubicación detectada.