VibeFox CTT for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
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 (for CTT Expresso contract customers, or ask CTT for a proposal). 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
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox CTT in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Fill in the price table (at least a Portugal or * Default row) and click Save. Optionally fill in the CTT API keys and the Carrier ID, turn on Live rates and Enable CTT point carrier (see Configuration).
On install the module creates two carriers. CTT (delivery to the customer's address, delivery time text CTT delivery to your address) is switched on. CTT point / parcel locker (delivery time text Pickup at a CTT point or parcel locker) is switched off until you enable it. Both are linked to the zone of Portugal and to all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.
Configuration
All settings are on the module page: Modules > Module Manager > VibeFox CTT > Configure. Each section has its own Save button, which saves the whole page. The prices and conditions apply to both CTT carriers. Every save clears the cached CTT answers, including the API token and the CTT point lists.
Warnings above the settings tell you about an empty price table, a missing price for Portugal, incomplete API keys, a missing Carrier ID, a shop currency other than EUR without an exchange rate, a failed connection to the CTT API and a deleted CTT carrier. Invalid values are reported when you save: an invalid number is not saved, an unknown destination or a duplicate row in the price table is removed. If the weight or dimension unit of your shop is not known to the module, a warning asks you to set the units in International > Localization (Local units).
General
Enable/Disable: turns CTT delivery to the customer's address on or off. This is the same switch as the carrier status in Shipping > Carriers.
Name: the carrier name shown to the customer at checkout, for example "CTT Expresso". Default: CTT. Required, up to 64 characters.
Tax status: None means the prices are final. Taxable with a tax rule means PrestaShop adds that shipping tax (for example IVA) on top of the prices. The choice is saved to both CTT carriers.
Delivery to a CTT point or parcel locker
The second CTT carrier. The customer searches CTT points by postcode or city and must choose one before continuing. It needs the CTT API keys and the Carrier ID. Without them it is a carrier without point selection.
Enable CTT point carrier: turns the CTT point carrier on or off. This is the same switch as its status in Shipping > Carriers. Default: off.
CTT point carrier name: the name of this option at checkout. Default: CTT point / parcel locker. Required, up to 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.
Both keys are never shown again after saving. The field description then says Saved - leave empty to keep it. Type a new value only to change it. Tick Remove the saved public and private key and save to delete both.
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. After the keys and the App ID are saved, the carriers of your account are listed under the field, with the ones that support CTT points marked (CTT points). Numbers only.
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: off.
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 your shop default currency is different, enter how many units of your shop 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. Products with dimensions use their own. Dimensions are converted to cm and weights to grams from your shop units.
Prices (the section title shows your shop default currency)
Enter the prices of your CTT contract or of the public CTT price list at ctt.pt, in the shop default currency, 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 carrier. The Azores row is used for Portuguese postcodes 9500-9999, the Madeira row (including Porto Santo) for 9000-9499. Without them the Portugal row applies. Click Add destination to add a row and the trash icon to remove one. Prices accept a decimal point or comma. The table is empty after install.
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 the carriers to appear. 0 means no limit.
Max weight (kg): the carriers are hidden above this cart weight. Default: 30 (CTT parcels go up to 30 kg). 0 means no limit. Min weight (kg) cannot be greater than Max weight (kg): the settings are not saved.
Minimum order amount: show the carriers only when the cart subtotal (products that need shipping, after discounts, before tax) reaches this amount. Leave empty to always show them.
Free shipping
Free shipping: turn on free CTT delivery from the amount below.
Free shipping from: the cart subtotal (after discounts, before tax) from which the carriers cost 0. It applies only to destinations that have a price. Used only when Free shipping is on.
Availability without shipping zones
Normally the carriers are offered in the shipping zones they are linked to in Shipping > Carriers.
Ignore shipping zones: offer the carriers in the countries below without linking them to their zone. When you turn it on, both carriers are linked to every active zone (also zones you create later). When you turn it off, they get back the zones they had before.
Countries: the destination countries for that mode. Default: Portugal. Leave empty to allow all countries. Used only when Ignore shipping zones is on. Customers in the zones the carriers had before are always served.
Advanced
Debug log: logs the price calculation and the CTT API calls to logs/vfd_ctt_debug.log.php in the module 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 on, uninstalling the module deletes the module settings and its carriers. When off, uninstalling only switches the carriers off. Orders, including the chosen CTT point, are never changed.
How it works at checkout
At the shipping step PrestaShop asks the module for the price of each CTT carrier. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks Ignore shipping zones and its countries, the cart weight and the minimum order amount. 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. The price is calculated in your shop default currency and then shown in the customer's cart currency.
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. The API timeout is 12 seconds. API errors never reach the customer: the table price is used, or the carrier is hidden if the destination has no price.
If you edit a carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.
With API keys filled in, the module sends the delivery address, product weights and dimensions and your shop 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 carriers.
Pickup points
When the customer selects the CTT point carrier, a search field and a list appear under it. The postcode of the delivery address is filled in and searched automatically. The customer can search other CTT points by postcode or city (button 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.
A point must be chosen before the customer can continue. When the customer clicks Continue in the shipping step, the module checks the point on the server again. Without a point the customer sees Please select a CTT point., with a point that is not in the CTT list The selected CTT point is not in the CTT list for this search. Please choose the CTT point again. The CTT point lists are cached for 6 hours. 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 with the Classic and Hummingbird themes. It is active only when the public key, private key, App ID and Carrier ID are filled in.
The chosen point is saved in the order. It is shown on the admin order page in the CTT point block (name and ID), on the order confirmation page and in the order details in the customer account, and in the order confirmation e-mail as CTT point: next to the carrier name. The new order e-mail of the Mail alerts module also shows the point ID.
On the admin order page, enter a postcode or city under Change CTT point, click Search, choose a point and click Save. The page shows CTT point updated. and a private order message CTT point changed to: with the new point is added. Changing the point needs permission to edit orders.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox CTT is the first block on Modules > Module Manager > VibeFox CTT > Configure, 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 shop. Below them are the line Product: presta-shipping-ctt and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop 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 main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, neither CTT carrier (delivery to the address or to a CTT point) is shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carriers are 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.
Troubleshooting
CTT does not appear at checkout: check that the license is active and Enable/Disable (or Enable CTT point carrier) is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or that Ignore shipping zones is on and the country is allowed. Check 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. Products can also be limited to certain carriers in the product page.
The customer cannot choose a CTT point: the selector appears only under the CTT point carrier, and only when the public key, private key, App ID and Carrier ID are filled in. Check the warnings above the settings, turn on Debug log and look at the Log field on the module page.
Live rates do not appear: the price table is used until the customer has entered the street, postcode and city. Check the warnings above the settings and the log. An answer "405" means the function is not enabled for your App ID: ask CTT. In a shop not in euro, fill in Exchange rate.
The connection to the CTT API failed: the warning above the settings shows the error. Check the keys and the App ID. The module retries automatically after a few minutes.
Prices with or without VAT: with Tax status set to a Taxable rule PrestaShop adds the shipping tax on top of the price. With None the price is final.
Prices look outdated after a change: click Save on the module page. This clears the cached CTT answers.
The page says a CTT carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. A reset keeps the settings and the on/off status of both carriers.
For developers: the CTT API address can be changed with the Configuration key vfd_ctt_API_URL.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox CTT and choose Uninstall. The license key, the license status, the cached CTT answers and the API token are always removed. If Remove data on uninstall is on, both carriers are deleted (orders keep their history), and the settings, the log and CTT points of carts that never became orders are removed. If it is off, the carriers are only switched off and all settings are kept. Installing the module again gives each carrier back the on/off status it had. CTT points saved in orders are always kept.
CTT is a trademark of its respective owner. This module is not affiliated with or endorsed by CTT.