VibeFox SMSA Express 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.
PHP: 8.1 to 8.4. Live charges need the PHP cURL extension. Without it, the price table is used.
SMSA Express rate card: the prices for the price table come from your SMSA account or the SMSA sales team. Enter them in the base currency of your store, tax excluded. If your rate card is in SAR, AED or another currency, convert it first.
SMSA passKey (for live charges only): live charges use the SMSA web service (SECOM, operation getShipCharges). SMSA issues the passKey on request: ask your SMSA account manager or write to [email protected] and ask for access to the SMSA web service with your account number. The passKey may differ from the API key of the SMSA e-commerce portal. SMSA has no test (sandbox) server for this service. If you only use the price table, you do not need a passKey.
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-smsa-express-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/SmsaExpressShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_SmsaExpressShipping 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 SMSA Express. 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 SMSA Express prices in the Price table. Optionally, under Live rates (API) set Live charges to Yes, enter your SMSA passKey, the ship-from city and country, and, if the base currency of your store is not SAR, the exchange rate. Set Enable to Yes and click Save Config.
The module adds the SMSA Express shipping method to Magento. Customers see it as SMSA Express - Courier delivery (method title and method name). It is off after installation (Enable = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox SMSA Express, 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 also 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 SMSA charges. Amounts accept "9.99" and "9,99". Opening or saving the settings sends no request to SMSA.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field or a price in the Price table that does not contain a number of 0 or more; an Exchange rate of 0; a Currency of SMSA charges that is not a 3-letter code; a Minimum weight (kg) greater than the Maximum weight (kg).
While Enable and Live charges are Yes, warnings after saving tell you about settings that stop live charges: an empty passKey (only the price table is used, or the method is hidden when there are no table prices), an empty ship-from city, a missing exchange rate for charges in the SMSA currency, or an empty price table. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable: shows or hides SMSA Express at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: SMSA Express. Required, at most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Live rates (API) (optional; if SMSA returns no charge, the price table is used)
Live charges: get the shipping charge from SMSA Express. Default: No.
SMSA passKey: the key of the SMSA web service (SECOM). Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved passKey, type a new value to change it. To delete the saved passKey, clear the field and click Save Config. Only the price table is used then. If the log shows "Invalid Passkey", the key is not accepted by this service. Ask SMSA for a web-service passKey.
Ship-from city: the city your parcels are sent from, spelled as SMSA does, for example Riyadh, Jeddah or Dammam. Leave it empty to use the city of Stores > Configuration > Sales > Shipping Settings > Origin.
Ship-from country: the country your parcels are sent from. Leave it empty to use the country of Shipping Settings > Origin.
Shipment type: sent to SMSA as the shipment type. Letters and digits only, at most 10 characters, saved in uppercase. DLV (the default, also used when the field is empty) is standard delivery. Change it only if SMSA gave you another code.
Currency of SMSA charges: SMSA returns every charge with its currency code, usually SAR. A three-letter code; empty uses SAR (the default). A charge in the base currency of your store is used as it is. A charge in this currency is converted with the exchange rate. A charge in any other currency is not used.
Exchange rate: the value of 1 unit of the SMSA currency in the base currency of your store, for example 0.27. Not needed when both currencies are the same. Without it, charges in the SMSA currency are not used and the price table applies. 0 is refused.
Prices (your SMSA Express rate card in the base currency, tax excluded; used when live charges are off, and as the fallback when SMSA returns no charge)
Price table: one row per destination country, with the columns Country, Base, XS, S, M, L and XL. Click Add country to add a row and Delete to remove one. The row * All other countries applies to countries without their own row. The weight columns are 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. An empty or 0 weight column uses the Base price. A Base price of 0 means free shipping. Rows without any price are removed on save. If a country has two rows, the first one is used. If the country has its own row but no price for this weight, Price for countries not in the table is used, not the * row.
Price for countries not in the table: used when the table has no row for the destination country (and no * row) or the row has no price for this weight. Leave it empty to hide the method in that case. 0 means free.
Price applies: how the price is calculated.
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 weight (the sum of product weights). Magento products have no standard dimensions, so volumetric weight is not calculated.
Conditions
Minimum weight (kg): hide the method when the cart weighs less. Empty or 0 means no minimum.
Maximum weight (kg): hide the method when the cart weighs more. Default: 30. Clearing the field saves 0, which means no maximum.
Minimum order amount: show the method only when the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) reaches this amount. Leave empty to always show it.
Free shipping from: the cart subtotal (calculated the same way) from which SMSA Express shipping is free. When the cart reaches it, the price is 0 and no request goes to SMSA. Leave it empty to never offer free shipping.
Availability
Ship to Applicable Countries: All Allowed Countries offers SMSA Express for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries.
The module has no tax field. If your store taxes shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
Advanced
Debug log: writes rate calculations to var/log/vfd_smsa_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged, even when this is off. The passKey and the destination city are never written to the log. Turn the log off when you are done.
Debug log viewer: 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 SMSA Express settings and the log (see Uninstall). When No, the settings and the log are kept. The license key and the cached charges are always removed. Orders are never removed.
How it works at checkout
At the shipping step Magento asks the module for the SMSA Express price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum order amount. If Free shipping from applies, the price is 0 and no request goes to SMSA. A Magento cart price rule with free shipping also makes the price 0; the countries and the other conditions still apply.
With live charges on, the module sends SMSA your ship-from city and country, the customer's city and country, the shipment type, the parcel weight in kg and a cash on delivery amount of 0. SMSA answers with the charge and its currency. The module converts it to the base currency of your store; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it. A live charge is requested only after the customer has entered a delivery address with a city.
Each charge is cached for an hour, so the same cart does not trigger a new request. A failed request is cached for 5 minutes. After a timeout, a server error or an unreadable answer, SMSA is not asked again for 2 minutes. After a rejected key, it is not asked again for 5 minutes. So the checkout never waits for a failing service on every refresh. The request timeout is 12 seconds. The cache is kept encrypted in the Magento database, and the Magento cron removes expired entries every hour.
Whenever SMSA returns no usable charge (no passKey, no city entered yet, missing product weights, an invalid key, a timeout, an error, no service to the city or a currency without an exchange rate), the price table is used. If the table and Price for countries not in the table give no price, the method is hidden. The customer never sees an error. The reason is written to the log.
The module only calculates the shipping price. It does not create SMSA shipments, print AWB labels, handle returns or track parcels. Cash on delivery and its fee are not included in the live charge. There is no SMSA retail point selector: the method is door-to-door delivery.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox SMSA Express is the first row of the VibeFox SMSA Express 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-smsa-express 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 SMSA Express 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
SMSA Express does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Check that the country or the * row has a price, or that Price for countries not in the table is set.
Customers see the table price instead of the SMSA charge: SMSA needs the customer's city, so until it is entered the table price is shown. The table is also used when SMSA does not answer, rejects the key or the city, or returns the charge in a currency without an exchange rate. Turn on Debug log, reload the checkout and look at the Debug log viewer in the Advanced section for the reason.
"Invalid Passkey" in the log: the key is not accepted by the SMSA web service. Ask SMSA for a web-service passKey.
The customer's city is not accepted: SMSA expects its own city spelling. Check the city in the delivery address and the Ship-from city.
The settings are not saved and an error is shown: a number field or a table price contains text or a negative value, the exchange rate is 0, the currency code is not 3 letters, or Minimum weight (kg) is above Maximum weight (kg). Correct the value named in the message and click Save Config again.
Tax is charged twice on shipping: your rate card or SMSA charges may already include VAT. Do not tax shipping in Tax Class for Shipping, or enter prices without VAT.
Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached SMSA charges.
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 and the settings stay. To remove the data, uninstall the module with the Magento command:
Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_SmsaExpressShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_SmsaExpressShipping to remove the data, then bin/magento module:disable Vibefox_SmsaExpressShipping, delete the folder app/code/Vibefox/SmsaExpressShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached charges are always removed. If Remove data on uninstall is Yes, the SMSA Express settings and the log are removed too. If it is No, the settings and the log are kept for a re-install. Orders placed with SMSA Express keep their shipping method and price.
SMSA Express is a trademark of its respective owner. This module is not affiliated with or endorsed by SMSA Express.