VibeFox Correios for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Correios contract (for live prices only): live prices use the Correios Web Services (CWS) price API and need the credentials of a Correios contract with a posting card. You need three values: your Meu Correios user (usually the CNPJ or CPF of the contract), the API access code and the posting card number. Generate the access code in the Correios Web Services portal (cws.correios.com.br; for homologation cwshom.correios.com.br). You also need the CEP you ship from. Without credentials the module works with fixed prices only.
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 Correios 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. Enter the Correios API user, access code, posting card number, origin CEP and service. If your shop default currency is not BRL, enter the BRL rate. Fill in the fixed prices for other countries and as the fallback (see Configuration) and click Save.
On install the module creates the Correios carrier with the delivery time text Correios (Brazilian Post). The carrier is assigned to all zones and 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 Correios > Configure. Each section has its own Save button, which saves the whole page. Every save also clears the cached Correios prices and API tokens. Numbers can be typed with a point or a comma.
The page shows warnings when live prices or the carrier cannot work: only some of the three credentials are filled in, the origin CEP is missing, the BRL rate is missing for a shop in another currency, or there are neither credentials nor fixed prices. Each warning says whether the fixed prices are used in the meantime or the carrier is hidden. A warning also appears if the shop weight or dimension unit is not known to the module (it is then read as kg or cm); set kg, g, lb or oz and cm, mm, m or in in International > Localization (Local units).
Saving is refused with a message if the method title is empty or invalid (64 characters max), a number field or a price in Country prices is not a number of 0 or more, the BRL rate is 0, Min cart weight is greater than Max cart weight, the origin CEP does not have 8 digits or the other service code has more than 5 digits. Nothing is saved until you correct the value.
General
Enable Correios: turns the carrier on or off in all zones at once. This is the same switch as the carrier status in Shipping > Carriers.
Method title: the carrier name shown in the cart and at checkout. Default: Correios. Required.
Tax: the tax rule added on top of the shipping cost, or No tax (the default).
Correios API (live prices in Brazil)
For addresses in Brazil the price comes from the Correios price API. If the API gives no price (API down, CEP not served, parcel too big), the fixed price from Country prices is used, or the carrier is hidden when there is none. Error details go to the log, never to the customer.
API user: your Meu Correios portal login, usually the CNPJ or CPF of the contract.
Access code: the API access code (código de acesso) generated in the Correios Web Services portal. It is not the portal password. After saving, the field stays empty and shows Saved — leave empty to keep it (empty the API user as well to remove it). Type a new value only to change it. To remove the saved code, empty both API user and Access code and save.
Posting card: the posting card (cartão de postagem) number of your contract: 10 digits, usually starting with two zeros, for example 0012345678. Shorter numbers are completed with leading zeros. You can check the number on the Correios Fácil page of the Correios website.
Homologation: uses the Correios homologation (test) environment: requests go to apihom.correios.com.br with a homologation access code. Turn it off on a live shop.
Origin CEP: the CEP (8 digits) the parcels are sent from, for example 01001-000.
Service: the Correios service priced at checkout. Retail codes: PAC (04510, default), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Contract codes: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Contract codes need a posting card of a contract that includes the service.
Other service code: optional, a 5-digit service code of your contract that is not in the list, for example 03085. A shorter code is completed with leading zeros. When filled it is used instead of Service.
Package format: the object type sent to Correios.
Default product weight: in kg, sent to Correios for each product that has no weight. Default: 0.3. Product weights and dimensions are converted from your shop units (the field description shows them), and the cart is priced as one parcel.
BRL → store currency rate: the field name shows your shop default currency, for example BRL → EUR rate. Correios prices are in BRL. If your default currency is not BRL, enter how many units of your currency one BRL is worth, for example 0.17. Without it live prices are not used. The rate must be greater than 0. If your default currency is BRL, leave it empty.
Fixed prices (used for countries outside Brazil, without API credentials, and as the fallback when the API gives no price)
Country prices: a table of countries with a Base price and prices by cart weight in your shop default currency, tax excluded: XS up to 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL over 5 kg. An empty or zero size price uses the Base price. Click Add country to add a row and the cross to remove one. The row * Default (all other countries) sets prices for all countries without their own row. A country without a row (and without *) gets no fixed price. A row without any price is not saved. A price that is not a number, or is negative, stops the save with an error. A base price of 0 means free shipping for that country.
Fixed price per: Order charges the price once. Item (price × quantity) multiplies it by the number of items in the cart. This applies to fixed prices only. Live prices are always calculated for the whole parcel.
Conditions
Min cart weight: in kg, hide the carrier below this cart weight. 0 means no limit. It cannot be greater than Max cart weight.
Max cart weight: in kg, hide the carrier above this cart weight. Default: 30. 0 means no limit, an empty field means 30 kg. Correios PAC and SEDEX parcels can weigh up to 30 kg.
Minimum order amount: show the carrier only when the cart subtotal (products that need shipping, after discounts, before tax) reaches this amount. Leave empty to always show it.
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal (after discounts, before tax) from which shipping is free. No API request is made in that case.
Availability without shipping zones
Normally the carrier is shown in the zones it is assigned to in Shipping > Carriers.
Ignore shipping zones: offer the carrier for the countries below, whatever zone matches. On save the carrier is added to all zones. Switching the option off removes the zones it added. A zone created later while the option is on is added automatically.
Countries: the destination countries for that mode. Leave empty to use all active countries of the shop. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: writes price calculations to logs/vfd_crr_debug.log.php in the module folder. The file cannot be opened from the web. API errors are always logged, even when this option is off. The API user, access code, posting card, token and customer CEPs are not logged.
Log: shows the size and the latest entries of the debug log. Click Clear log to empty it.
Remove data on uninstall: when on, uninstalling the module deletes the settings, the carrier, the order services, cached prices and the log. When off, everything is kept for a re-install.
How it works at checkout
At the shipping step PrestaShop asks the module for the Correios price. Only physical products count: virtual products add no weight and are not included in the order amount. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. If free shipping applies, the price is 0 and no request goes to Correios.
For an address in Brazil with credentials set, the module first gets an API token for your posting card. The token also gives the contract and regional office numbers, so the price is the price of your contract. Then it requests the price of the chosen service by the origin and destination CEP, the parcel weight in grams and the parcel size in cm. A price is requested only when the destination CEP has 8 digits. When every product has dimensions, the parcel size is estimated from them; otherwise the Correios minimum size is sent. Parcels over 30 kg are not sent to the API. The BRL price is converted with your rate. The price is calculated in your default currency and then shown in the customer's cart currency.
Each price is cached for 1 hour per parcel. A failed request is cached for 10 minutes, so an API outage does not slow down every checkout update. The token is cached until shortly before it expires and renewed automatically; if Correios rejects it, a new token is requested and the price request is repeated once. The API timeout is 12 seconds.
If the API gives no price, the fixed price is used, or the carrier is hidden when there is no fixed price. The customer never sees API error details; they go to the debug log.
If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.
The module calculates rates only. It does not get international Correios prices (Exporta Fácil, Packet), delivery time estimates, labels, pre-postings, declarations or tracking. Customers cannot choose a Correios agency or locker. Additional services (declared value, own hands, receipt notice) are not added. It shows one Correios service per shop, and currency rates are not updated automatically.
Orders
When an order is placed with the Correios carrier, the module saves how its shipping price was calculated. The order page in the back office then shows a Correios block with Correios service (for a live price, for example PAC — contract (03298)) and Price source: Live price (Correios API), Fixed price or Free shipping.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Correios is the first block on Modules > Module Manager > VibeFox Correios > 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-correios 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, the Correios carrier is not 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 carrier 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 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
Correios does not appear at checkout: check that the license is active and Enable Correios is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group (or Ignore shipping zones is on and the country is allowed). Check the weight limits and Minimum order amount. Without a live price, a fixed price for the country or * must exist. Products can also be limited to certain carriers in the product page.
The carrier shows a fixed price instead of the Correios price: look at the Log field on the module page. Correios errors are logged there: wrong access code, service not in your contract, CEP not served, parcel over 30 kg or over the size limits. Also check that the origin CEP is set, the customer's CEP has 8 digits and, if the default currency is not BRL, the BRL rate. Turn on Debug log to see every calculation.
Token request fails: check the API user, the access code, the posting card and the environment. A homologation access code works only with Homologation on, and a production code only with it off.
Rates look outdated after a change: click Save on the module page. This clears the cached prices and the API token.
The page says the Correios carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.
Saving says you do not have permission: your employee profile can view the module but not configure it. Saving the settings and clearing the log need the configure permission of the module.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Correios and choose Uninstall. The license key, the license status and the cached prices and tokens are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings, the saved order services and the log are removed. If it is off, the carrier is only disabled and all settings are kept. Installing the module again restores the carrier with the status it had before.
Correios is a trademark of its respective owner. This module is not affiliated with or endorsed by Correios.