VibeFox GIG Logistics 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, with the cURL and JSON extensions.
GIG Logistics API credentials (for live prices only): live prices use the GIG Logistics third-party API. GIG Logistics issues an API username (usually an e-mail address) and password to business customers. Request them on the GIG Logistics developer page (giglogistics.com/developer). Test credentials work only with the test API. If you only use the price table and the fallback cost, you do not need API credentials.
Nigeria in your store: live prices are requested for delivery addresses in Nigeria only, so Nigeria must be one of the countries your store allows (Stores > Configuration > General > General > Country Options > Allow Countries).
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-gig-logistics-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/GigLogisticsShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_GigLogisticsShipping 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 GIG Logistics. 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. Fill in the country prices and/or the fallback cost. For live prices, also enter the API username and password, the sender phone, the pickup city and state, and the currency conversion rate if the base currency of your store is not NGN (see Configuration). Set Enable GIG Logistics to Yes and click Save Config.
The module adds the GIG Logistics shipping method to Magento. Customers see it as GIG Logistics - Courier delivery (method title and method name). It is off after installation (Enable GIG Logistics = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox GIG Logistics, 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. Save Config saves the whole page and clears the cached GIG Logistics prices, API tokens and address coordinates. Amounts accept "9.99" and "9,99".
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; a number field that does not contain a number of 0 or more; a Currency conversion rate of 0; a Pickup latitude outside -90 to 90 or a Pickup longitude outside -180 to 180; a Minimum weight (kg) greater than the Maximum weight (kg).
While Enable GIG Logistics is Yes and API credentials are entered, warnings after saving remind you of settings that stop live prices: GIG Logistics: enter both API username and password., GIG Logistics: enter the sender phone., GIG Logistics: enter the pickup city and state. and GIG Logistics: enter the NGN conversion rate for the base currency. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
The module has no tax field. If your store charges tax on shipping, the tax comes from Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping and is added on top of the GIG Logistics price.
General
Enable GIG Logistics: shows or hides GIG Logistics at checkout. Default: No.
Method title: the shipping method name shown to the customer in the cart and at checkout (the carrier title in Magento). Default: GIG Logistics. 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.
GIG Logistics API (needed for live prices only)
With API credentials, the price is requested from GIG Logistics for every Nigerian address. Without credentials, or when the API gives no price, the fixed prices are used.
API username: your GIG Logistics third-party API username, usually your e-mail address.
API password: your GIG Logistics third-party API password. It is used only to log in to the API and is never logged. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved password, type a new value to change it. To delete the saved password, clear this field or API username and click Save Config.
Test mode: use the GIG Logistics test API host. Test credentials work only with the test API. Set it to No for real prices. Default: No.
Currency conversion rate: GIG Logistics returns prices in NGN. If the base currency of your store is not NGN, enter how many units of the base currency one NGN is worth, for example 0.0006. The rate must be greater than 0. Without it, live GIG prices are not used and the fixed prices apply. Not needed when your base currency is NGN.
Pickup (sender) address
Where GIG Logistics picks up the parcels, in Nigeria. If the country of your shipping origin (Stores > Configuration > Sales > Shipping Settings > Origin) is Nigeria, empty street, city and state fields use the shipping origin address.
Sender name: the sender name sent to GIG Logistics. Empty uses the store name (Stores > Configuration > General > General > Store Information > Store Name).
Sender phone: your phone number, for example 08030000000. Required for live GIG prices.
Pickup street: the pickup street address.
Pickup city: the pickup city or area, for example Victoria Island. Required for live prices.
Pickup latitude: optional map latitude of the pickup point, between -90 and 90, for example 6.4281. GIG Logistics prices by distance. Empty means the coordinates are looked up from the address.
Pickup longitude: optional map longitude of the pickup point, between -180 and 180, for example 3.4219.
Pickup state: the Nigerian state of the pickup address, chosen from the 37 states. The default option, Shipping origin state, uses the state of the shipping origin. Required for live prices.
Address lookup: find map coordinates of the pickup and delivery addresses with OpenStreetMap (Nominatim). GIG Logistics calculates the price from the pickup and delivery coordinates. Entered pickup coordinates are kept. The customer's street, city and state are sent to nominatim.openstreetmap.org, and the results are cached for 30 days. Without it only the address text is sent, and GIG Logistics may not return a price. Default: Yes.
The state of the delivery address is recognised by its code (for example LA or NG-LA) or its name (for example Lagos or Federal Capital Territory) and sent to GIG Logistics and to the address lookup. The module does not add states to Magento. For a live price the delivery address needs a city or a state.
Fixed prices
Used when live GIG prices are unavailable: for other countries, when live prices are not configured, or when GIG Logistics gives no price. Amounts are in the base currency of your store, excluding tax.
Country prices: a table with a base price per country. Click Add country to add a row and Delete to remove one. Choose * All other countries for all countries without their own row. The columns XS (up to 1 kg), S (up to 2 kg), M (up to 3 kg), L (up to 5 kg) and XL (above 5 kg) are optional weight tier prices: a tier price above 0 replaces Base for carts in that tier, an empty or zero tier uses Base. A price of 0 means free shipping. Invalid cells and empty Base cells are saved as 0, so fill in the base price for every row you add. If a country appears twice, the later row is kept. Corrected values are listed in a warning after saving. Countries without a row (when there is no * All other countries row) get no table price.
Fixed price applies: Per order charges the price once. Per item (price × quantity) multiplies it by the number of items in the cart. Live GIG Logistics prices are always per shipment.
Fallback cost: used when neither GIG Logistics nor the table gives a price. Empty hides the method in that case.
Conditions
Minimum weight (kg): hide the method below this cart weight. 0 means no limit.
Maximum weight (kg): hide the method if the cart is heavier. Default: 30. An empty value or 0 means no limit.
Minimum order amount: show the method only when the subtotal of the products that need shipping (after discounts, tax excluded, base currency) is at least this amount. Empty means always.
Free shipping from: delivery is free if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. No request goes to GIG Logistics. Empty means no free shipping threshold.
Ship to Applicable Countries: All Allowed Countries offers GIG Logistics for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Live prices are requested for Nigeria only; other countries use the fixed prices.
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 cart weight is the sum of product weights. Magento products have no standard dimensions, so volumetric weight is not calculated.
Advanced
Debug log: writes price calculations to var/log/vfd_gigl_debug.log.php in the Magento folder. The file cannot be opened from the web. API and address lookup errors are always logged, even when this is off. No password, API token or customer address is written.
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 GIG Logistics settings and the log (see Uninstall). Only the value of the Default Config is used for this. The license key and the cached prices are always removed. Magento orders are never changed.
How it works at checkout
At the shipping step Magento asks the module for the GIG Logistics 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 the subtotal reaches Free shipping from, the price is 0 and no request goes to GIG Logistics. A Magento cart price rule with free shipping also makes the price 0.
Then the price is taken from the first source that gives one. First, the live GIG Logistics price, if API credentials are entered, the address is in Nigeria, the address has a city or state, the sender phone and the pickup city and state are set, and a conversion rate is set for stores whose base currency is not NGN. The module logs in to the GIG Logistics API and sends the pickup and delivery addresses and coordinates and the cart items with names, quantities, weights and values. Products without a weight are sent as 1 kg. The price is requested for bike delivery. Second, the Country prices table. Third, the Fallback cost. If none gives a price, the method is hidden for that cart. The price is calculated in your base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.
Each GIG answer is cached for 1 hour, so the same cart does not trigger a new request. A failed request or a failed login is cached for 10 minutes, so the checkout does not wait for GIG Logistics on every refresh. The login token is kept for 30 minutes and renewed automatically when GIG rejects it. The API timeout is 10 seconds, and the address lookup timeout is 5 seconds. The cached entries are kept in the Magento cache, so Flush Magento Cache in System > Cache Management also clears them.
If GIG Logistics returns an error or a zero price, the customer sees no error. The table or fallback price is used, and the error is written to the debug log.
The module calculates prices only. It does not create GIG Logistics shipments, waybills or labels, book pickups, track parcels or let customers choose a service centre. Orders are shipped through your GIG Logistics account as usual. Live prices are requested for Nigerian addresses only. For other countries, use the price table.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox GIG Logistics is the first row of the VibeFox GIG Logistics 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-gig-logistics 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 GIG Logistics method is not shown to customers at checkout and no price 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
GIG Logistics does not appear at checkout: check that the license is active and Enable GIG Logistics 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 table (the country or * All other countries) or Fallback cost gives a price for the country.
The price comes from the table, not from GIG Logistics: live prices need the API username and password, Sender phone, pickup city and state, a Nigerian delivery address with a city or state, and, for stores whose base currency is not NGN, the Currency conversion rate. Look at the warnings after Save Config. Turn on Debug log, reload the checkout and look at the Log field in the Advanced section to see the reason. A failed request is retried after 10 minutes.
Login failed in the log: GIG Logistics rejected the API username or password. Check them, and check Test mode: test credentials work only with the test API. Click Save Config to retry at once.
GIG Logistics does not return a price: GIG prices by distance. Keep Address lookup on, or enter Pickup latitude and Pickup longitude. Confirm the prices with your GIG Logistics account before going live.
The pickup city and state warning stays: choose a state in Pickup state and fill in Pickup city. The shipping origin address is used only when the shipping origin country is Nigeria.
Tax is charged on top of the GIG price: do not tax shipping in Tax Class for Shipping if the GIG price already includes everything you want to charge.
Prices look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached prices, tokens and coordinates.
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_GigLogisticsShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_GigLogisticsShipping to remove the data, then bin/magento module:disable Vibefox_GigLogisticsShipping, delete the folder app/code/Vibefox/GigLogisticsShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached prices, tokens and coordinates are always removed. If Remove data on uninstall is Yes, the GIG Logistics settings and the log are removed too. If it is No, the settings are kept for a re-install. Magento orders are not changed.
GIG Logistics is a trademark of its respective owner. This module is not affiliated with or endorsed by GIG Logistics.