Kowal ShippingRules — guide d’installation, de configuration et d’utilisation

Objectif du document

Ce document décrit la mise en place pratique et l’utilisation du module Kowal_ShippingRules dans Magento 2. Il s’adresse aux personnes responsables de l’installation du module, de la configuration de la boutique, des tests de déploiement et de la gestion quotidienne des règles d’expédition.

Le document couvre :

• l’installation du module,
• la configuration de base,
• la création de méthodes d’expédition,
• la configuration des tarifs,
• la gestion des restrictions de méthodes de livraison,
• la gestion des frais supplémentaires Extra Fee,
• le diagnostic,
• la migration depuis les modules Amasty,
• la checklist des tests après déploiement.

Informations de base

Nom technique du module :

Kowal_ShippingRules

Emplacement du module :

vendor/kowal/module-shipping-rules

Code du carrier :

kowal_shippingrules

Le code de la méthode d’expédition dans le checkout a le format suivant :

kowal_shippingrules_

Exemple :

kowal_shippingrules_dostawa_paletowa

Prérequis avant installation

Avant l’installation, confirmez que :

• la boutique fonctionne sous Magento 2.4.x,
• l’environnement utilise PHP >=8.1,
• le module Kowal_Base est disponible,
• une sauvegarde des fichiers et de la base de données a été effectuée,
• le déploiement est d’abord réalisé sur un environnement de test ou de staging,
• après l’installation, il sera possible d’exécuter setup:upgrade et setup:di:compile,
• la personne chargée des tests dispose d’un accès au panneau d’administration et au checkout.

Installation du module

Installation via Composer

Les identifiants d’accès au dépôt Composer, c’est-à-dire l’adresse e-mail du client et le token de licence, vous seront envoyés par e-mail après l’achat. Ils sont également disponibles dans l’espace client après connexion sur kowal.store. Remplacez TWOJ_EMAIL_KLIENTA par l’adresse e-mail de votre compte et TWOJ_TOKEN par le token reçu. Exécutez les commandes dans le répertoire racine 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. Activez le module

bin/magento module:enable Kowal_ShippingRules

Si Kowal_Base n’est pas encore activé, il faut l’activer auparavant ou en même temps que le module :

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Mettez à jour la base de données

bin/magento setup:upgrade

Cette commande crée les tables du module et ajoute les colonnes nécessaires à la prise en charge d’Extra Fee dans quote, order, invoice et creditmemo.

4. Compilez DI

En production :

bin/magento setup:di:compile

5. Videz le cache

bin/magento cache:flush

6. Vérifiez le statut du module

bin/magento module:status Kowal_ShippingRules

Le module doit figurer dans la liste des modules actifs.

Contrôle après installation

Après l’installation, lancez le diagnostic :

bin/magento kowal:shippingrules:stabilization:check

Version complète en JSON :

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

La commande est read-only et ne modifie pas les données. Elle vérifie notamment :

• la présence des tables du module,
• le nombre d’enregistrements,
• les JSON de conditions invalides,
• les méthodes actives sans tarifs actifs,
• les règles Extra Fee avec tax class lorsque le mode taxe est désactivé.

Si la commande renvoie des erreurs, le module ne doit pas être utilisé en production avant leur clarification.

Configuration de base

Carrier

Chemin dans le panneau Magento :

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

Champs :

• Enabled — active ou désactive le carrier kowal_shippingrules.
• Title — nom du groupe de méthodes visible dans le checkout.
• Test Method Name — nom de la méthode de configuration de test.
• Test Method Price — prix de la méthode de configuration de test.
• Sort Order — ordre du carrier dans la liste des méthodes de livraison.
• Show Method If Not Applicable — indique s’il faut afficher une erreur lorsqu’aucune méthode n’est disponible.
• Displayed Error Message — message affiché lorsque la méthode n’est pas disponible.

Paramètre le plus important :

carriers/kowal_shippingrules/active = 1

Si le carrier est désactivé, les méthodes créées dans le module ne seront pas disponibles dans le checkout.

Diagnostic et fonctions d’urgence

Chemin dans le panneau Magento :

Stores / Configuration / Sales / Shipping Methods & Rules

Section General Diagnostics :

• Enable Debug Logging — enregistre les détails des décisions dans le log.
• Shadow Mode — mode prévu pour comparer le comportement pendant une migration.

Section Restrictions :

• Enable Restrictions — active ou désactive uniquement les restrictions.

Section Extra Fees :

• Enable Extra Fees — active ou désactive uniquement les frais supplémentaires.
• Fee Tax Mode — définit le mode de gestion de la taxe pour Extra Fee.

Modes de taxe disponibles :

• Do Not Calculate Tax — le module ne calcule pas de taxe sur Extra Fee.
• Calculate by Fee Tax Class — le module calcule la taxe selon la classe de taxe définie dans la règle fee.

Paramètres par défaut sûrs :

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

Menu du module dans le panneau

Chemin :

Sales / Shipping Methods & Rules

Sections disponibles :

• Shipping Methods — méthodes d’expédition et tarifs,
• Shipping Restrictions — restrictions des méthodes de livraison,
• Extra Fees — frais supplémentaires.

Gestion des méthodes d’expédition

Quand créer une méthode d’expédition ?

Une méthode d’expédition doit être créée lorsque la boutique a besoin d’une option de livraison personnalisée, par exemple :

• livraison sur palette,
• transport spécial,
• livraison locale,
• transporteur pour produits hors gabarit,
• collecte logistique,
• méthode disponible uniquement pour certains produits ou certaines régions.

Création d’une méthode

Accédez à :

Sales / Shipping Methods & Rules / Shipping Methods

Sélectionnez ensuite Add New ou modifiez une méthode existante.

Champs typiques de la méthode :

• Is Active — indique si la méthode est active.
• Code — code technique de la méthode.
• Name — nom visible par le client.
• Description — description de la méthode.
• Sort Order — ordre d’affichage.
• Store Views — visibilité par store view.
• Customer Groups — visibilité par groupes de clients.
• Conditions — conditions de disponibilité de la méthode.

Recommandations pour le champ Code :

• utilisez des minuscules,
• n’utilisez pas de caractères polonais,
• n’utilisez pas d’espaces,
• utilisez des underscores à la place des espaces.

Exemples :

dostawa_paletowatransport_specjalnykurier_gabarytdostawa_lokalna

Le code complet de la méthode dans le checkout aura le préfixe du carrier :

kowal_shippingrules_dostawa_paletowa

Tarifs de la méthode

Une méthode active doit disposer d’au moins un tarif actif. Si la méthode ne possède pas de tarif correspondant, elle n’apparaîtra pas dans le checkout.

Le tarif peut dépendre :

• du pays,
• de la région,
• du code postal,
• de la valeur du panier,
• du poids,
• de la quantité de produits,
• du type d’expédition,
• de la priorité.

Modes de prix :

• fixed — prix fixe,
• percent_subtotal — pourcentage du subtotal.

Exemples :

• prix de 29 zł pour les envois jusqu’à 30 kg,
• prix de 149 zł pour une livraison sur palette,
• 5% de la valeur du panier pour un transport spécial,
• tarif séparé pour certains codes postaux.

Conditions de la méthode

Les conditions déterminent quand la méthode doit être disponible.

Exemples :

• méthode disponible uniquement pour les produits d’une catégorie sélectionnée,
• méthode disponible uniquement avec un attribut produit donné,
• méthode disponible uniquement pour un panier supérieur à une valeur donnée,
• méthode disponible uniquement pour un pays de livraison sélectionné.

Si les conditions sont vides, la méthode est limitée uniquement par le statut, le store view, le customer group et le tarif correspondant.

Gestion des restrictions des méthodes de livraison

Quand utiliser les restrictions ?

Les restrictions servent à masquer ou bloquer les méthodes d’expédition qui ne doivent pas être disponibles pour une commande donnée.

Exemples :

• masquer un point relais pour les produits hors gabarit,
• bloquer l’expédition internationale pour une catégorie sélectionnée,
• afficher un message indiquant que le transport express n’est pas disponible pour les produits sur commande,
• masquer une méthode de livraison pour un pays sélectionné.

Création d’une restriction

Accédez à :

Sales / Shipping Methods & Rules / Shipping Restrictions

Sélectionnez ensuite Add New ou modifiez une restriction existante.

Champs typiques :

• Is Active — indique si la restriction fonctionne.
• Name — nom interne.
• Target Carrier — carrier concerné par la restriction.
• Target Method — méthode concernée par la restriction.
• Action — mode d’action.
• Message — message destiné au client.
• Priority — priorité.
• Stop Processing — indique s’il faut arrêter la vérification des règles suivantes.
• Store Views — périmètre des store views.
• Customer Groups — périmètre des groupes de clients.
• Conditions — conditions de correspondance.

Actions des restrictions

hide :

• la méthode sera masquée,
• le client ne la verra pas,
• adapté aux limitations évidentes, par exemple un point relais pour les produits hors gabarit.

error :

• la méthode sera affichée comme indisponible,
• le client verra un message,
• adapté lorsqu’il est utile d’expliquer la raison de l’indisponibilité.

Priorité et Stop Processing

Les règles sont vérifiées selon leur priorité. Une priorité plus élevée signifie une vérification plus précoce.

Stop Processing = Yes signifie qu’après la correspondance de cette restriction, le module ne vérifie pas les restrictions suivantes pour cette méthode.

Recommandation :

• utilisez des priorités plus élevées pour les règles plus spécifiques,
• utilisez des priorités plus basses pour les règles générales,
• activez Stop Processing si la règle doit déterminer définitivement la disponibilité de la méthode.

Gestion d’Extra Fee

Quand utiliser Extra Fee ?

Extra Fee sert à ajouter des frais supplémentaires à la commande.

Exemples :

• frais d’emballage non standard,
• supplément pour transport hors gabarit,
• frais pour produits fragiles,
• frais logistiques pour une méthode de livraison spécifique,
• supplément pour certaines régions.

Création d’Extra Fee

Accédez à :

Sales / Shipping Methods & Rules / Extra Fees

Sélectionnez ensuite Add New ou modifiez des frais existants.

Champs typiques :

• Is Active — indique si le fee fonctionne.
• Name — nom interne.
• Label — nom des frais visible dans totals.
• Target Carrier — carrier concerné par le fee.
• Target Method — méthode concernée par le fee.
• Price Type — type de prix.
• Price — valeur des frais.
• Apply Mode — mode d’application.
• Tax Class ID — classe de taxe si tax mode est utilisé.
• Priority — priorité.
• Stop Processing — indique s’il faut arrêter l’application des fee suivants.
• Store Views — périmètre des store views.
• Customer Groups — périmètre des groupes de clients.
• Conditions — conditions d’application.

Modes de prix

fixed :

• montant fixe,
• par exemple 19 zł pour l’emballage.

percent_subtotal :

• pourcentage de la valeur du panier,
• par exemple 3% de la valeur de la commande.

Modes d’application

cart :

• un seul frais pour l’ensemble du panier.

per_item :

• frais multipliés par la quantité de produits.

per_matching_item :

• frais appliqués uniquement aux produits qui remplissent les conditions.

Exemple :

Si les frais pour une protection spéciale sont de 5 zł et que le panier contient 3 produits remplissant la condition, le mode per_matching_item appliquera 15 zł.

Taxe Extra Fee

Par défaut, la taxe sur Extra Fee n’est pas calculée :

kowal_shippingrules/fees/tax_mode = none

Pour calculer la taxe :

1. Définissez Fee Tax Mode sur Calculate by Fee Tax Class.
2. Renseignez Tax Class ID dans la règle Extra Fee.
3. Testez le panier, order, invoice et creditmemo.

La taxe Extra Fee doit toujours être vérifiée avec la configuration fiscale de la boutique concernée.

Gestion des conditions

Le module utilise un générateur de conditions similaire aux règles Magento.

Les conditions peuvent notamment concerner :

• les attributs produits,
• les SKU,
• les catégories,
• le type de produit,
• le poids,
• le prix,
• la valeur du panier,
• la quantité de produits,
• le pays de livraison,
• la région,
• la ville,
• le code postal,
• le coupon,
• la méthode d’expédition sélectionnée.

Exemple de condition pour un produit hors gabarit

Hypothèse :

• le produit possède l’attribut shipping_type,
• la valeur pour le gabarit est pallet.

Règle :

Jeżeli produkt w koszyku ma shipping_type = pallet

Actions possibles :

• afficher la méthode Dostawa paletowa,
• masquer le point relais,
• ajouter le fee Transport gabarytowy.

Recommandations pour travailler avec les conditions

• créez d’abord une règle simple et testez-la dans le panier,
• évitez un trop grand nombre de conditions dans une seule règle,
• décrivez les règles avec des noms lisibles,
• pour les règles importantes, utilisez des attributs produits explicites,
• après modification des attributs produits, testez à nouveau le panier.

Diagnostic et journalisation

Fichier de log dédié :

var/log/kowal_shipping_rules.log

Le debug peut être activé dans :

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

Activez :

Enable Debug Logging = Yes

Recommandations :

• ne laissez pas debug logging activé en permanence en production,
• activez le debug uniquement pendant le diagnostic,
• désactivez le debug une fois les tests terminés,
• analysez les logs avec le panier de test et la configuration des règles.

Fonctions d’urgence

En cas de problème après le déploiement, vous pouvez désactiver indépendamment :

Tout le carrier

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

Effet :

• les méthodes du carrier kowal_shippingrules ne seront pas disponibles.

Uniquement les restrictions

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

Effet :

• les méthodes ne seront pas masquées ni bloquées par les restrictions.

Uniquement Extra Fee

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

Effet :

• les frais supplémentaires ne seront pas appliqués.

Migration depuis Amasty

Objectif de la migration

La migration depuis Amasty vise à aider à transférer la configuration des restrictions et des extra fee vers Kowal_ShippingRules.

Le module Kowal ne nécessite pas Amasty pour fonctionner normalement. Amasty peut être utilisé comme source de données de migration et comme point de référence pendant les tests.

Sources de données prises en charge

Le migrateur analyse :

amasty_shiprestriction_ruleamasty_extrafeeamasty_extrafee_option

Tables cibles :

kowal_shipping_restrictionkowal_shipping_fee

Règles de sécurité de la migration

La migration a été conçue avec prudence :

• le rapport est read-only,
• le dry-run n’enregistre aucune donnée,
• apply fonctionne par défaut comme preview,
• l’enregistrement nécessite l’option explicite --execute,
• seuls les enregistrements avec le statut ready sont enregistrés,
• les enregistrements manual_review et unsupported sont ignorés,
• la migration est idempotente grâce aux champs migration_source et migration_source_key,
• la migration ne désactive pas Amasty,
• la migration ne bascule pas le trafic automatiquement.

Étape 1 — rapport de base

Exécutez :

bin/magento kowal:shippingrules:amasty:report

Le rapport sera enregistré dans :

var/report/kowal_shippingrules_amasty_report.json

Le rapport indique la présence et le volume des tables Amasty ainsi que des tables Kowal.

Étape 2 — dry-run de la transformation

Exécutez :

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

Le dry-run prépare le plan de transformation, mais n’enregistre rien.

Statuts des enregistrements :

• ready — l’enregistrement peut être transféré automatiquement,
• manual_review — l’enregistrement nécessite une analyse manuelle,
• unsupported — l’enregistrement n’est pas pris en charge par le migrateur automatique.

Si le rapport contient beaucoup de manual_review ou unsupported, ces règles doivent être analysées avant apply.

Étape 3 — preview apply

Exécutez :

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

Cela n’enregistre toujours aucune donnée. La commande indique combien d’enregistrements seraient créés, ignorés ou terminés avec une erreur.

Étape 4 — apply des restrictions

Après acceptation du preview :

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

La commande enregistrera uniquement les restrictions ayant le statut ready.

Étape 5 — apply Extra Fee

Après acceptation du preview :

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

La commande enregistrera uniquement les extra fees ayant le statut ready.

Étape 6 — diagnostic après migration

Exécutez :

bin/magento kowal:shippingrules:stabilization:check

Vérifiez également le panneau :

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

Étape 7 — tests comparatifs avec Amasty

Avant de désactiver ou de remplacer la configuration Amasty, comparez les résultats pour des paniers de test.

Paniers recommandés :

• produit standard,
• produit hors gabarit,
• produit fragile,
• plusieurs produits avec des conditions différentes,
• commande avec différents pays de livraison,
• commande avec différents codes postaux,
• commande avec coupon,
• commande avec une méthode sélectionnée soumise à Extra Fee.

Pour chaque panier, vérifiez :

• les méthodes de livraison disponibles,
• les méthodes masquées,
• les messages d’erreur,
• les extra fee appliqués,
• les montants TTC/HT si tax fee est utilisé,
• order,
• invoice,
• creditmemo.

Étape 8 — décision de bascule

La bascule de la configuration de production ne peut être planifiée qu’après validation des résultats.

Recommandations :

• ne désactivez pas Amasty sans sauvegarde,
• ne supprimez pas les données Amasty immédiatement après la migration,
• commencez par désactiver le fonctionnement côté configuration,
• conservez la possibilité d’un rollback,
• préparez la liste des règles nécessitant une correction manuelle.

Rollback après migration

En cas de problème :

1. Désactivez le carrier Kowal ShippingRules.
2. Désactivez Enable Restrictions.
3. Désactivez Enable Extra Fees.
4. Restaurez la configuration Amasty existante.
5. Vérifiez le checkout.
6. Conservez les rapports de migration pour analyse.

Checklist après déploiement

Technique

• module:status affiche Kowal_ShippingRules comme actif,
• setup:upgrade s’est terminé sans erreur,
• setup:di:compile s’est terminé sans erreur,
• cache:flush a été exécuté,
• stabilization:check ne renvoie aucune erreur,
• le panneau d’administration affiche le menu Shipping Methods & Rules,
• le fichier de log est écrit lorsque debug est activé.

Configuration

• le carrier est activé,
• au moins une méthode d’expédition a été créée,
• la méthode active possède un tarif actif,
• les store views sont correctement définies,
• les customer groups sont correctement définis,
• les restrictions sont activées ou volontairement désactivées,
• les extra fees sont activés ou volontairement désactivés,
• tax mode est conforme à la configuration fiscale de la boutique.

Checkout

• la méthode apparaît pour un panier remplissant les conditions,
• la méthode n’apparaît pas lorsqu’aucun tarif ne correspond,
• la restriction hide masque la méthode,
• la restriction error affiche un message,
• extra fee apparaît dans totals après sélection de la méthode,
• le changement de méthode d’expédition recalcule le fee,
• order contient les montants de fee,
• invoice contient les montants de fee,
• creditmemo rembourse correctement le fee.

Problèmes les plus fréquents

La méthode n’apparaît pas dans le checkout

Vérifiez :

• si le carrier est activé,
• si la méthode est active,
• si la méthode possède un tarif actif,
• si le tarif correspond au pays, à la région, au code postal, au poids et au subtotal,
• si le store view est correct,
• si le customer group est correct,
• si les conditions de la méthode sont remplies,
• si une restriction ne masque pas la méthode.

Extra Fee ne s’applique pas

Vérifiez :

• si Enable Extra Fees = Yes,
• si le fee est actif,
• si target carrier et target method sont corrects,
• si les conditions du fee sont remplies,
• si une méthode d’expédition a été sélectionnée,
• si le prix du fee est supérieur à zéro,
• si Stop Processing d’une règle précédente n’a pas arrêté la suite de l’application.

La restriction ne fonctionne pas

Vérifiez :

• si Enable Restrictions = Yes,
• si la restriction est active,
• si target carrier et target method sont corrects,
• si les conditions de la restriction sont remplies,
• si la priorité de la règle est correcte,
• si une autre règle avec Stop Processing ne met pas fin au traitement plus tôt.

La taxe Extra Fee ne s’applique pas

Vérifiez :

• si Fee Tax Mode = Calculate by Fee Tax Class,
• si la règle fee dispose de Tax Class ID,
• si la configuration fiscale Magento renvoie un taux de taxe pour l’adresse,
• si le panier possède une adresse de livraison,
• si le fee est effectivement appliqué.

Bonnes pratiques

• Configurez d’abord des règles simples, puis ajoutez des conditions supplémentaires.
• Préparez un panier de test pour chaque règle importante.
• Utilisez des noms lisibles pour les méthodes, les restrictions et les fee.
• Évitez plusieurs règles très similaires avec la même priorité.
• Documentez la raison de création d’une restriction ou d’un fee dans son nom.
• Après modification des attributs produits, effectuez un test de checkout.
• Activez debug logging uniquement pendant le diagnostic.
• Effectuez la migration depuis Amasty par étapes : rapport, dry-run, preview, execute, QA.

Documents associés

• README.md — description technique du module pour les développeurs.
• docs/WDROZENIE.md — documentation détaillée de déploiement et architecture.
• docs/OPIS_MARKETINGOWY.md — description marketing du module.