Kowal ShippingRules — guía de instalación, configuración y uso

Objetivo del documento

Este documento describe la implantación práctica y el uso del módulo Kowal_ShippingRules en Magento 2. Está destinado a las personas responsables de la instalación del módulo, la configuración de la tienda, las pruebas de implantació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 de Amasty,
• checklist de pruebas tras la implantación.

Información básica

Nombre técnico del módulo:

Kowal_ShippingRules

Ubicación del módulo:

app/code/Kowal/ShippingRules

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 previos a la instalación

Antes de la instalación se debe confirmar:

• 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 implantación se realiza primero en un entorno de pruebas o staging,
• tras 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

1. Carga el módulo

El módulo debe encontrarse en el directorio:

app/code/Kowal/ShippingRules

2. Activa el módulo

bin/magento module:enable Kowal_ShippingRules

Si Kowal_Base aún 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 la gestión de 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 debe aparecer en la lista de módulos activos.

Comprobación tras la instalación

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

bin/magento kowal:shippingrules:stabilization:check

Versión completa en JSON:

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

El comando es read-only y no modifica datos. Comprueba, entre otras cosas:

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

Si el comando devuelve errores, no se debe cambiar 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 prueba de configuración.
• Test Method Price — precio del método de prueba de configuración.
• Sort Order — orden del carrier en la lista de métodos de entrega.
• Show Method If Not Applicable — si se debe mostrar un error cuando no haya métodos disponibles.
• Displayed Error Message — mensaje cuando el método no está disponible.

Configuración 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 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 solo las restricciones.

Sección Extra Fees:

• Enable Extra Fees — activa o desactiva solo los cargos adicionales.
• Fee Tax Mode — define la forma de gestionar el impuesto para Extra Fee.

Modos de impuestos disponibles:

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

Configuración predeterminada y segura:

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?

Se debe crear un método de envío cuando la tienda necesite su propia opción de entrega, 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 del método

Ve a:

Sales / Shipping Methods & Rules / Shipping Methods

Luego selecciona Add New o edita un método existente.

Campos típicos del método:

• Is Active — 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 por store view.
• Customer Groups — visibilidad por grupos de clientes.
• Conditions — condiciones de disponibilidad del método.

Recomendaciones para el campo Code:

• usa letras minúsculas,
• no uses caracteres polacos,
• no uses espacios,
• usa 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 debe tener al menos una tarifa activa. Si el método no tiene una 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 definen 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 determinado,
• método disponible solo para carritos por encima de un valor definido,
• método disponible solo para un país de entrega seleccionado.

Si las condiciones están vacías, el método solo estará limitado 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 el locker 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 restricciones

Ve a:

Sales / Shipping Methods & Rules / Shipping Restrictions

Luego selecciona Add New o edita una restricción existente.

Campos típicos:

• Is Active — 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 — forma de funcionamiento.
• Message — mensaje para el cliente.
• Priority — prioridad.
• Stop Processing — si debe detenerse la comprobación adicional de reglas.
• Store Views — alcance por store view.
• Customer Groups — alcance por grupos de clientes.
• Conditions — condiciones de coincidencia.

Acciones de restricción

hide:

• el método se ocultará,
• el cliente no lo verá,
• adecuado para restricciones evidentes, por ejemplo un locker 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 una comprobación anterior.

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

Recomendación:

• usa prioridades más altas para reglas más específicas,
• usa 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 de gran volumen,
• 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

Luego selecciona Add New o edita un cargo existente.

Campos típicos:

• Is Active — 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 — forma de cálculo.
• Tax Class ID — clase fiscal, si se utiliza tax mode.
• Priority — prioridad.
• Stop Processing — si se debe detener el cálculo adicional del fee.
• Store Views — alcance por store view.
• Customer Groups — alcance por grupos de clientes.
• Conditions — condiciones para aplicar el cargo.

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 aplicación

cart:

• un solo cargo para todo el carrito.

per_item:

• cargo multiplicado por la cantidad de productos.

per_matching_item:

• cargo aplicado solo a productos que cumplan 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

Por defecto, 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 de Extra Fee.
3. Prueba carrito, order, invoice y creditmemo.

El impuesto de Extra Fee debe comprobarse siempre 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 otras cosas, a:

• atributos de producto,
• SKU,
• categoría,
• 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 gran volumen es pallet.

Regla:

Jeżeli produkt w koszyku ma shipping_type = pallet

Posibles acciones:

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

Recomendaciones al trabajar con condiciones

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

Diagnóstico y logging

Archivo de log dedicado:

var/log/kowal_shipping_rules.log

El debug se puede activar en:

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

Activa:

Enable Debug Logging = Yes

Recomendaciones:

• no dejes debug logging activado permanentemente en producción,
• activa debug solo durante el diagnóstico,
• cuando terminen las pruebas, desactiva debug,
• analiza los logs junto con el carrito de prueba y la configuración de reglas.

Funciones de emergencia

Si se produce un problema tras la implantación, se puede desactivar de forma independiente:

Todo el carrier

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

Resultado:

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

Solo restricciones

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

Resultado:

• los métodos no se ocultarán ni bloquearán mediante restricciones.

Solo Extra Fee

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

Resultado:

• no se calcularán cargos adicionales.

Migración desde Amasty

Objetivo de la migración

La migración desde Amasty tiene como objetivo ayudar a trasladar la configuración de restricciones y extra fee a Kowal_ShippingRules.

El módulo de Kowal no requiere Amasty para funcionar con normalidad. 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,
• el guardado 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 volumen de las tablas de Amasty y de las tablas de Kowal.

Paso 2 — dry-run de 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, estas reglas deben analizarse antes de apply.

Paso 3 — preview apply

Ejecuta:

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

Esto aún no guarda 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, hay que comparar los resultados para carritos de prueba.

Carritos recomendados:

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

Para cada carrito, comprueba:

• métodos de envío disponibles,
• métodos ocultos,
• mensajes de error,
• extra fee calculado,
• importes brutos/netos, si se usa tax fee,
• order,
• invoice,
• creditmemo.

Paso 8 — decisión sobre el 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 inmediatamente después de la migración,
• primero desactiva el funcionamiento a nivel de configuración,
• mantén la posibilidad de rollback,
• prepara una lista de reglas que requieran corrección manual.

Rollback después de la migración

Si surge 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 checkout.
6. Conserva los informes de migración para su análisis.

Checklist después de la implantació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,
• los store views están configurados correctamente,
• los customer groups están configurados correctamente,
• las restricciones están activadas o conscientemente desactivadas,
• los extra fees están activados o conscientemente desactivados,
• 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 al seleccionar el método,
• el cambio del método de envío recalcula el fee,
• order incluye los importes del fee,
• invoice incluye 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 país, región, código postal, peso y subtotal,
• si el store view es correcto,
• si el customer group es correcto,
• si se cumplen las condiciones del método,
• si una restricción no está ocultando el método.

Extra Fee no se calcula

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 la adecuada,
• si otra regla con Stop Processing no termina el procesamiento antes.

El impuesto de Extra Fee no se calcula

Comprueba:

• si Fee Tax Mode = Calculate by Fee Tax Class,
• si la regla de 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 dirección de entrega,
• si el fee se está calculando realmente.

Buenas prácticas

• Configura primero reglas simples y luego añade más condiciones.
• Prepara un carrito de prueba para cada regla importante.
• Usa nombres claros para métodos, restricciones y fees.
• Evita varias reglas muy similares con la misma prioridad.
• Documenta el motivo de crear una restricción o un fee en el nombre.
• Después de cambiar atributos de productos, 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 implantación y arquitectura.
• docs/OPIS_MARKETINGOWY.md — descripción de marketing del módulo.