Kowal ShippingRules — handleiding voor installatie, configuratie en gebruik

Doel van het document

Dit document beschrijft de praktische implementatie en het gebruik van de module Kowal_ShippingRules in Magento 2. Het is bedoeld voor personen die verantwoordelijk zijn voor de installatie van de module, winkelconfiguratie, implementatietests en dagelijks beheer van verzendregels.

Het document omvat:

• installatie van de module,
• basisconfiguratie,
• aanmaken van verzendmethoden,
• configuratie van tarieven,
• beheer van beperkingen voor leveringsmethoden,
• beheer van extra kosten Extra Fee,
• diagnostiek,
• migratie vanaf Amasty-modules,
• checklist voor tests na implementatie.

Basisinformatie

Technische naam van de module:

Kowal_ShippingRules

Locatie van de module:

vendor/kowal/module-shipping-rules

Carrier-code:

kowal_shippingrules

De code van de verzendmethode in checkout heeft het formaat:

kowal_shippingrules_

Voorbeeld:

kowal_shippingrules_dostawa_paletowa

Vereisten vóór installatie

Controleer vóór installatie of:

• de winkel draait op Magento 2.4.x,
• de omgeving PHP >=8.1 gebruikt,
• de module Kowal_Base beschikbaar is,
• er een back-up van bestanden en database is gemaakt,
• de implementatie eerst wordt uitgevoerd op een test- of stagingomgeving,
• na installatie setup:upgrade en setup:di:compile kunnen worden uitgevoerd,
• de tester toegang heeft tot het admin panel en de checkout.

Installatie van de module

Installatie via Composer

De toegangsgegevens voor de Composer-repository, het e-mailadres van de klant en de licentietoken, ontvangt u per e-mail na aankoop. Ze zijn ook beschikbaar in het klantpaneel na inloggen op kowal.store. Vervang TWOJ_EMAIL_KLIENTA door het e-mailadres van uw account en TWOJ_TOKEN door de ontvangen token. Voer de opdrachten uit in de hoofdmap van 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. Schakel de module in

bin/magento module:enable Kowal_ShippingRules

Als Kowal_Base nog niet is ingeschakeld, moet deze eerder of samen met de module worden ingeschakeld:

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Werk de database bij

bin/magento setup:upgrade

Deze opdracht maakt de module-tabellen aan en voegt kolommen toe die nodig zijn voor ondersteuning van Extra Fee in quote, order, invoice en creditmemo.

4. Compileer DI

In productie:

bin/magento setup:di:compile

5. Leeg de cache

bin/magento cache:flush

6. Controleer de modulestatus

bin/magento module:status Kowal_ShippingRules

De module moet op de lijst met actieve modules staan.

Controle na installatie

Voer na installatie de diagnostiek uit:

bin/magento kowal:shippingrules:stabilization:check

Volledige variant in JSON:

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

De opdracht is read-only en wijzigt geen gegevens. Deze controleert onder andere:

• aanwezigheid van module-tabellen,
• aantal records,
• onjuiste JSON van voorwaarden,
• actieve methoden zonder actieve tarieven,
• Extra Fee-regels met tax class bij uitgeschakelde belastingmodus.

Als de opdracht fouten retourneert, mag de module niet voor productiegebruik worden ingeschakeld voordat deze zijn verklaard.

Basisconfiguratie

Carrier

Pad in het Magento panel:

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

Velden:

• Enabled — schakelt de carrier kowal_shippingrules in of uit.
• Title — naam van de methodengroep die zichtbaar is in checkout.
• Test Method Name — naam van de testconfiguratiemethode.
• Test Method Price — prijs van de testconfiguratiemethode.
• Sort Order — volgorde van de carrier op de lijst met leveringsmethoden.
• Show Method If Not Applicable — of een fout moet worden getoond wanneer er geen beschikbare methoden zijn.
• Displayed Error Message — melding wanneer de methode niet beschikbaar is.

Belangrijkste instelling:

carriers/kowal_shippingrules/active = 1

Als de carrier is uitgeschakeld, zijn de in de module aangemaakte methoden niet beschikbaar in checkout.

Diagnostiek en noodfuncties

Pad in het Magento panel:

Stores / Configuration / Sales / Shipping Methods & Rules

Sectie General Diagnostics:

• Enable Debug Logging — slaat details van beslissingen op in het log.
• Shadow Mode — modus die is voorbereid om gedrag tijdens migratie te vergelijken.

Sectie Restrictions:

• Enable Restrictions — schakelt alleen beperkingen in of uit.

Sectie Extra Fees:

• Enable Extra Fees — schakelt alleen extra kosten in of uit.
• Fee Tax Mode — bepaalt de manier waarop belasting voor Extra Fee wordt verwerkt.

Beschikbare belastingmodi:

• Do Not Calculate Tax — de module berekent geen belasting over Extra Fee.
• Calculate by Fee Tax Class — de module berekent belasting volgens de belastingklasse die op de fee-regel is ingesteld.

Standaard, veilige instellingen:

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

Modulemenu in het panel

Pad:

Sales / Shipping Methods & Rules

Beschikbare secties:

• Shipping Methods — verzendmethoden en tarieven,
• Shipping Restrictions — beperkingen voor leveringsmethoden,
• Extra Fees — extra kosten.

Beheer van verzendmethoden

Wanneer maakt u een verzendmethode aan?

Maak een verzendmethode aan wanneer de winkel een eigen leveringsoptie nodig heeft, bijvoorbeeld:

• palletlevering,
• speciaal transport,
• lokale levering,
• koerier voor grote producten,
• logistieke afhaling,
• methode die alleen beschikbaar is voor geselecteerde producten of regio's.

Methode aanmaken

Ga naar:

Sales / Shipping Methods & Rules / Shipping Methods

Kies vervolgens Add New of bewerk een bestaande methode.

Typische methodevelden:

• Is Active — of de methode actief is.
• Code — technische code van de methode.
• Name — naam zichtbaar voor de klant.
• Description — beschrijving van de methode.
• Sort Order — weergavevolgorde.
• Store Views — zichtbaarheid voor store view.
• Customer Groups — zichtbaarheid voor klantgroepen.
• Conditions — voorwaarden voor beschikbaarheid van de methode.

Aanbevelingen voor het veld Code:

• gebruik kleine letters,
• gebruik geen Poolse tekens,
• gebruik geen spaties,
• gebruik underscores in plaats van spaties.

Voorbeelden:

dostawa_paletowatransport_specjalnykurier_gabarytdostawa_lokalna

De volledige methodecode in checkout krijgt de carrier-prefix:

kowal_shippingrules_dostawa_paletowa

Tarieven van de methode

Een actieve methode moet ten minste één actief tarief hebben. Als een methode geen passend tarief heeft, verschijnt deze niet in checkout.

Een tarief kan afhankelijk zijn van:

• land,
• regio,
• postcode,
• winkelwagenwaarde,
• gewicht,
• aantal producten,
• verzendtype,
• prioriteit.

Prijsmodi:

• fixed — vaste prijs,
• percent_subtotal — percentage van het subtotaal.

Voorbeelden:

• prijs 29 zł voor zendingen tot 30 kg,
• prijs 149 zł voor palletlevering,
• 5% van de winkelwagenwaarde voor speciaal transport,
• apart tarief voor geselecteerde postcodes.

Voorwaarden van de methode

Voorwaarden bepalen wanneer de methode beschikbaar moet zijn.

Voorbeelden:

• methode alleen beschikbaar voor producten uit een geselecteerde categorie,
• methode alleen beschikbaar bij een specifiek productattribuut,
• methode alleen beschikbaar voor een winkelwagen boven een bepaalde waarde,
• methode alleen beschikbaar voor een geselecteerd land van levering.

Als de voorwaarden leeg zijn, wordt de methode alleen beperkt door status, store view, customer group en een passend tarief.

Beheer van beperkingen voor leveringsmethoden

Wanneer gebruikt u beperkingen?

Beperkingen worden gebruikt om verzendmethoden te verbergen of te blokkeren die niet beschikbaar zouden moeten zijn voor een specifieke bestelling.

Voorbeelden:

• verberg pakketautomaat voor grote producten,
• blokkeer internationale verzending voor een geselecteerde categorie,
• toon een melding dat expressvervoer niet beschikbaar is voor producten op bestelling,
• verberg de leveringsmethode voor een geselecteerd land.

Beperking aanmaken

Ga naar:

Sales / Shipping Methods & Rules / Shipping Restrictions

Kies vervolgens Add New of bewerk een bestaande beperking.

Typische velden:

• Is Active — of de beperking werkt.
• Name — interne naam.
• Target Carrier — carrier waarop de beperking betrekking heeft.
• Target Method — methode waarop de beperking betrekking heeft.
• Action — werkwijze.
• Message — melding voor de klant.
• Priority — prioriteit.
• Stop Processing — of verdere controle van regels moet worden gestopt.
• Store Views — bereik van store view.
• Customer Groups — bereik van klantgroepen.
• Conditions — matchvoorwaarden.

Acties van beperkingen

hide:

• de methode wordt verborgen,
• de klant ziet deze niet,
• geschikt voor duidelijke beperkingen, bijvoorbeeld pakketautomaat voor grote pakketten.

error:

• de methode wordt weergegeven als niet beschikbaar,
• de klant ziet een melding,
• geschikt wanneer het nuttig is om de reden van onbeschikbaarheid uit te leggen.

Prioriteit en Stop Processing

Regels worden gecontroleerd op basis van prioriteit. Een hogere prioriteit betekent eerdere controle.

Stop Processing = Yes betekent dat de module na matchen van deze beperking geen volgende beperkingen voor deze methode controleert.

Aanbeveling:

• gebruik hogere prioriteiten voor specifiekere regels,
• gebruik lagere prioriteiten voor algemene regels,
• schakel Stop Processing in als de regel definitief moet beslissen over de beschikbaarheid van de methode.

Beheer van Extra Fee

Wanneer gebruikt u Extra Fee?

Extra Fee wordt gebruikt om extra kosten aan de bestelling toe te voegen.

Voorbeelden:

• kosten voor niet-standaard verpakking,
• toeslag voor groot transport,
• kosten voor kwetsbare producten,
• logistieke kosten voor een specifieke leveringsmethode,
• toeslag voor geselecteerde regio's.

Extra Fee aanmaken

Ga naar:

Sales / Shipping Methods & Rules / Extra Fees

Kies vervolgens Add New of bewerk een bestaande kost.

Typische velden:

• Is Active — of de fee werkt.
• Name — interne naam.
• Label — naam van de kosten zichtbaar in totals.
• Target Carrier — carrier waarop de fee betrekking heeft.
• Target Method — methode waarop de fee betrekking heeft.
• Price Type — prijstype.
• Price — waarde van de kosten.
• Apply Mode — berekeningswijze.
• Tax Class ID — belastingklasse als tax mode wordt gebruikt.
• Priority — prioriteit.
• Stop Processing — of verdere berekening van fee moet worden gestopt.
• Store Views — bereik van store view.
• Customer Groups — bereik van klantgroepen.
• Conditions — voorwaarden voor berekening.

Prijsmodi

fixed:

• vast bedrag,
• bijvoorbeeld 19 zł voor verpakking.

percent_subtotal:

• percentage van de winkelwagenwaarde,
• bijvoorbeeld 3% van de bestelwaarde.

Berekeningsmodi

cart:

• één kost voor de hele winkelwagen.

per_item:

• kosten vermenigvuldigd met het aantal producten.

per_matching_item:

• kosten worden alleen berekend voor producten die aan de voorwaarden voldoen.

Voorbeeld:

Als de kosten voor speciale beveiliging 5 zł bedragen en er 3 producten in de winkelwagen zijn die aan de voorwaarde voldoen, berekent de modus per_matching_item 15 zł.

Belasting op Extra Fee

Standaard wordt er geen belasting over Extra Fee berekend:

kowal_shippingrules/fees/tax_mode = none

Om belasting te berekenen:

1. Stel Fee Tax Mode in op Calculate by Fee Tax Class.
2. Vul Tax Class ID in op de Extra Fee-regel.
3. Test winkelwagen, order, invoice en creditmemo.

Belasting op Extra Fee moet altijd worden gecontroleerd met de belastingconfiguratie van de specifieke winkel.

Beheer van voorwaarden

De module gebruikt een voorwaardengenerator die lijkt op Magento-regels.

Voorwaarden kunnen onder andere betrekking hebben op:

• productattributen,
• SKU,
• categorieën,
• producttype,
• gewicht,
• prijs,
• winkelwagenwaarde,
• aantal producten,
• land van levering,
• regio,
• plaats,
• postcode,
• coupon,
• geselecteerde verzendmethode.

Voorbeeld van een voorwaarde voor een groot product

Uitgangspunt:

• het product heeft het attribuut shipping_type,
• de waarde voor groot formaat is pallet.

Regel:

Jeżeli produkt w koszyku ma shipping_type = pallet

Mogelijke acties:

• toon de methode Dostawa paletowa,
• verberg pakketautomaat,
• bereken fee Transport gabarytowy.

Aanbevelingen bij het werken met voorwaarden

• maak eerst een eenvoudige regel en test deze in de winkelwagen,
• vermijd te veel voorwaarden in één regel,
• geef regels duidelijke namen,
• gebruik voor belangrijke regels eenduidige productattributen,
• test de winkelwagen opnieuw na wijziging van productattributen.

Diagnostiek en logging

Dedicated logbestand:

var/log/kowal_shipping_rules.log

Debug kan worden ingeschakeld in:

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

Schakel in:

Enable Debug Logging = Yes

Aanbevelingen:

• laat debug logging niet permanent ingeschakeld in productie,
• schakel debug alleen in tijdens diagnose,
• schakel debug uit na afronding van tests,
• analyseer logs samen met de testwinkelwagen en regelconfiguratie.

Noodfuncties

Als er na implementatie een probleem optreedt, kunt u onafhankelijk uitschakelen:

De volledige carrier

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

Effect:

• methoden van de carrier kowal_shippingrules zijn niet beschikbaar.

Alleen beperkingen

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

Effect:

• methoden worden niet verborgen of geblokkeerd door beperkingen.

Alleen Extra Fee

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

Effect:

• extra kosten worden niet berekend.

Migratie vanaf Amasty

Doel van de migratie

Migratie vanaf Amasty is bedoeld om de configuratie van beperkingen en extra fee over te brengen naar Kowal_ShippingRules.

De Kowal-module vereist Amasty niet voor normaal gebruik. Amasty kan worden gebruikt als bron van migratiegegevens en als referentiepunt tijdens tests.

Ondersteunde gegevensbronnen

De migrator analyseert:

amasty_shiprestriction_ruleamasty_extrafeeamasty_extrafee_option

Doeltabellen:

kowal_shipping_restrictionkowal_shipping_fee

Veiligheidsregels voor migratie

De migratie is voorzichtig ontworpen:

• het rapport is read-only,
• dry-run slaat geen gegevens op,
• apply werkt standaard als preview,
• opslaan vereist de expliciete optie --execute,
• alleen records met status ready worden opgeslagen,
• records manual_review en unsupported worden overgeslagen,
• de migratie is idempotent dankzij de velden migration_source en migration_source_key,
• de migratie schakelt Amasty niet uit,
• de migratie schakelt verkeer niet automatisch om.

Stap 1 — basisrapport

Voer uit:

bin/magento kowal:shippingrules:amasty:report

Het rapport wordt opgeslagen in:

var/report/kowal_shippingrules_amasty_report.json

Het rapport toont de aanwezigheid en aantallen van Amasty-tabellen en Kowal-tabellen.

Stap 2 — dry-run van transformatie

Voer uit:

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

Dry-run bereidt een transformatieplan voor, maar slaat niets op.

Recordstatussen:

• ready — record kan automatisch worden overgezet,
• manual_review — record vereist handmatige analyse,
• unsupported — record wordt niet ondersteund door de automatische migrator.

Als het rapport veel manual_review of unsupported bevat, moeten deze regels vóór apply worden geanalyseerd.

Stap 3 — preview apply

Voer uit:

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

Ook dit slaat nog geen gegevens op. De opdracht toont hoeveel records zouden worden aangemaakt, overgeslagen of met een fout eindigen.

Stap 4 — apply van beperkingen

Na acceptatie van de preview:

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

De opdracht slaat alleen beperkingen met status ready op.

Stap 5 — apply van Extra Fee

Na acceptatie van de preview:

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

De opdracht slaat alleen extra fees met status ready op.

Stap 6 — diagnostiek na migratie

Voer uit:

bin/magento kowal:shippingrules:stabilization:check

Controleer ook het panel:

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

Stap 7 — vergelijkingstests met Amasty

Voordat de Amasty-configuratie wordt uitgeschakeld of vervangen, moeten de resultaten voor testwinkelwagens worden vergeleken.

Aanbevolen winkelwagens:

• standaardproduct,
• groot product,
• kwetsbaar product,
• meerdere producten met verschillende voorwaarden,
• bestelling met verschillende landen van levering,
• bestelling met verschillende postcodes,
• bestelling met coupon,
• bestelling met geselecteerde methode waarop Extra Fee van toepassing is.

Controleer voor elke winkelwagen:

• beschikbare leveringsmethoden,
• verborgen methoden,
• foutmeldingen,
• berekende extra fee,
• bruto-/nettobedragen, als tax fee wordt gebruikt,
• order,
• invoice,
• creditmemo.

Stap 8 — beslissing over omschakeling

Pas na acceptatie van de resultaten kan de omschakeling van de productieconfiguratie worden gepland.

Aanbevelingen:

• schakel Amasty niet uit zonder back-up,
• verwijder Amasty-gegevens niet direct na migratie,
• schakel eerst de werking aan de configuratiezijde uit,
• behoud de mogelijkheid tot rollback,
• maak een lijst met regels die handmatige correctie vereisen.

Rollback na migratie

Als er een probleem optreedt:

1. Schakel carrier Kowal ShippingRules uit.
2. Schakel Enable Restrictions uit.
3. Schakel Enable Extra Fees uit.
4. Herstel de bestaande Amasty-configuratie.
5. Controleer checkout.
6. Bewaar migratierapporten voor analyse.

Checklist na implementatie

Technisch

• module:status toont Kowal_ShippingRules als actief,
• setup:upgrade is zonder fouten voltooid,
• setup:di:compile is zonder fouten voltooid,
• cache:flush is uitgevoerd,
• stabilization:check retourneert geen fouten,
• het admin panel toont het menu Shipping Methods & Rules,
• het logbestand wordt geschreven bij ingeschakelde debug.

Configuratie

• carrier is ingeschakeld,
• er is ten minste één verzendmethode aangemaakt,
• de actieve methode heeft een actief tarief,
• store views zijn correct ingesteld,
• customer groups zijn correct ingesteld,
• beperkingen zijn ingeschakeld of bewust uitgeschakeld,
• extra fees zijn ingeschakeld of bewust uitgeschakeld,
• tax mode is in overeenstemming met de belastingconfiguratie van de winkel.

Checkout

• de methode verschijnt voor een winkelwagen die aan de voorwaarden voldoet,
• de methode verschijnt niet wanneer er geen passend tarief is,
• beperking hide verbergt de methode,
• beperking error toont een melding,
• extra fee verschijnt in totals na selectie van de methode,
• wijziging van verzendmethode herberekent fee,
• order bevat fee-bedragen,
• invoice bevat fee-bedragen,
• creditmemo restitueert fee correct.

Meest voorkomende problemen

Methode verschijnt niet in checkout

Controleer:

• of de carrier is ingeschakeld,
• of de methode actief is,
• of de methode een actief tarief heeft,
• of het tarief past bij land, regio, postcode, gewicht en subtotaal,
• of store view correct is,
• of customer group correct is,
• of aan de methodevoorwaarden is voldaan,
• of een beperking de methode niet verbergt.

Extra Fee wordt niet berekend

Controleer:

• of Enable Extra Fees = Yes,
• of de fee actief is,
• of target carrier en target method correct zijn,
• of aan de fee-voorwaarden is voldaan,
• of er een verzendmethode is geselecteerd,
• of de fee-prijs groter is dan nul,
• of Stop Processing van een eerdere regel verdere berekening niet heeft gestopt.

Beperking werkt niet

Controleer:

• of Enable Restrictions = Yes,
• of de beperking actief is,
• of target carrier en target method correct zijn,
• of aan de beperkingsvoorwaarden is voldaan,
• of de prioriteit van de regel juist is,
• of een andere regel met Stop Processing de verwerking niet eerder beëindigt.

Belasting op Extra Fee wordt niet berekend

Controleer:

• of Fee Tax Mode = Calculate by Fee Tax Class,
• of de fee-regel een ingestelde Tax Class ID heeft,
• of de belastingconfiguratie van Magento een belastingtarief voor het adres retourneert,
• of de winkelwagen een afleveradres heeft,
• of de fee daadwerkelijk is berekend.

Best practices

• Configureer eerst eenvoudige regels en voeg daarna volgende voorwaarden toe.
• Bereid voor elke belangrijke regel een testwinkelwagen voor.
• Gebruik duidelijke namen voor methoden, beperkingen en fee.
• Vermijd meerdere sterk vergelijkbare regels met dezelfde prioriteit.
• Documenteer de reden voor het aanmaken van een beperking of fee in de naam.
• Voer na wijziging van productattributen een checkout-test uit.
• Schakel debug logging alleen in tijdens diagnose.
• Voer migratie vanaf Amasty gefaseerd uit: rapport, dry-run, preview, execute, QA.

Gerelateerde documenten

• README.md — technische beschrijving van de module voor ontwikkelaars.
• docs/WDROZENIE.md — gedetailleerde implementatiedocumentatie en architectuur.
• docs/OPIS_MARKETINGOWY.md — marketingbeschrijving van de module.