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

Objectif du document

Ce document décrit la mise en œuvre pratique et l’utilisation du module Kowal_ShippingRules dans Magento 2. Il est destiné 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 des 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 :

app/code/Kowal/ShippingRules

Code du carrier :

kowal_shippingrules

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

kowal_shippingrules_

Exemple :

kowal_shippingrules_dostawa_paletowa

Prérequis avant l’installation

Avant l’installation, il faut confirmer 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 en charge des tests a accès au panneau d’administration et au checkout.

Installation du module

1. Téléchargez le module

Le module doit se trouver dans le répertoire :

app/code/Kowal/ShippingRules

2. Activez le module

bin/magento module:enable Kowal_ShippingRules

Si Kowal_Base n’est pas encore activé, il faut l’activer avant 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 gestion de 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 apparaître dans la liste des modules actifs.

Contrôle après l’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,
• un JSON de conditions invalide,
• des méthodes actives sans tarifs actifs,
• des règles Extra Fee avec tax class lorsque le mode taxe est désactivé.

Si la commande renvoie des erreurs, il ne faut pas basculer le module 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.

Le 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 de secours

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 les comportements lors d’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 la manière de gérer 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 fiscale définie sur la règle fee.

Paramètres par défaut recommandés et 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 de sa propre option de livraison, par exemple :

• livraison sur palette,
• transport spécial,
• livraison locale,
• transporteur pour produits volumineux,
• retrait 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

Puis sélectionnez Add New ou modifiez une méthode existante.

Champs typiques de la méthode :

• Is Active — la méthode est-elle 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 lettres 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 avoir au moins un tarif actif. Si la méthode n’a pas de tarif correspondant, elle n’apparaîtra pas dans le checkout.

Le tarif peut dépendre de :

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

Modes de prix :

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

Exemples :

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

Conditions de la méthode

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

Exemples :

• méthode disponible uniquement pour des produits d’une catégorie donnée,
• méthode disponible uniquement pour un attribut produit précis,
• méthode disponible uniquement pour un panier au-dessus d’une certaine valeur,
• méthode disponible uniquement pour un pays de livraison donné.

Si les conditions sont vides, la méthode est limitée uniquement par son statut, le store view, le customer group et un 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 consigne automatique pour des produits volumineux,
• bloquer l’expédition internationale pour une catégorie donné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 donné.

Création d’une restriction

Accédez à :

Sales / Shipping Methods & Rules / Shipping Restrictions

Puis sélectionnez Add New ou modifiez une restriction existante.

Champs typiques :

• Is Active — la restriction est-elle active.
• 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 pour le client.
• Priority — priorité.
• Stop Processing — faut-il arrêter la vérification des règles suivantes.
• Store Views — portée des store views.
• Customer Groups — portée 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 restrictions évidentes, par exemple un consigne automatique pour des gabarits volumineux.

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 tôt.

Stop Processing = Yes signifie qu’après correspondance de cette restriction, le module ne vérifie plus 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écider définitivement de la disponibilité de la méthode.

Gestion de Extra Fee

Quand utiliser Extra Fee ?

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

Exemples :

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

Création de Extra Fee

Accédez à :

Sales / Shipping Methods & Rules / Extra Fees

Puis sélectionnez Add New ou modifiez des frais existants.

Champs typiques :

• Is Active — les frais sont-ils actifs.
• Name — nom interne.
• Label — nom des frais visible dans totals.
• Target Carrier — carrier concerné par les frais.
• Target Method — méthode concernée par les frais.
• Price Type — type de prix.
• Price — valeur des frais.
• Apply Mode — mode d’application.
• Tax Class ID — classe fiscale si le tax mode est utilisé.
• Priority — priorité.
• Stop Processing — faut-il arrêter l’application des frais suivants.
• Store Views — portée des store views.
• Customer Groups — portée 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 tout le panier.

per_item :

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

per_matching_item :

• frais appliqués uniquement aux produits remplissant 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 sur 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 sur Extra Fee doit toujours être vérifiée en fonction de 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 concerner notamment :

• les attributs des produits,
• 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 choisie.

Exemple de condition pour un produit volumineux

Hypothèse :

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

Règle :

Jeżeli produkt w koszyku ma shipping_type = pallet

Actions possibles :

• afficher la méthode Dostawa paletowa,
• masquer le consigne automatique,
• ajouter les frais Transport gabarytowy.

Recommandations pour travailler avec les conditions

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

Diagnostic et journalisation

Fichier 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 le debug logging activé en permanence en production,
• activez le debug uniquement pendant le diagnostic,
• désactivez le debug après les tests,
• analysez les logs avec le panier de test et la configuration des règles.

Fonctions de secours

Si un problème survient après le déploiement, il est possible de désactiver séparément :

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 ni 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 au transfert de la configuration des restrictions et des extra fees vers Kowal_ShippingRules.

Le module Kowal n’exige 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

Principes de sécurité de la migration

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

• le rapport est read-only,
• le dry-run n’enregistre pas de données,
• apply fonctionne par défaut comme preview,
• l’écriture exige l’option explicite --execute,
• seuls les enregistrements avec le statut ready sont sauvegardé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 automatiquement le trafic.

É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 montre la présence et le volume des tables Amasty ainsi que des tables Kowal.

Étape 2 — dry-run de 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 de unsupported, il faut analyser ces règles avant apply.

Étape 3 — preview apply

Exécutez :

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

Cela n’enregistre toujours pas de données. La commande montre combien d’enregistrements seraient créés, ignorés ou terminés avec une erreur.

Étape 4 — apply des restrictions

Après validation de la preview :

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

La commande n’enregistrera que les restrictions avec le statut ready.

Étape 5 — apply de Extra Fee

Après validation de la preview :

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

La commande n’enregistrera que les extra fees avec 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, il faut comparer les résultats pour des paniers de test.

Paniers recommandés :

• produit standard,
• produit volumineux,
• 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 concernée par Extra Fee.

Pour chaque panier, vérifiez :

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

Étape 8 — décision de bascule

Ce n’est qu’après validation des résultats qu’il est possible de planifier la bascule de la configuration de production.

Recommandations :

• ne désactivez pas Amasty sans sauvegarde,
• ne supprimez pas les données Amasty immédiatement après la migration,
• désactivez d’abord le fonctionnement côté configuration,
• conservez la possibilité de rollback,
• préparez une 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 erreurs,
• setup:di:compile s’est terminé sans erreurs,
• cache:flush exécuté,
• stabilization:check ne renvoie pas d’erreurs,
• le panneau d’administration affiche le menu Shipping Methods & Rules,
• le fichier log est écrit lorsque le debug est activé.

Configuration

• le carrier est activé,
• au moins une méthode d’expédition a été créée,
• la méthode active dispose d’un tarif actif,
• les store views sont correctement définis,
• les customer groups sont correctement définis,
• les restrictions sont activées ou désactivées en connaissance de cause,
• les extra fees sont activés ou désactivés en connaissance de cause,
• le 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 correspondant n’existe,
• la restriction hide masque la méthode,
• la restriction error affiche un message,
• l’extra fee apparaît dans totals après sélection de la méthode,
• le changement de méthode d’expédition recalcule les frais,
• order contient les montants des frais,
• invoice contient les montants des frais,
• creditmemo rembourse correctement les frais.

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 dispose d’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 n’est pas appliqué

Vérifiez :

• si Enable Extra Fees = Yes,
• si les frais sont actifs,
• si target carrier et target method sont corrects,
• si les conditions des frais sont remplies,
• si la méthode d’expédition a été sélectionnée,
• si le montant des frais est supérieur à zéro,
• si Stop Processing d’une règle précédente n’a pas empêché l’application des frais suivants.

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 termine pas le traitement plus tôt.

La taxe sur Extra Fee n’est pas calculée

Vérifiez :

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

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 clairs pour les méthodes, restrictions et fees.
• Évitez plusieurs règles très similaires avec la même priorité.
• Documentez la raison de la création d’une restriction ou d’un fee dans son nom.
• Après avoir modifié les attributs des produits, effectuez un test du checkout.
• N’activez le debug logging que 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.