VibeFox CTT for Adobe Commerce — Hilfe
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.
CTT e-commerce account (for live rates and CTT points only): live rates and delivery to a CTT point use the CTT e-commerce API. You need a CTT e-commerce account at enviosecommerce.ctt.pt. In the key management page of that account, create a public and private key pair. The App ID (X-APPID) is issued by CTT for your integration: ask your CTT e-commerce contact. CTT also decides which API functions (cost estimate, CTT points) your App ID may use. Finally you need the Carrier ID of CTT in your account. The settings page lists the carriers of your account once the keys are saved. If you only use the price table and delivery to the address, you do not need API keys.
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-ctt-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/CttShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_CttShipping 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 CTT. 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 price table (at least a Portugal or * Default row). Optionally fill in the CTT API keys and the Carrier ID, set Live rates and Enable CTT point option to Yes (see Configuration). Set Enable CTT to Yes and click Save Config.
The module adds the CTT shipping method to Magento with two options. Customers see them as CTT - Delivery to your address and CTT - CTT point / parcel locker (method title and option name). After installation the module is off (Enable CTT = No), delivery to the address is switched on and the CTT point option is switched off until you enable it. The module adds one table for the CTT points chosen in carts and orders.
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox CTT, 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, Name and CTT point option 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 CTT answers, including the API token and the CTT point lists. Amounts accept "9.99" and "9,99". The prices and conditions apply to both CTT options.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Name or CTT point option name; a Method title or 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). An empty Method title is saved as CTT.
Some values are corrected and saved with a warning: an amount or weight that is not a non-negative number is not saved (the field stays empty), an Exchange rate that is not a positive number is cleared, an invalid Default product size (cm) is set back to 30x20x15, a Carrier ID or Service ID that is not a number is cleared. In the price table an unknown destination is removed, a repeated destination keeps only its first row and an invalid price is left empty.
The Notices row at the top of the group warns about settings that hide CTT or the CTT point selection: an empty price table, no price for Portugal and no * Default row, live rates or the CTT point option without complete API keys (public key, private key, App ID) or without a Carrier ID, a base currency other than EUR without an exchange rate, and a failed connection to the CTT API.
General
Enable CTT: shows or hides CTT at checkout. This switches the whole module; the two delivery options are switched in their own sections. Default: No.
Method title: shown to the customer before the option name, as "Method title - Option name". Default: CTT. At most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
Delivery to the customer's address
Enable delivery to the address: CTT shipping to the customer's address. Default: Yes.
Name: the name of this option at checkout, after the method title, for example "Expresso". Default: Delivery to your address. Required, at most 64 characters.
Delivery to a CTT point or parcel locker
The second option. The customer searches CTT points by postcode or city and must choose one before the order can be placed (see Pickup points). It needs the CTT API keys and the Carrier ID. Without them it is an option without point selection.
Enable CTT point option: turns the CTT point option on or off. Default: No.
CTT point option name: the name of this option at checkout, after the method title. Default: CTT point / parcel locker. Required, at most 64 characters.
CTT e-commerce API (live rates, CTT points) (optional; without keys the price table is used)
Public key: the public key from the key management page of your CTT e-commerce account.
Private key: the secret key used to sign every request (HMAC-SHA256). It is never sent to CTT or written to the log.
Magento stores both keys encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved keys, clear Public key and click Save Config: this removes the saved public and private key.
App ID (X-APPID): the application key issued by CTT, sent in the X-APPID header.
Carrier ID: the ID of the CTT carrier in your account, used for live rates and the CTT point search. Numbers only. After the keys and the App ID are saved, the row Carriers of your CTT account under the field lists the carriers of your account with their IDs, with the ones that support CTT points marked (CTT points).
Live rates: ask CTT for the price (cost estimate) once the customer has entered the street, postcode and city. The price table is used while the address is incomplete and whenever CTT gives no price. CTT calls this price an estimate. Default: No.
Service ID: optional. When CTT returns several services, the one with this ServiceId is used. Leave it empty to use the cheapest one.
Exchange rate: CTT prices are in euro. If the base currency of your store is different, enter how many units of the base currency equal 1 unit of the CTT currency. Without it, live rates in another currency are not used and the price table applies.
Default product size (cm): length x width x height sent to CTT for products without dimensions. Default: 30x20x15. Magento products have no standard dimensions: products with the attributes length / width / height (or ts_dimensions_length / _width / _height) use their own, in cm when the weight unit of the store is kgs and in inches when it is lbs.
Prices
Enter the prices of your CTT contract or of the public CTT price list at ctt.pt, in the base currency of your store, tax excluded. With live rates off this table sets the price. With live rates on it is the fallback.
Price table: one row per destination. Choose a country, Portugal - Azores (PT-AC), Portugal - Madeira (PT-MA) or * Default (other destinations). Each row has a base Price and optional prices for the sizes 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). An empty (or 0) size price uses the base price. A row where both are empty hides the method. The Azores row is used for Portuguese postcodes 9500-9999, the Madeira row for 9000-9499. Without them the Portugal row applies. Click Add destination to add a row and Delete to remove one. Prices accept a decimal point or comma. The table is empty after installation.
Calculation: how the table price is found.
A live CTT price is always for the whole shipment.
Conditions
Min weight (kg): the minimum cart weight for CTT to appear. 0 means no limit.
Max weight (kg): CTT is hidden above this cart weight. Default: 30 (CTT parcels go up to 30 kg). 0 means no limit.
Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs).
Minimum order amount: show CTT 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
Free shipping: Yes turns on free CTT delivery from the amount below.
Free shipping from: the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) from which both options cost 0. It applies only to destinations that have a price.
Availability
Ship to Applicable Countries: All Allowed Countries offers CTT for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Default: Portugal.
Advanced
Debug log: logs the price calculation and the CTT API calls to var/log/vfd_ctt_debug.log.php in the Magento folder. The file cannot be opened from the web. CTT API errors are always logged, even when this is off. Keys, 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 module settings, the log and the CTT point searches of carts that never became orders (see Uninstall). The license key and the cached CTT answers are always removed. CTT points saved in orders are always kept.
Shipping tax is not a module setting: if your store taxes shipping, Magento adds the tax of Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping on top of the CTT price.
How it works at checkout
At the shipping step Magento asks the module for the price of each CTT option that is switched on. 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 cart weight and the minimum order amount (Magento itself checks the countries). With Live rates on and a complete address, it sends CTT the delivery address and, for each cart line, the quantity, the weight in grams and the dimensions in cm, and uses the returned price. Otherwise, or when CTT gives no price (API error, timeout, no coverage, a function not enabled for your App ID), the price comes from the table. If free shipping applies, the price is 0. A Magento cart price rule with free shipping also makes the price 0. Both options get the same price. The price is calculated in the base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.
A CTT price is cached for 1 hour, so the same cart does not trigger a new request. A failed request is remembered for 5 minutes, so the checkout does not wait for CTT on every refresh. API errors never reach the customer: the table price is used, or the method is hidden if the destination has no price. The reason is written to the log.
With API keys filled in, the module sends the delivery address, product weights and dimensions and your store URL to CTT to get a price or the nearest CTT points.
The module does not create shipments, print labels, request pickups, provide tracking numbers or show a map of CTT points. There is one price table and one set of API settings for both options.
Pickup points
When the customer selects the CTT point option in the shipping step, a Postcode or city field with a Search button and a list of CTT points appear under it. The postcode of the delivery address is searched automatically. The customer can search other CTT points by postcode or city (Search or Enter) and chooses one from the list. The choice is saved in the cart at once. Only a point from the CTT list for that search is accepted; otherwise the customer sees The selected CTT point is not in the CTT list for this search. Please choose the CTT point again.
A point must be chosen before the customer can continue. Next in the shipping step waits for the choice, and the server checks the point again. Without a point the customer sees Please select a CTT point. and stays on the shipping step. The CTT point lists are cached for 6 hours. If no point is found, the customer sees No CTT points found for this postcode or city. If CTT cannot be reached, the customer sees CTT points cannot be loaded right now. Please try again in a few minutes or choose another shipping method.
The point selection works in the standard Magento checkout (Luma and Blank themes) and is active only when Enable CTT and Enable CTT point option are Yes and the public key, private key, App ID and Carrier ID are filled in. Other checkouts (Hyvä, one-step checkouts) and orders created in the Admin or with multiple addresses have no point selection; such an order is placed without a point and an error line is written to the log.
The chosen point is saved with the order and added to its shipping description, for example CTT - CTT point / parcel locker - CTT point: Loja CTT Restauradores - Praça dos Restauradores 58, Lisboa. The customer sees it in the order confirmation e-mail, in the order in their account and on invoices.
On the admin order page (Sales > Orders > View, Information tab) the CTT point block shows the point and its ID, or No CTT point was selected for this order. To change the point, click Change CTT point, enter a postcode or city, click Search, choose a point and click Save. The search uses the delivery address of the order. The page shows CTT point updated., the shipping description of the order is updated and the comment CTT point changed to: with the new point is added to the order history, without notifying the customer. Changing the point needs permission to edit orders and the saved API keys and Carrier ID. The block is also shown for older orders and when the module is switched off.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox CTT is the first row of the VibeFox CTT 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-ctt 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, neither CTT option (delivery to the address or to a CTT point) is 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 CTT 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
CTT does not appear at checkout: check that the license is active and Enable CTT is Yes for the website of the store, and that Enable delivery to the address or Enable CTT point option is Yes. Check Ship to Applicable Countries and Ship to Specific Countries, that the destination has a row in the price table (or a * Default row), the cart weight is within Min weight and Max weight and the Minimum order amount is reached. Look at the Notices row of the group.
The customer cannot choose a CTT point: the selector appears only under the CTT point option, and only when the public key, private key, App ID and Carrier ID are filled in. Check the Notices row, set Debug log to Yes and look at the Log field in the Advanced section.
Live rates do not appear: the price table is used until the customer has entered the street, postcode and city. Check the Notices row and the log. An answer "405" means the function is not enabled for your App ID: ask CTT. If the base currency of your store is not EUR, fill in Exchange rate.
The connection to the CTT API failed: the Notices row shows the error. Check the keys and the App ID. The module retries automatically after a few minutes.
Prices look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached CTT answers.
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_CttShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_CttShipping to remove the data, then bin/magento module:disable Vibefox_CttShipping, delete the folder app/code/Vibefox/CttShipping and run bin/magento setup:upgrade.
The license key, the license status, the cached CTT answers and the API token are always removed. If Remove data on uninstall is Yes, the settings, the log and the CTT point searches of carts that never became orders are removed too. If it is No, the settings are kept for a re-install. CTT points saved in orders and the shipping descriptions of orders are always kept.
CTT is a trademark of its respective owner. This module is not affiliated with or endorsed by CTT.