VibeFox Andreani 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.

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 [email protected]. 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 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-andreani-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/AndreaniShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_AndreaniShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy (the module has its own checkout scripts and styles), then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Andreani. 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. Set the rate source, the country prices (for example AR=5000) and, for live rates, the API credentials, client code and contract number (see Configuration). Set Enable Andreani to Yes and click Save Config.

The module adds the Andreani shipping method to Magento with two options. Customers see the main option as Andreani - Home delivery and the second option as Andreani - Branch pickup (method title and option name). After installation Enable Andreani is No and the second option is off. The module also creates its own table for the branch choices of carts and orders.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Andreani, 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, Method name and Second option name also for a store view. Save Config saves the whole page and clears the cached Andreani token, branch list and rates. 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, Method name or Second option name, longer than 64 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a Min weight (kg) greater than the Max weight (kg).

A number field that does not contain a number, a negative number or an ARS exchange rate of 0 or less is saved empty, and a warning names the field. Lines of Country prices that are not in the format CC=PRICE are ignored, and a warning lists them. Warnings about missing settings are shown in the Notices row at the top of the group: API rates selected without the API username or password, without a contract number, or without an ARS exchange rate when the base currency is not ARS, and no price for Argentina in Country prices.

General

Enable Andreani: shows or hides Andreani at checkout. The second option has its own switch and needs this one on. Default: No.

Method title: the carrier name shown to the customer before the name of each option, as "Method title - Method name". Default: Andreani. Required, at most 64 characters.

Method name: the name of the main option at checkout, shown after the method title. Default: Home delivery. Rename it if the delivery modality of the main option delivers to a branch. Required, at most 64 characters.

Sort order: the position 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. Clearing it also clears the saved password.

API password: your Andreani API password. 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 the field and click Save Config.

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

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. Fixed prices need no Andreani account.

Country prices: a fixed price per destination country in the base currency of your store, 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.

ARS exchange rate: Andreani quotes in Argentine pesos. Only needed if the base currency of your store is not ARS: the price of 1 ARS in the base 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. Default: 0.5. 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.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so no volume is sent to Andreani.

There is no tax field in the module. If your store charges tax on shipping (a tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping, with shipping prices entered without tax), the Andreani rate without IVA is used and Magento adds its own tax. Otherwise the rate with IVA included is used.

Availability

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

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

Minimum subtotal: show the method only when the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) is at least this amount. Leave it empty to always show it.

Ship to Applicable Countries: All Allowed Countries offers Andreani for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries. Live rates are requested for Argentina only; other countries use the fixed prices.

Free shipping

Free shipping: turns the free shipping threshold on. Default: No.

Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) from which shipping is free. Requires Free shipping to be Yes.

Second option

A second Andreani option with its own name, delivery modality and contract, for example home delivery in the main option and branch pickup here, to offer both. All other settings are shared.

Enable second option: offers the second option at checkout while Enable Andreani is Yes. Default: No.

Second option name: the name of this option at checkout, shown after the method title. Default: Branch pickup. Required, at most 64 characters.

Delivery modality: Use global setting (the modality of the main option) 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 300px. Default: 100%.

Advanced

Debug log: logs API requests and rate calculations to var/log/vfd_andr_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged, even when this is off. Credentials, tokens and customer addresses are never 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 Andreani settings, the log and the branch choices of carts that never became an order (see Uninstall). The license key and the cache are always removed. Branch data saved in orders is always kept. This setting is read from the Default Config only.

How it works at checkout

At the shipping step Magento asks the module for the price of each Andreani option. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module checks the countries, the cart weight (products without a weight use Default product weight (kg)) and Minimum subtotal.

In the fixed mode the price is taken from Country prices. In the live modes the module logs in to the Andreani API and requests a quote with the destination postcode, the contract (the second option can have its own), the client code, the weight in kg and the declared value (the cart subtotal in ARS). A live rate is requested only for a valid Argentine postcode. The ARS amount is converted with ARS exchange rate when your base currency is not ARS. The price is calculated in the base currency of your store; Magento then shows it in the customer's currency.

The login token is cached for 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. 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 Yes and the subtotal reaches Free shipping from, the price is 0. A Magento cart price rule with free shipping also makes the price 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 module does not create Andreani shipments, print labels or track parcels. Use the Andreani web portal for these.

Pickup points

When an option with Door to branch or Branch to branch is selected, a Province list and an Andreani branch list appear under the shipping methods in the shipping 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 12 hours. Branches that do not hand over parcels are not listed. 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 to the cart as soon as the customer selects it. Only a branch from the current Andreani list is accepted. Without a branch, Next in the shipping 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. A branch chosen under another Andreani option before the customer switched does not belong to the order.

The selector is made for the standard Magento checkout (Luma and Blank themes). Third-party checkouts need their own integration. Orders created in the Admin and multi-address checkout have no branch selector; such an order is placed without a branch, and an error is written to the log.

Orders

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

Shipping description: the branch is added to the shipping method of the order, for example Andreani - Branch pickup: Palermo (Av. Santa Fe 3400 CABA). The customer sees it in the order e-mails, in the order in their account and on invoices.

Admin order page: on Sales > Orders > View, Information tab, an Andreani block shows the modality and the branch (name, ID and province). Click Edit, choose another province and branch and click Save to change it. You see Branch updated. and the shipping description of the order changes 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. Editing needs the Admin permission to edit orders. The block also works for older orders and when the module is switched off.

Existing orders keep their branch data.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Andreani is the first row of the VibeFox Andreani 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-andreani 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 Andreani options are 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

Andreani does not appear at checkout: check that the license is active and Enable Andreani is Yes for the website of the store (for the second option also Enable second option). Check Ship to Applicable Countries and Ship to Specific Countries, that Country prices has a line for the country (for fixed prices or as the fallback), the weight limits and Minimum subtotal. Read the Notices at the top of the group.

Live rates do not appear: turn on Debug log, reload the checkout and look at the Log field in the Advanced section. 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 the base currency of your store.

IVA is charged twice or not at all: with a Tax Class for Shipping and shipping prices without tax, the Andreani rate without IVA is used and Magento adds its own tax. Otherwise the rate with IVA is used. Check the tax settings of your store 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 branch lists do not appear at checkout: check that the selected option uses Door to branch or Branch to branch. After installing or updating in production mode run bin/magento setup:static-content:deploy so that the checkout scripts of the module are published.

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

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_AndreaniShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_AndreaniShipping to remove the data, then bin/magento module:disable Vibefox_AndreaniShipping, delete the folder app/code/Vibefox/AndreaniShipping and run bin/magento setup:upgrade.

The license key, the license status and the cached token, branch list and rates are always removed. If Remove data on uninstall is Yes, the Andreani settings, the log and the branch choices of carts without an order are removed too. If it is No, the settings are kept for a re-install. The branch table of the module and the branch data of orders are never deleted, and the shipping description of orders keeps the branch.

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