Kowal ShippingRules — instrucciones de instalación, configuración y uso

Objetivo del documento

Este documento describe la implementación práctica y el uso del módulo Kowal_ShippingRules en Magento 2. Está dirigido a las personas responsables de la instalación del módulo, la configuración de la tienda, las pruebas de implementación y la gestión diaria de las reglas de envío.

El documento incluye:

• instalación del módulo,
• configuración básica,
• creación de métodos de envío,
• configuración de tarifas,
• gestión de restricciones de métodos de entrega,
• gestión de cargos adicionales Extra Fee,
• diagnóstico,
• migración desde módulos Amasty,
• checklist de pruebas posteriores a la implementación.

Información básica

Nombre técnico del módulo:

Kowal_ShippingRules

Ubicación del módulo:

vendor/kowal/module-shipping-rules

Código del carrier:

kowal_shippingrules

El código del método de envío en checkout tiene el formato:

kowal_shippingrules_

Ejemplo:

kowal_shippingrules_dostawa_paletowa

Requisitos antes de la instalación

Antes de la instalación, confirma lo siguiente:

• la tienda funciona con Magento 2.4.x,
• el entorno utiliza PHP >=8.1,
• el módulo Kowal_Base está disponible,
• se ha realizado una copia de seguridad de los archivos y de la base de datos,
• la implementación se realiza primero en un entorno de pruebas o staging,
• después de la instalación será posible ejecutar setup:upgrade y setup:di:compile,
• la persona que realiza las pruebas tiene acceso al panel de administración y al checkout.

Instalación del módulo

Instalación mediante Composer

Recibirás por correo electrónico los datos de acceso al repositorio Composer, es decir, la dirección de e-mail del cliente y el token de licencia, después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-shipping-rules

2. Activa el módulo

bin/magento module:enable Kowal_ShippingRules

Si Kowal_Base todavía no está activado, debe activarse antes o junto con el módulo:

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Actualiza la base de datos

bin/magento setup:upgrade

Este comando crea las tablas del módulo y añade las columnas necesarias para gestionar Extra Fee en quote, order, invoice y creditmemo.

4. Compila DI

En producción:

bin/magento setup:di:compile

5. Limpia la caché

bin/magento cache:flush

6. Comprueba el estado del módulo

bin/magento module:status Kowal_ShippingRules

El módulo debería aparecer en la lista de módulos activos.

Comprobación posterior a la instalación

Después de la instalación, ejecuta el diagnóstico:

bin/magento kowal:shippingrules:stabilization:check

Variante completa en JSON:

bin/magento kowal:shippingrules:stabilization:check --json

El comando es read-only y no modifica los datos. Comprueba, entre otros aspectos:

• la presencia de las tablas del módulo,
• el número de registros,
• JSON de condiciones incorrecto,
• métodos activos sin tarifas activas,
• reglas Extra Fee con tax class cuando el modo de impuestos está desactivado.

Si el comando devuelve errores, no se debe pasar el módulo a uso en producción antes de aclararlos.

Configuración básica

Carrier

Ruta en el panel de Magento:

Stores / Configuration / Sales / Delivery Methods / Shipping Methods & Rules

Campos:

• Enabled — activa o desactiva el carrier kowal_shippingrules.
• Title — nombre del grupo de métodos visible en checkout.
• Test Method Name — nombre del método de configuración de prueba.
• Test Method Price — precio del método de configuración de prueba.
• Sort Order — orden del carrier en la lista de métodos de entrega.
• Show Method If Not Applicable — indica si se muestra un error cuando no hay métodos disponibles.
• Displayed Error Message — mensaje cuando el método no está disponible.

Ajuste más importante:

carriers/kowal_shippingrules/active = 1

Si el carrier está desactivado, los métodos creados en el módulo no estarán disponibles en checkout.

Diagnóstico y funciones de emergencia

Ruta en el panel de Magento:

Stores / Configuration / Sales / Shipping Methods & Rules

Sección General Diagnostics:

• Enable Debug Logging — guarda los detalles de las decisiones en el log.
• Shadow Mode — modo preparado para comparar el comportamiento durante la migración.

Sección Restrictions:

• Enable Restrictions — activa o desactiva únicamente las restricciones.

Sección Extra Fees:

• Enable Extra Fees — activa o desactiva únicamente los cargos adicionales.
• Fee Tax Mode — define cómo se gestiona el impuesto para Extra Fee.

Modos de impuesto disponibles:

• Do Not Calculate Tax — el módulo no calcula impuestos sobre Extra Fee.
• Calculate by Fee Tax Class — el módulo calcula el impuesto según la clase de impuesto configurada en la regla fee.

Ajustes predeterminados y seguros:

kowal_shippingrules/general/debug = 0kowal_shippingrules/general/shadow_mode = 0kowal_shippingrules/restrictions/enabled = 1kowal_shippingrules/fees/enabled = 1kowal_shippingrules/fees/tax_mode = none

Menú del módulo en el panel

Ruta:

Sales / Shipping Methods & Rules

Secciones disponibles:

• Shipping Methods — métodos de envío y tarifas,
• Shipping Restrictions — restricciones de métodos de entrega,
• Extra Fees — cargos adicionales.

Gestión de métodos de envío

¿Cuándo crear un método de envío?

Debe crearse un método de envío cuando la tienda necesita una opción de entrega propia, por ejemplo:

• entrega en palé,
• transporte especial,
• entrega local,
• mensajería para productos voluminosos,
• recogida logística,
• método disponible solo para productos o regiones seleccionados.

Creación de un método

Ve a:

Sales / Shipping Methods & Rules / Shipping Methods

A continuación, selecciona Add New o edita un método existente.

Campos habituales del método:

• Is Active — indica si el método está activo.
• Code — código técnico del método.
• Name — nombre visible para el cliente.
• Description — descripción del método.
• Sort Order — orden de visualización.
• Store Views — visibilidad para store view.
• Customer Groups — visibilidad para grupos de clientes.
• Conditions — condiciones de disponibilidad del método.

Recomendaciones para el campo Code:

• utiliza minúsculas,
• no utilices caracteres polacos,
• no utilices espacios,
• utiliza guiones bajos en lugar de espacios.

Ejemplos:

dostawa_paletowatransport_specjalnykurier_gabarytdostawa_lokalna

El código completo del método en checkout tendrá el prefijo del carrier:

kowal_shippingrules_dostawa_paletowa

Tarifas del método

Un método activo debería tener al menos una tarifa activa. Si el método no tiene ninguna tarifa coincidente, no aparecerá en checkout.

La tarifa puede depender de:

• país,
• región,
• código postal,
• valor del carrito,
• peso,
• cantidad de productos,
• tipo de envío,
• prioridad.

Modos de precio:

• fixed — precio fijo,
• percent_subtotal — porcentaje del subtotal.

Ejemplos:

• precio de 29 zł para envíos de hasta 30 kg,
• precio de 149 zł para entrega en palé,
• 5% del valor del carrito para transporte especial,
• tarifa independiente para códigos postales seleccionados.

Condiciones del método

Las condiciones determinan cuándo debe estar disponible el método.

Ejemplos:

• método disponible solo para productos de una categoría seleccionada,
• método disponible solo con un atributo de producto específico,
• método disponible solo para carritos por encima de un valor determinado,
• método disponible solo para un país de entrega seleccionado.

Si las condiciones están vacías, el método se limita únicamente por el estado, store view, customer group y una tarifa coincidente.

Gestión de restricciones de métodos de entrega

¿Cuándo usar restricciones?

Las restricciones sirven para ocultar o bloquear métodos de envío que no deberían estar disponibles para un pedido concreto.

Ejemplos:

• ocultar punto de recogida para productos voluminosos,
• bloquear el envío internacional para una categoría seleccionada,
• mostrar un mensaje indicando que el transporte exprés no está disponible para productos bajo pedido,
• ocultar un método de entrega para un país seleccionado.

Creación de una restricción

Ve a:

Sales / Shipping Methods & Rules / Shipping Restrictions

A continuación, selecciona Add New o edita una restricción existente.

Campos habituales:

• Is Active — indica si la restricción está activa.
• Name — nombre interno.
• Target Carrier — carrier al que se aplica la restricción.
• Target Method — método al que se aplica la restricción.
• Action — modo de funcionamiento.
• Message — mensaje para el cliente.
• Priority — prioridad.
• Stop Processing — indica si se detiene la comprobación de reglas posteriores.
• Store Views — alcance de store view.
• Customer Groups — alcance de grupos de clientes.
• Conditions — condiciones de coincidencia.

Acciones de restricción

hide:

• el método quedará oculto,
• el cliente no lo verá,
• adecuado para limitaciones evidentes, por ejemplo, punto de recogida para productos voluminosos.

error:

• el método se mostrará como no disponible,
• el cliente verá un mensaje,
• adecuado cuando conviene explicar el motivo de la falta de disponibilidad.

Prioridad y Stop Processing

Las reglas se comprueban según la prioridad. Una prioridad más alta significa que se comprueba antes.

Stop Processing = Yes significa que, después de coincidir esta restricción, el módulo no comprueba más restricciones para este método.

Recomendación:

• utiliza prioridades más altas para reglas más específicas,
• utiliza prioridades más bajas para reglas generales,
• activa Stop Processing si la regla debe decidir de forma definitiva la disponibilidad del método.

Gestión de Extra Fee

¿Cuándo usar Extra Fee?

Extra Fee sirve para añadir cargos adicionales al pedido.

Ejemplos:

• cargo por embalaje no estándar,
• suplemento por transporte voluminoso,
• cargo por productos delicados,
• cargo logístico para un método de entrega concreto,
• suplemento para regiones seleccionadas.

Creación de Extra Fee

Ve a:

Sales / Shipping Methods & Rules / Extra Fees

A continuación, selecciona Add New o edita un cargo existente.

Campos habituales:

• Is Active — indica si el fee está activo.
• Name — nombre interno.
• Label — nombre del cargo visible en totals.
• Target Carrier — carrier al que se aplica el fee.
• Target Method — método al que se aplica el fee.
• Price Type — tipo de precio.
• Price — valor del cargo.
• Apply Mode — modo de cálculo.
• Tax Class ID — clase de impuesto si se usa tax mode.
• Priority — prioridad.
• Stop Processing — indica si se detiene el cálculo de fees posteriores.
• Store Views — alcance de store view.
• Customer Groups — alcance de grupos de clientes.
• Conditions — condiciones de aplicación.

Modos de precio

fixed:

• importe fijo,
• por ejemplo, 19 zł por embalaje.

percent_subtotal:

• porcentaje del valor del carrito,
• por ejemplo, 3% del valor del pedido.

Modos de cálculo

cart:

• un único cargo para todo el carrito.

per_item:

• cargo multiplicado por la cantidad de productos.

per_matching_item:

• cargo aplicado solo a los productos que cumplen las condiciones.

Ejemplo:

Si el cargo por protección especial es de 5 zł, y en el carrito hay 3 productos que cumplen la condición, el modo per_matching_item aplicará 15 zł.

Impuesto de Extra Fee

De forma predeterminada, no se calcula impuesto sobre Extra Fee:

kowal_shippingrules/fees/tax_mode = none

Para calcular el impuesto:

1. Configura Fee Tax Mode como Calculate by Fee Tax Class.
2. Completa Tax Class ID en la regla Extra Fee.
3. Prueba el carrito, order, invoice y creditmemo.

El impuesto de Extra Fee debe comprobarse en cada caso con la configuración fiscal de la tienda concreta.

Gestión de condiciones

El módulo utiliza un generador de condiciones similar al de las reglas de Magento.

Las condiciones pueden referirse, entre otros aspectos, a:

• atributos de productos,
• SKU,
• categorías,
• tipo de producto,
• peso,
• precio,
• valor del carrito,
• cantidad de productos,
• país de entrega,
• región,
• ciudad,
• código postal,
• cupón,
• método de envío seleccionado.

Ejemplo de condición para un producto voluminoso

Supuesto:

• el producto tiene el atributo shipping_type,
• el valor para el producto voluminoso es pallet.

Regla:

Jeżeli produkt w koszyku ma shipping_type = pallet

Acciones posibles:

• mostrar el método Dostawa paletowa,
• ocultar el punto de recogida,
• añadir el fee Transport gabarytowy.

Recomendaciones al trabajar con condiciones

• crea primero una regla sencilla y pruébala en el carrito,
• evita demasiadas condiciones en una sola regla,
• describe las reglas con nombres claros,
• para reglas importantes, utiliza atributos de producto inequívocos,
• después de modificar atributos de producto, vuelve a probar el carrito.

Diagnóstico y logging

Archivo de log dedicado:

var/log/kowal_shipping_rules.log

El debug puede activarse en:

Stores / Configuration / Sales / Shipping Methods & Rules / General Diagnostics

Activa:

Enable Debug Logging = Yes

Recomendaciones:

• no dejes debug logging activado de forma permanente en producción,
• activa debug solo durante el diagnóstico,
• desactiva debug después de finalizar las pruebas,
• analiza los logs junto con el carrito de prueba y la configuración de las reglas.

Funciones de emergencia

Si aparece un problema después de la implementación, puedes desactivar de forma independiente:

Todo el carrier

Stores / Configuration / Sales / Delivery Methods / Shipping Methods & Rules / Enabled = No

Efecto:

• los métodos del carrier kowal_shippingrules no estarán disponibles.

Solo restricciones

Stores / Configuration / Sales / Shipping Methods & Rules / Restrictions / Enable Restrictions = No

Efecto:

• los métodos no serán ocultados ni bloqueados por restricciones.

Solo Extra Fee

Stores / Configuration / Sales / Shipping Methods & Rules / Extra Fees / Enable Extra Fees = No

Efecto:

• no se aplicarán cargos adicionales.

Migración desde Amasty

Objetivo de la migración

La migración desde Amasty ayuda a trasladar la configuración de restricciones y extra fee a Kowal_ShippingRules.

El módulo Kowal no requiere Amasty para su funcionamiento normal. Amasty puede utilizarse como fuente de datos de migración y como punto de referencia durante las pruebas.

Fuentes de datos compatibles

El migrador analiza:

amasty_shiprestriction_ruleamasty_extrafeeamasty_extrafee_option

Tablas de destino:

kowal_shipping_restrictionkowal_shipping_fee

Principios de seguridad de la migración

La migración se ha diseñado con cautela:

• el informe es read-only,
• dry-run no guarda datos,
• apply funciona por defecto como preview,
• la escritura requiere la opción explícita --execute,
• solo se guardan registros con estado ready,
• los registros manual_review y unsupported se omiten,
• la migración es idempotente gracias a los campos migration_source y migration_source_key,
• la migración no desactiva Amasty,
• la migración no cambia el tráfico automáticamente.

Paso 1 — informe base

Ejecuta:

bin/magento kowal:shippingrules:amasty:report

El informe se guardará en:

var/report/kowal_shippingrules_amasty_report.json

El informe muestra la presencia y el número de registros de las tablas Amasty y de las tablas Kowal.

Paso 2 — dry-run de la transformación

Ejecuta:

bin/magento kowal:shippingrules:amasty:report --dry-run --limit=100

Dry-run prepara el plan de transformación, pero no guarda nada.

Estados de los registros:

• ready — el registro puede trasladarse automáticamente,
• manual_review — el registro requiere análisis manual,
• unsupported — el registro no es compatible con el migrador automático.

Si el informe contiene muchos manual_review o unsupported, deben analizarse esas reglas antes de apply.

Paso 3 — preview apply

Ejecuta:

bin/magento kowal:shippingrules:amasty:apply --limit=100

Esto sigue sin guardar datos. El comando muestra cuántos registros se crearían, se omitirían o terminarían con error.

Paso 4 — apply de restricciones

Tras aceptar el preview:

bin/magento kowal:shippingrules:amasty:apply --type=restrictions --limit=100 --execute

El comando guardará solo las restricciones con estado ready.

Paso 5 — apply de Extra Fee

Tras aceptar el preview:

bin/magento kowal:shippingrules:amasty:apply --type=fees --limit=100 --execute

El comando guardará solo los extra fees con estado ready.

Paso 6 — diagnóstico después de la migración

Ejecuta:

bin/magento kowal:shippingrules:stabilization:check

Comprueba también el panel:

Sales / Shipping Methods & Rules / Shipping RestrictionsSales / Shipping Methods & Rules / Extra Fees

Paso 7 — pruebas comparativas con Amasty

Antes de desactivar o sustituir la configuración de Amasty, se deben comparar los resultados para carritos de prueba.

Carritos recomendados:

• producto estándar,
• producto voluminoso,
• producto delicado,
• varios productos con diferentes condiciones,
• pedido con diferentes países de entrega,
• pedido con diferentes códigos postales,
• pedido con cupón,
• pedido con un método seleccionado incluido en Extra Fee.

Para cada carrito, comprueba:

• métodos de entrega disponibles,
• métodos ocultos,
• mensajes de error,
• extra fee aplicado,
• importes brutos/netos si se utiliza tax fee,
• order,
• invoice,
• creditmemo.

Paso 8 — decisión de cambio

Solo después de aceptar los resultados se puede planificar el cambio de la configuración de producción.

Recomendaciones:

• no desactives Amasty sin copia de seguridad,
• no elimines los datos de Amasty justo después de la migración,
• primero desactiva el funcionamiento desde la configuración,
• mantén la posibilidad de rollback,
• prepara una lista de reglas que requieren corrección manual.

Rollback después de la migración

Si se produce un problema:

1. Desactiva el carrier Kowal ShippingRules.
2. Desactiva Enable Restrictions.
3. Desactiva Enable Extra Fees.
4. Restaura la configuración anterior de Amasty.
5. Comprueba el checkout.
6. Conserva los informes de migración para su análisis.

Checklist posterior a la implementación

Técnica

• module:status muestra Kowal_ShippingRules como activo,
• setup:upgrade ha finalizado sin errores,
• setup:di:compile ha finalizado sin errores,
• cache:flush ejecutado,
• stabilization:check no devuelve errores,
• el panel de administración muestra el menú Shipping Methods & Rules,
• el archivo de log se guarda cuando debug está activado.

De configuración

• el carrier está activado,
• se ha creado al menos un método de envío,
• el método activo tiene una tarifa activa,
• store views están configuradas correctamente,
• customer groups están configurados correctamente,
• las restricciones están activadas o desactivadas de forma consciente,
• extra fees están activados o desactivados de forma consciente,
• tax mode es coherente con la configuración fiscal de la tienda.

Checkout

• el método aparece para un carrito que cumple las condiciones,
• el método no aparece cuando no hay una tarifa coincidente,
• la restricción hide oculta el método,
• la restricción error muestra un mensaje,
• extra fee aparece en totals después de seleccionar el método,
• el cambio de método de envío recalcula el fee,
• order contiene los importes del fee,
• invoice contiene los importes del fee,
• creditmemo reembolsa correctamente el fee.

Problemas más frecuentes

El método no aparece en checkout

Comprueba:

• si el carrier está activado,
• si el método está activo,
• si el método tiene una tarifa activa,
• si la tarifa coincide con el país, la región, el código postal, el peso y el subtotal,
• si store view es correcto,
• si customer group es correcto,
• si se cumplen las condiciones del método,
• si una restricción no oculta el método.

Extra Fee no se aplica

Comprueba:

• si Enable Extra Fees = Yes,
• si el fee está activo,
• si target carrier y target method son correctos,
• si se cumplen las condiciones del fee,
• si se ha seleccionado un método de envío,
• si el precio del fee es mayor que cero,
• si Stop Processing de una regla anterior no ha detenido el cálculo posterior.

La restricción no funciona

Comprueba:

• si Enable Restrictions = Yes,
• si la restricción está activa,
• si target carrier y target method son correctos,
• si se cumplen las condiciones de la restricción,
• si la prioridad de la regla es adecuada,
• si otra regla con Stop Processing no finaliza el procesamiento antes.

El impuesto de Extra Fee no se calcula

Comprueba:

• si Fee Tax Mode = Calculate by Fee Tax Class,
• si la regla fee tiene configurado Tax Class ID,
• si la configuración fiscal de Magento devuelve una tasa de impuesto para la dirección,
• si el carrito tiene una dirección de entrega,
• si el fee se ha aplicado realmente.

Buenas prácticas

• Configura primero reglas sencillas y después añade condiciones adicionales.
• Prepara un carrito de prueba para cada regla importante.
• Utiliza nombres claros para métodos, restricciones y fees.
• Evita varias reglas muy similares con la misma prioridad.
• Documenta en el nombre el motivo de creación de la restricción o fee.
• Después de modificar atributos de producto, realiza una prueba de checkout.
• Activa debug logging solo durante el diagnóstico.
• Realiza la migración desde Amasty por etapas: informe, dry-run, preview, execute, QA.

Documentos relacionados

• README.md — descripción técnica del módulo para desarrolladores.
• docs/WDROZENIE.md — documentación detallada de implementación y arquitectura.
• docs/OPIS_MARKETINGOWY.md — descripción de marketing del módulo.