VibeFox Mondial Relay for Adobe Commerce — المساعدة
Requirements
Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules. The pickup point selection works in the standard Magento checkout (Luma and Blank themes).
PHP: 8.1 to 8.4, with the cURL, JSON, SimpleXML and mbstring extensions.
Mondial Relay account: the brand code (Enseigne) and the Private Key come with a Mondial Relay business account: see the professionals section of mondialrelay.fr, your "Connect" customer area or your sales contact. The map selector needs only the brand code. The list of nearest points needs both.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.
1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-mondialrelay-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/MondialrelayShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_MondialrelayShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Mondial Relay. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).
4. Enter your Brand code (Enseigne) and, for the list of nearest points, the Private Key. Fill in Country prices (or a Fallback cost), set Enable Mondial Relay to Yes and click Save Config.
The module adds the Mondial Relay shipping method to Magento. Customers see it as Mondial Relay - Point Relais (method title and method name). It is off after installation (Enable Mondial Relay = No), and the brand code, the Private Key and the prices are empty. The module creates a table for the pickup points chosen in carts and orders.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Mondial Relay, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name can also be changed for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached pickup point lists. Amounts and weights accept "4.90" and "4,90".
Some values stop the save: Magento shows an error and nothing on the page is saved. This happens for an empty Method title or Method name, one longer than 64 characters or with one of the characters < > ; = # { } (Enter a valid method title or name (1 to 64 characters), without < > ; = # { }.), a brand code with other characters than letters, digits and spaces or longer than 8 characters (The brand code must have at most 8 letters, digits or spaces.), a Sort order that is not a whole number and a Minimum weight (kg) greater than the Maximum weight (kg) (Minimum weight must not be greater than maximum weight.).
A number field with a value that is not a number of 0 or more keeps its previous value, the other fields are saved, and Magento shows the warning Mondial Relay: … is not a valid non-negative number; the previous value is kept. with the field code. Invalid cells of Country prices are cleared and rows with an unknown country are removed, with the warning Mondial Relay: invalid country prices were cleared or their rows removed.
While Enable Mondial Relay is Yes, saving the page also shows warnings for settings that hide the method: Mondial Relay: enter the brand code to enable pickup point selection., Mondial Relay: list mode requires the Private Key. and Mondial Relay: no price for followed by the countries among France, Belgium and Spain that have no price. When the brand code and the Private Key are both set, the module tests them with the Mondial Relay Web Service and shows Mondial Relay Web Service: the brand code and Private Key are valid. or Mondial Relay Web Service: followed by the error. The warnings and the test run only while the method is enabled and only when its own settings are saved, because the Delivery Methods page is shared by all shipping methods.
General
Enable Mondial Relay: shows or hides Mondial Relay at checkout. Default: No. The method is shown only when a pickup point selector and a price are configured.
Method title: the carrier name shown in the cart and at checkout. Default: Mondial Relay. Required, at most 64 characters, without < > ; = # { }.
Method name: shown after the method title, as "Method title - Method name". Default: Point Relais. Required, with the same rules.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Mondial Relay account
Brand code (Enseigne): at most 8 letters, digits or spaces. It is uppercased and padded to 8 characters when used. Used by the pickup point map and by the Web Service. Without it customers cannot choose a Point Relais, so the method is not shown at checkout.
Private Key: required for the list of nearest points and for the account test. It is used only to sign the Web Service requests and is never sent to the browser. It is stored encrypted and the field shows only a mask after saving. Leave the mask unchanged to keep the saved key, type a new value to replace it. To delete the saved key, clear the field and click Save Config.
Pickup point selector: how the customer chooses a Point Relais.
Rates
Prices are entered in the base currency of your store, tax excluded. Magento shows the price to the customer in the customer's currency. Mondial Relay has no public rate API, so the price always comes from this section. The module has no tax field: if your store taxes shipping, Magento adds tax with the class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
Country prices: price by destination country and parcel weight. Click Add country to add a row and Delete to remove one. Each row has a Country (or * All other countries), a Price and five weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. The row of the country is used first, then the first * All other countries row. A weight column left empty or at 0 uses the Price column. If Price is empty too, the delivery for that weight is free, so fill in Price when you use only some weight columns. Rows without any price are dropped when you save.
Calculation type: how the price is counted.
Fallback cost: used when no country row and no * All other countries row matches. Leave it empty to hide the method for such countries.
Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which the delivery is free. It applies only after a price has been found: without a price the method stays hidden. Leave it empty for no free shipping.
Availability
Minimum weight (kg): hide the method when the cart weighs less. 0 means no minimum.
Maximum weight (kg): hide the method when the cart weighs more. Mondial Relay accepts parcels up to 30 kg in Points Relais. Default: 30. An empty field restores 30 kg, an explicit 0 disables the limit.
Minimum subtotal: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. Leave it empty to always show it.
Ship to Applicable Countries: All Allowed Countries offers Mondial Relay for all six supported countries that your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Mondial Relay supports France, Belgium, Luxembourg, Spain, Portugal and the Netherlands. This list can only narrow them: other countries are never offered, even if you select them.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). The price uses the actual cart weight (the sum of product weights). Magento products have no standard dimensions, so volumetric weight is not calculated.
Advanced
Debug log: writes rate calculations and Web Service calls to var/log/vfd_mrel_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Errors are always logged, even when this is off. The Private Key and the customer address are not logged.
Log: shows the size and the latest entries of the log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the settings and the log too (see Uninstall). Default: No. The license and the cached pickup point lists are always removed. The pickup points saved in orders are always kept.
How it works at checkout
The method is offered only for countries with Points Relais: France, Belgium, Luxembourg, Spain, Portugal and the Netherlands. It is hidden when customers could not choose a point: without a brand code, or in list mode without the Private Key.
At the shipping step Magento asks the module for the price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks the cart weight and the Minimum subtotal. The price comes from the row of the country (or the * All other countries row): the weight column, else Price. Without a row, the fallback cost is used. If there is no price, the method is hidden. If the subtotal reaches Free shipping from, the price becomes 0. A Magento cart price rule with free shipping also makes the price 0. The price is calculated in the base currency and shown in the customer's currency.
The module does not request live rates: Mondial Relay has no public rate API. It does not create shipments, print labels or track parcels. Create the shipments in your Mondial Relay "Connect" space using the Point Relais number shown in the order. Home delivery is not offered. The pickup point selector is part of the standard Magento checkout only: other checkouts (for example Hyvä), checkout with multiple addresses and orders created in the Admin do not show it.
Pickup points
When the customer selects Mondial Relay at the shipping step, a Mondial Relay pickup point box appears under the shipping methods.
Map mode: the button Choose a Point Relais on the map opens the official Mondial Relay map in a window (Choose a Mondial Relay pickup point) for the delivery country, postcode and parcel weight. After the customer picks a point, the window closes and the box shows the point name and address with its number, for example (FR-066974). The map runs in a page of your store inside the window. It loads the Mondial Relay script from widget.mondialrelay.com and the Leaflet map library from unpkg.com only when the customer opens the map, and the map loads point data and map tiles from Mondial Relay and OpenStreetMap. These services receive the usual request data of the visitor (IP address, browser). Mention this in your privacy policy. The module adds these addresses to the Magento content security policy.
List mode: a drop-down Choose a Point Relais shows the 10 nearest points for the delivery postcode, with their distance. The chosen point is shown with its opening hours. Refresh pickup points loads the list again. The list is loaded by your server, so no third-party script runs in the browser for it. Lists are cached for 12 hours, an empty answer for 1 hour, and a failed request is remembered for 5 minutes. The Web Service timeout is 10 seconds. If the list is unavailable or empty, the customer sees The point list is unavailable or empty. Please choose a Point Relais on the map. and can use the map button, which is shown in both modes.
The chosen point is saved to the cart at once, so it stays after the shipping step refreshes or the page reloads. If the shipping address changes to another country, the customer has to choose a point again. A point is required. Without one, the customer cannot click past Next and sees Please choose a Mondial Relay pickup point. A point in another country than the delivery address is refused with The Mondial Relay point is not in the delivery country. In list mode the point is also checked against the list for the address; a point that is not in it is refused with The Mondial Relay point is not available for this address. Please choose it again. If the Web Service fails, a point chosen on the map is kept. If the map cannot be loaded, the customer sees The Mondial Relay map could not be loaded. Please try again or choose another shipping method. The server checks the point and its country again when the shipping step is saved and when the order is placed.
When the order is placed, the point stays with the order and no longer changes with the cart. If the customer cancels the payment on the payment provider's page and Magento restores the cart, the customer can choose a Point Relais again for the new order. The earlier order keeps its own point. The shipping address of the order is not changed.
Shipping description: the point name, address and number are added to the shipping description of the order, for example Mondial Relay - Point Relais: followed by the point name and address and (FR-066974). The number is kept even when the text has to be shortened. This text is shown in the order in the customer account, in the order e-mails and on invoices.
Admin order page: on Sales > Orders > View, Information tab, a Mondial Relay pickup point block shows the point name and address, the Point Relais number (for example FR-066974) and Verified against the point list or Selected on the map. The block also works for older orders and when the module is switched off. The point cannot be changed in the Admin. If a Mondial Relay order has no point, the block shows No Point Relais was saved for this order.
Customer: the Mondial Relay pickup point box with the point and its number is shown in the order view in the customer account and, for guests, in Orders and Returns.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Mondial Relay is the first row of the VibeFox Mondial Relay group in Stores > Configuration > Sales > Delivery Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-shipping-mondialrelay and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Mondial Relay method is not shown to customers at checkout and no rate is calculated. The Magento storefront does not know that you are logged in to the Admin, so the method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.
Troubleshooting
Mondial Relay does not appear at checkout: check that the license is active and Enable Mondial Relay is Yes for the website of the store. Check that the shipping country is one of the six Mondial Relay countries and is allowed by Ship to Applicable Countries and Ship to Specific Countries. Save the settings and read the warnings: the method is hidden without a brand code, in list mode without the Private Key and for a country without a price. Check the weight limits and Minimum subtotal. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section to see the reason.
Web Service test failed after saving: the message Mondial Relay Web Service: shows the Mondial Relay error, for example an invalid brand code or an invalid security key. Check the brand code and the Private Key with Mondial Relay.
The list of points is empty or not available: the customer needs a delivery postcode first. If the Web Service fails, the map is offered instead. Turn on Debug log, reload the checkout and look at the Log field for the reason.
The map does not open: the map is loaded from widget.mondialrelay.com and unpkg.com. Check that a privacy or script blocker does not block them. If your store adds its own content security policy rules, allow these addresses and the resources the Mondial Relay map loads.
Delivery is free for a country by mistake: check the row of that country in Country prices. A row where Price and the weight column for the cart weight are empty or 0 gives free delivery.
An order created in the Admin with Mondial Relay cannot be placed: the Admin order form has no pickup point selector, and the module refuses to place a Mondial Relay order without a checked point, so Magento shows a Mondial Relay error. Choose another shipping method for such orders.
The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.
Uninstall
Deleting the module code alone removes nothing from the database: the license key, the settings and the pickup points stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_MondialrelayShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_MondialrelayShipping to remove the data, then bin/magento module:disable Vibefox_MondialrelayShipping, delete the folder app/code/Vibefox/MondialrelayShipping and run bin/magento setup:upgrade.
The license key, the license status, the cached pickup point lists and the points of carts without an order are always removed. If Remove data on uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a re-install. The pickup point table and the points saved in orders are always kept, and the shipping description of the orders does not change.
Mondial Relay is a trademark of its respective owner. This module is not affiliated with or endorsed by Mondial Relay.