VibeFox Andreani 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), with the default theme.

PHP: 8.0 or later.

Andreani account (for live rates only): live rates use the Andreani quote API. Andreani issues API credentials, a client code and contract numbers to business customers, usually from about 300 shipments a month. See developers.andreani.com or write to ventapyme@andreani.com. You need the API username and password, the client code and the contract number. Andreani issues a separate contract for each service (home delivery, branch pickup). Without API access, use fixed prices. The branch selector works without credentials.

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_andreani-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_andreani.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_andreani-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 Andreani 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. Set the name, the rate source, the country prices (for example AR=5000) and, for live rates, the API credentials, client code and contract number (see Configuration). Click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_andreani.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 Andreani, 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, Enable/Disable and Enable second option are off, and Andreani is not offered at checkout until you switch an option on and click Save. If you install the extension again after an uninstall, the Andreani settings you kept are used again, but both options are off: switch them on and click Save.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Andreani > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. After saving you see Settings saved. Cached token, branches and rates were cleared. Only admin users with the modify permission for this extension can save the settings.

Warnings about missing settings are shown at the top of the page: API rates selected without the API username and password or without a contract number, no ARS exchange rate when your store currency is not ARS, no price for Argentina in Country prices. A warning also appears if the store weight or length unit is not known to the extension (weights are then read as kg, dimensions as cm).

When you save, an empty name, a name longer than 64 characters or with one of the characters < > ; = # { }, a Min weight (kg) greater than Max weight (kg), or a Sort order that is not a whole number is refused and nothing is saved. A value that is not a number, a negative number or an ARS exchange rate of 0 or less is not saved, and a warning names the field.

General

Andreani has two options at checkout: the main option, set up here and in Andreani API and Delivery and rates, and the Second option. Both are shown under the heading Andreani in the delivery method step.

Enable/Disable: turns the main Andreani option on or off. Default: off. The second option has its own switch.

Name: the name of the main option shown to the customer at checkout. Default: Andreani. Required.

Tax status: None (the API rate is taken with IVA) (default), or one of your tax classes. With a tax class, OpenCart adds tax to the shipping cost, so the API rate is taken without IVA. With None, the API rate is taken with IVA included. Used by both options.

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

Andreani API (needed for live rates)

Environment: Sandbox / QA (apisqa.andreani.com) (default) or Production (apis.andreani.com). Use the environment your credentials belong to.

API username: your Andreani API user name.

API password: your Andreani API password. After saving, the field stays empty and shows Saved - leave empty to keep it. Clearing the API username removes it too. Type a new value only to change it.

Client code: the client code (código de cliente) provided by Andreani, for example CL0000000.

Contract number: the contract of the service used for rates, for example home delivery. The second option can use another contract, for example for branch pickup.

Origin branch code: optional origin branch (sucursalOrigen) for rate quotes. Leave it empty to use the branch configured in your contract.

Delivery and rates

Delivery modality: the modality of the main option. The first part is where Andreani takes the parcel (your address or a branch where you drop it off). The second part is where the customer gets it.

Rate source: how the price is calculated.

Country prices: a fixed price per destination country in your store default currency, tax excluded, one per line in the format CC=PRICE, for example AR=5000. Used by the fixed mode and as the API fallback. Countries without a line get no fixed price. Lines in another format are ignored, and a warning lists them when you save.

ARS exchange rate: Andreani quotes in Argentine pesos. Only needed if your store default currency is not ARS: the price of 1 ARS in your store currency, for example 0.001. Without it, API rates are not used.

Default product weight (kg): used for products without a weight when requesting API rates and checking weight limits. Empty means 0.5 kg.

Calculation type: Per order (default) charges the price once. Per item (price x number of items) multiplies the fixed price from Country prices by the number of items in the cart. A live Andreani rate is already for the whole cart and is not multiplied.

Availability

Min weight (kg): the minimum cart weight for the method to appear. 0 means no limit (default).

Max weight (kg): the maximum cart weight. The method is hidden if it is exceeded. Default: 100. Empty means 100 kg, 0 means no limit.

Minimum subtotal: show the method only when the cart subtotal (products that need shipping, after the coupon, tax excluded, in your store default currency) is at least this amount. Leave it empty to always show it.

Geo zone: offer Andreani only for addresses in this geo zone. All zones (default) means no limit. Geo zones are managed in System > Localisation > Geo Zones. Not used when Ignore shipping zones is on.

Ignore shipping zones: offer Andreani for the countries below, whatever the geo zone is. Default: off.

Countries: the destination countries for that mode. Leave it empty to allow all countries. Only used when Ignore shipping zones is on.

Free shipping

Free shipping: turn on the free shipping threshold. Default: off.

Free shipping from: the cart subtotal (in your store default currency) from which shipping is free. Requires Free shipping to be on.

Second option

A second Andreani option with its own name, delivery modality and contract, for example "a domicilio" in the main option and "retiro en sucursal" here, to offer both. All other settings are shared.

Enable second option: offers the second option at checkout. Default: off.

Second option name: the name of this option at checkout. Default: Andreani - branch pickup. Required.

Delivery modality: Use global setting or one of the four modalities. Default: Door to branch (Puerta a Sucursal).

Contract number: Andreani issues a separate contract per service (home delivery, branch pickup). Leave it empty to use the global contract.

Branch selector (shown for door to branch and branch to branch)

Province select width: the CSS width of the province list, for example 100% or 300px. Default: 100%.

Branch select width: the CSS width of the branch list, for example 100% or 400px. Default: 100%.

Advanced

Debug log: logs API requests and rate calculations to storage/logs/vfd_andr_debug.log.php. The file cannot be read from the web. Errors are always logged. Credentials and tokens are never logged. When the file reaches 5 MB, it is moved to vfd_andr_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 Andreani settings and the log. When off (default), they are kept for a re-install. Branch data saved in orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API password 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 password is kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the price of each enabled Andreani option. If a Geo zone is set and Ignore shipping zones is off, Andreani is not offered for addresses outside the geo zone. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension then checks the countries (when Ignore shipping zones is on), the cart weight (product weights are converted to kg, products without a weight use Default product weight (kg)) and Minimum subtotal. The subtotal is the price of the products that need shipping, after the coupon discount and before tax.

In the fixed mode the price is taken from Country prices. In the live modes the extension logs in to the Andreani API and requests a quote with the destination postcode, the contract, the client code, the weight in kg, the volume from product dimensions and the declared value (the cart subtotal in ARS). A live rate is requested only for a valid Argentine postcode (4 digits, or a CPA such as C1425ABC). The ARS amount is converted with ARS exchange rate when your store currency is not ARS. The price is calculated in your store default currency, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax status.

The login token is kept for up to 23 hours and renewed automatically when Andreani rejects it. Quotes are cached for 1 hour. A failed API call is not repeated for 5 minutes. All of this is stored in the OpenCart cache, so an entry is never kept longer than the OpenCart cache lifetime (1 hour by default) and is then simply requested again. API errors are never shown to the customer: the option is hidden, or the fixed price is used in the fallback mode. The reason is written to the log.

If Free shipping is on and the cart subtotal reaches Free shipping from, the price is 0. Free shipping applies only where the option has a price: if the Andreani API returns no rate and there is no fixed price to fall back to, the option is not shown.

The extension does not create Andreani shipments, print labels or track parcels. Use the Andreani web portal for these.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks an Andreani option in the window Shipping method options. The options work the same way as on OpenCart 3; the branch selection is described in Pickup points.

Pickup points

When an option with Door to branch or Branch to branch is offered, a province list and a branch list appear right under it in the delivery method step. The province is pre-selected from the region of the delivery address. The branch list comes from the public Andreani branch API and is cached for up to 12 hours (within the OpenCart cache lifetime). Branches that do not hand over parcels are not listed. The delivery step itself never waits for Andreani: if the list is not cached yet, it is loaded in the background and the customer briefly sees Loading Andreani branches.... If no branches are available, the customer sees No Andreani branches available right now. Please try again later or choose another shipping method.

The choice is saved as soon as the customer selects it. Only a branch from the current Andreani list is accepted. Without a branch, Continue in the delivery method step does not go through, and the customer sees Please select an Andreani pickup branch. The server checks the branch again when the customer continues. If the branch is no longer in the list, the customer sees The selected Andreani branch is not available. Please choose another one.

On OpenCart 4 the province list and the branch list appear in the window Shipping method options, right under the Andreani branch option, with the same texts and checks. Continue in the window without a branch is held back with Please select an Andreani pickup branch. under the option. If the store refuses the branch when the customer continues, the message is shown at the top of the checkout page and the window stays open. OpenCart 4 keeps one order for the checkout and updates it at every confirmation; the branch of the order is updated with it, and it is removed when the customer changes the order to another shipping method.

A branch chosen under one Andreani option does not belong to an order placed with another option or another shipping method.

The selector is made for the one-page checkout of the default OpenCart 3 theme and for the checkout of the default OpenCart 4 theme. A theme with a different delivery step layout may need changes to the selector script.

Orders

The order keeps the delivery modality and, for the branch modalities, the chosen branch.

Shipping method of the order: the branch is added to the shipping method text, for example Andreani - branch pickup: and the branch name. If the option name does not mention a branch, the text Pickup branch: (or Andreani pickup branch: when the name has no Andreani in it) is added before the branch name, for example Andreani - Pickup branch: and the branch name. This text appears in the order e-mails to the customer and the store, in the customer's order history, on the invoice and on the admin order page. The text is limited to 128 characters by OpenCart; the full branch data is kept by the extension. The order success page of OpenCart does not show the shipping method.

Admin order page: in Sales > Orders, open an order. An Andreani panel shows Andreani modality and, for the branch modalities, Andreani branch (name, ID and province). Click Edit, choose another province and branch and click Save to change it. You see Branch updated., and the branch in the shipping method text of the order is replaced too. Only branches from the Andreani list can be saved. If the list is not available, you see The Andreani branch list is not available right now - the branch cannot be changed. Changing the branch needs the modify permission for sale/order and access to extension/shipping/vfd_andreani (OpenCart 3) or extension/vfd_andreani/shipping/vfd_andreani (OpenCart 4). The panel is shown for orders already placed with Andreani also while the extension is disabled.

While the extension is switched off, the Andreani panel is not shown. The branch data stays saved and the shipping method text of the order does not change. Existing orders keep their branch data.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Andreani is the first block on Extensions > Extensions > Shipping > VibeFox Andreani > 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-andreani 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, the Andreani shipping options are 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

Andreani does not appear at checkout: check that the license is active and Enable/Disable is on (for the second option also Enable second option), and that you clicked Save after install. Check Geo zone, or Ignore shipping zones and Countries. Check that Country prices has a line for the country (for fixed prices or as the fallback), the weight limits and Minimum subtotal. Read the warnings at the top of the Edit page. Check that the products have Requires Shipping set to Yes.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field on the extension page. It shows the reason: missing credentials or contract number, a failed login (wrong username, password or environment), no valid Argentine postcode yet, no exchange rate, or an Andreani HTTP error. With Andreani API, fixed price if the API fails customers still get the fixed price while you fix the problem.

My store is not in Argentine pesos: set ARS exchange rate to the value of 1 ARS in your store default currency.

Shipping tax looks wrong: with a tax class in Tax status the Andreani rate without IVA is used and OpenCart adds its own tax. With None the rate with IVA is used and no tax is added. Check that taxes are enabled in the store settings and the tax class has rates for Argentina.

No branches in the list: the Andreani branch API did not answer. A failed request is retried after 5 minutes. Check the log.

The wrong province is pre-selected: the province is read from the region of the delivery address. The customer can always choose another province.

Rates look outdated after a change: click Save on the extension page. This clears the cached token, branch list and rates.

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

For developers: the Andreani API hosts can be replaced with the setting vfd_andr_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 Andreani. The license key and license status of this extension are always removed. OpenCart always resets the status, Sort order, Tax status and Geo zone. The extension always removes its checkout and order page handlers and the cached token, branch list and rates. If Remove data on uninstall is on, all Andreani 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. Branch data saved in orders is never deleted, and 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 Andreani in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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