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

Antes de la instalación, confirme que:

• la tienda funciona con Magento 2.4.x,
• el entorno usa PHP >=8.1,
• el módulo Kowal_Base está disponible,
• se ha realizado una copia de seguridad de archivos y base de datos,
• la implementació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 encargada de las pruebas tiene acceso al panel de administración y al checkout.

Instalación del módulo

Instalación mediante Composer

Recibirá 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. Sustituya TWOJ_EMAIL_KLIENTA por la dirección de e-mail de su cuenta y TWOJ_TOKEN por el token recibido. Ejecute 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. Active el módulo

bin/magento module:enable Kowal_ShippingRules

Si Kowal_Base aún no está activado, debe activarlo antes o junto con el módulo:

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Actualice 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. Compile DI

En producción:

bin/magento setup:di:compile

5. Limpie la cache

bin/magento cache:flush

6. Compruebe 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, ejecute 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 datos. Comprueba, entre otras cosas:

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

Si el comando devuelve errores, no debe activar el módulo para 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 — si se debe mostrar 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 solo las restricciones.

Sección Extra Fees:

• Enable Extra Fees — activa o desactiva solo 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 impuesto sobre Extra Fee.
• Calculate by Fee Tax Class — el módulo calcula el impuesto según la clase fiscal configurada en la regla fee.

Ajustes seguros predeterminados:

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 crear un método de envío cuando la tienda necesite 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

Vaya a:

Sales / Shipping Methods & Rules / Shipping Methods

A continuación, seleccione Add New o edite un método existente.

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

Recomendaciones para el campo Code:

• use minúsculas,
• no utilice caracteres polacos,
• no utilice espacios,
• use 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 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 determinado,
• método disponible solo para un carrito 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 queda limitado solo 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 de 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

Vaya a:

Sales / Shipping Methods & Rules / Shipping Restrictions

A continuación, seleccione Add New o edite una restricción existente.

Campos habituales:

• Is Active — si la restricción funciona.
• 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 — si se debe detener la comprobación posterior de reglas.
• Store Views — ámbito de store view.
• Customer Groups — ámbito de grupos de clientes.
• Conditions — condiciones de coincidencia.

Acciones de restricción

hide:

• el método se ocultará,
• 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 no disponibilidad.

Prioridad y Stop Processing

Las reglas se comprueban según la prioridad. Una prioridad más alta significa una comprobación más temprana.

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

Recomendación:

• use prioridades más altas para reglas más específicas,
• use prioridades más bajas para reglas generales,
• active Stop Processing si la regla debe decidir definitivamente 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

Vaya a:

Sales / Shipping Methods & Rules / Extra Fees

A continuación, seleccione Add New o edite un cargo existente.

Campos habituales:

• Is Active — si el fee funciona.
• 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 fiscal, si se utiliza tax mode.
• Priority — prioridad.
• Stop Processing — si se debe detener el cálculo posterior de fees.
• Store Views — ámbito de store view.
• Customer Groups — ámbito de grupos de clientes.
• Conditions — condiciones de cálculo.

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 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 calculará 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. Configure Fee Tax Mode como Calculate by Fee Tax Class.
2. Complete Tax Class ID en la regla Extra Fee.
3. Pruebe el 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 a las reglas de Magento.

Las condiciones pueden referirse, entre otros, 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 volumen es pallet.

Regla:

Jeżeli produkt w koszyku ma shipping_type = pallet

Acciones posibles:

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

Recomendaciones al trabajar con condiciones

• cree primero una regla sencilla y pruébela en el carrito,
• evite demasiadas condiciones en una sola regla,
• describa las reglas con nombres claros,
• para reglas importantes, use atributos de producto inequívocos,
• tras cambiar atributos de productos, vuelva 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

Active:

Enable Debug Logging = Yes

Recomendaciones:

• no deje debug logging activado permanentemente en producción,
• active debug solo durante el diagnóstico,
• después de finalizar las pruebas, desactive debug,
• analice los logs junto con el carrito de prueba y la configuración de reglas.

Funciones de emergencia

Si aparece un problema tras la implementación, se puede 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 se ocultarán ni bloquearán mediante 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 prudencia:

• 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

Ejecute:

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 Kowal.

Paso 2 — dry-run de la transformación

Ejecute:

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

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

Estados de 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, debe analizar esas reglas antes de apply.

Paso 3 — preview apply

Ejecute:

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 la preview:

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

El comando guardará solo restricciones con estado ready.

Paso 5 — apply de Extra Fee

Tras aceptar la preview:

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

El comando guardará solo extra fees con estado ready.

Paso 6 — diagnóstico posterior a la migración

Ejecute:

bin/magento kowal:shippingrules:stabilization:check

Compruebe 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 Amasty, compare los resultados para carritos de prueba.

Carritos recomendados:

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

Para cada carrito, compruebe:

• métodos de entrega disponibles,
• métodos ocultos,
• mensajes de error,
• extra fee aplicado,
• importes brutos/netos, si se usa 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 desactive Amasty sin backup,
• no elimine los datos de Amasty inmediatamente después de la migración,
• primero desactive el funcionamiento desde la configuración,
• mantenga la posibilidad de rollback,
• prepare una lista de reglas que requieran corrección manual.

Rollback tras la migración

Si aparece un problema:

1. Desactive el carrier Kowal ShippingRules.
2. Desactive Enable Restrictions.
3. Desactive Enable Extra Fees.
4. Restaure la configuración Amasty anterior.
5. Compruebe el checkout.
6. Conserve 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 finalizó sin errores,
• setup:di:compile finalizó 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 con debug 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 conscientemente,
• extra fees están activados o desactivados conscientemente,
• 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 falta una tarifa coincidente,
• la restricción hide oculta el método,
• la restricción error muestra un mensaje,
• extra fee aparece en totals tras elegir el método,
• el cambio de método de envío recalcula el fee,
• order contiene los importes de fee,
• invoice contiene los importes de fee,
• creditmemo reembolsa correctamente el fee.

Problemas más frecuentes

El método no aparece en checkout

Compruebe:

• 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 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 calcula

Compruebe:

• 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

Compruebe:

• 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

Compruebe:

• 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 dirección de entrega,
• si el fee se ha aplicado realmente.

Buenas prácticas

• Configure primero reglas simples y luego añada condiciones adicionales.
• Prepare un carrito de prueba para cada regla importante.
• Use nombres claros para métodos, restricciones y fees.
• Evite varias reglas muy similares con la misma prioridad.
• Documente en el nombre el motivo de crear una restricción o fee.
• Después de cambiar atributos de productos, realice una prueba de checkout.
• Active debug logging solo durante el diagnóstico.
• Realice 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.