VibeFox Frenet for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

Frenet account (for live quotes only): create a free account in the Frenet panel (painel.frenet.com.br), enable the carriers you use and copy your API token. If you only use fixed prices, you do not need a Frenet account.

Products: fill in weight and dimensions for accurate prices. Products without them are quoted as 0.3 kg and 16 × 11 × 2 cm (the minimum Correios box).

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_frenet-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_frenet.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_frenet-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Frenet and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

4. Paste your VibeFox license key into License key in the license block at the top of the Edit page and click Activate (see License key).

5. Paste the API token and enter the origin CEP. If your default currency is not BRL, enter the BRL exchange rate. Optionally add fixed prices and a fallback cost. Turn on Enable Frenet and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_frenet.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox Frenet, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 and 5 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn on Enable Frenet and save. If you install the extension again after an uninstall, the Frenet settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached Frenet quotes. Price fields accept both a point and a comma as the decimal separator. If a value is wrong, nothing is saved and the page shows the reason, for example Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. or "…" must not be negative. A BRL exchange rate of 0 or less and a Minimum weight (kg) above the Maximum weight (kg) are rejected too. Only admin users with the modify permission for this extension can save the settings.

At the top of the page, and again after each save, the extension shows warnings: no API token (only fixed prices are used, or the method is never shown if there are no fixed prices either), no origin CEP, an origin CEP without 8 digits, or a default currency other than BRL without an exchange rate. It also warns when your store has no weight class with the unit kg or no length class with the unit cm. Product weights and dimensions are then converted by the unit name of their class, and unknown units are read as kg or cm. Check System > Localisation > Weight Classes and Length Classes.

General

The settings apply to every geo zone. You can limit the method to a geo zone in Conditions, or use Ignore shipping zones. The price always comes from this extension.

Enable Frenet: shows or hides Frenet at checkout. Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout. Default: Frenet. Required, 64 characters at most, without the characters < > ; = # { }.

Sort order: the position of Frenet among the shipping methods at checkout. A whole number.

Frenet live quotes

Frenet compares the carriers enabled in your Frenet account (Correios, Jadlog, Loggi and others) and returns their prices for the cart. Live quotes are requested only for addresses in Brazil with a full 8-digit CEP. The section has a link to the Frenet panel.

API token: your Frenet API token from the Frenet panel. Leave it empty to use fixed prices only. After saving, the field stays empty and shows A token is saved — leave empty to keep it. Type a new value only to change it. To delete the saved token, tick Remove the saved token and save.

Origin CEP: the postal code (CEP) the parcels are shipped from, for example 01001-000. OpenCart has no store postcode, so live quotes need this field. A CEP without 8 digits is saved as typed, and the page shows Frenet: the origin CEP must have 8 digits.

Service to offer: Cheapest service (default) or Fastest service. Frenet returns several services, and the method shows one price. The chosen carrier, service and delivery time are saved with the order.

BRL exchange rate: Frenet quotes in Brazilian reais. If your default currency is not BRL, enter how much 1 BRL is in your default currency, for example 0.16. The quote and the declared order value are converted with it. Without it live quotes are not used. When your default currency is BRL, the field says that Frenet prices are used as they are.

Fixed prices

Used when there is no API token, for countries Frenet does not serve, and whenever Frenet returns no price (API down, CEP not served).

Price per country: a table with the columns Country, Price, XS, S, M, L and XL, prices in your default currency, tax excluded. Click Add country to add a row. The size columns depend on the cart weight: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg, XL above 5 kg. Price is used when the size column is empty. A Price of 0 means free shipping for that country. Use * Default (all other countries) for all countries without their own row. Rows without any price are removed when you save.

Fallback cost: used when neither Frenet nor the table gives a price. Leave it empty to hide the method.

Fixed price applies: Per order (default) charges the price once. Per item (price × quantity) multiplies it by the number of items. This applies only to fixed prices and the fallback cost. Frenet quotes already cover the whole cart.

Conditions

Minimum weight (kg): hide the method below this cart weight. 0 means no limit.

Maximum weight (kg): hide the method above this cart weight. Default: 30 (also used when the field is empty). 0 means no limit. It cannot be lower than Minimum weight (kg).

Minimum order amount: show the method only when the subtotal of the products that need shipping (after the coupon, before tax) is at least this amount. Leave it empty to always show it.

Free shipping from: the subtotal (after the coupon, before tax) from which shipping is free. Leave it empty to never give free shipping.

Tax class: the tax class added on top of the shipping cost, or No tax. Frenet prices are final carrier prices. Choose No tax if OpenCart must not add tax to them.

Geo zone: offer Frenet only for addresses in this geo zone. All zones means no limit. Not used with Ignore shipping zones. Geo zones are managed in System > Localisation > Geo Zones.

Availability without shipping zones

Normally the method is offered in the geo zone selected in Conditions (in all zones when none is selected).

Ignore shipping zones: offer Frenet for the countries below, whatever geo zone matches. The Geo zone in Conditions is then not checked.

Countries: the destination countries for that mode, chosen from the enabled countries of your store. Leave it empty to use all countries you ship to. Used only when Ignore shipping zones is on.

Advanced

Debug log: logs every quote request and response to storage/logs/vfd_frn_debug.log.php (on OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). The file cannot be read from the web. API errors are always logged. The token is never logged and the customer CEP is shortened. Turn it off when you are done. When the file reaches 5 MB, it is moved to vfd_frn_debug.old.log.php and a new log is started.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the extension deletes all Frenet settings and the log. When off, everything is kept for a re-install. Cached quotes are always removed. The Frenet services saved with orders are order history and are kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API token is not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API token is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Frenet price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Frenet is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the country list (when Ignore shipping zones is on), the cart weight and the minimum order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. If free shipping applies, the price is 0 and no request goes to Frenet.

For an address in Brazil with a full 8-digit CEP, and when the API token and the origin CEP are set, the extension sends Frenet the origin and destination CEP, every cart item (weight in kg, dimensions in cm, quantity, the product Model and its categories), the order value in BRL and the coupon code of the cart. No request is made while the CEP is incomplete. Frenet returns the services of your enabled carriers. Services with an error or without a price are skipped. The extension picks the cheapest or the fastest service and converts the price to your default currency. The price is rounded to the decimals of your default currency and shown to the customer in their currency with the tax of the selected Tax class.

Each answer is cached for 1 hour for the same cart and address. A failed request, or a CEP that no enabled carrier serves, is remembered for 10 minutes. The API timeout is 10 seconds. In these cases the customer sees no error: the fixed price or the fallback cost is used, or the method is hidden if there is none. The reason is written to the log. For addresses outside Brazil only fixed prices are used.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Frenet in the window Shipping method options. The method works the same way as on OpenCart 3.

The extension calculates rates only. It does not create shipments, print labels or track parcels. It shows one Frenet service per cart, not several, and has no pickup points or lockers. Frenet quotes within Brazil only; use the fixed prices for other countries.

Orders

When an order is placed with Frenet, the extension saves how its shipping price was calculated: exactly the option the customer saw at the shipping step, without a new request to Frenet. The order page in Sales > Orders then shows a Frenet block with these lines:

Carrier: the Frenet carrier and service, for example a Correios or Jadlog service. Shown for live quotes.

Delivery time: the delivery time in business days returned by Frenet. Shown for live quotes.

Price source: Live Frenet quote, Fixed price (price per country), Fallback cost or Free shipping.

On OpenCart 4 the block is shown above History. OpenCart 4 updates the same order when the customer confirms it again: the saved Frenet data is updated as well, and if the customer has chosen another shipping method, the Frenet data of the order is removed.

The block is also shown when the extension is disabled. This data is kept when the extension is uninstalled, also with Remove data on uninstall.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Frenet is the first block on Extensions > Extensions > Shipping > VibeFox Frenet > Edit, 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: opencart-shipping-frenet and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (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 extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Frenet is not shown to customers at checkout and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Frenet does not appear at checkout: check that the license is active and Enable Frenet is on. Check Geo zone, or Ignore shipping zones and Countries, the weight limits and Minimum order amount. Check the warnings at the top of the extension page. Typical reasons: the customer has not entered a full 8-digit CEP yet and there are no fixed prices, or Frenet returned no service for the route and there is no fixed price. Check that the products have Requires Shipping set to Yes.

Live quotes do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension page. It shows the reason: no origin CEP, no BRL exchange rate, an incomplete customer CEP, a weight or amount limit, or the messages of the skipped services.

The log says the API token was rejected (HTTP 401 or 403): copy the token again from the Frenet panel and paste it into API token.

The log says Frenet returned no services: enable at least one carrier in the Frenet panel.

My store sells in euros or dollars: Frenet answers in BRL. Enter the BRL exchange rate (how much 1 BRL is in your default currency).

Tax is charged on top of the Frenet price: Frenet prices are final carrier prices. Set Tax class to No tax.

Rates look outdated after a change: click Save on the extension page. This clears the cached Frenet quotes.

The page says "Warning: You do not have permission to modify VibeFox Frenet!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_frenet (OpenCart 3) or extension/vfd_frenet/shipping/vfd_frenet (OpenCart 4) in System > Users > User Groups.

For developers: the Frenet quote address can be replaced with the setting vfd_frn_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox Frenet. The license key and license status of this extension are always removed. OpenCart always resets Enable Frenet, Sort order, Tax class and Geo zone. The cached quotes are always removed. The OpenCart event of the extension is removed too (on OpenCart 4 also the events that save the Frenet data of new orders), so the Frenet block is no longer shown on the order page. The Frenet data saved with orders is kept and shown again after a re-install. If Remove data on uninstall is on, the Frenet settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Existing orders keep their shipping method and cost.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Frenet in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Frenet is a trademark of its respective owner. This extension is not affiliated with or endorsed by Frenet.