VibeFox Correios 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).

PHP: 8.0 or later.

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 extension works with fixed prices only.

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_correios-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_correios.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_correios-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 Correios 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. Enter the Correios API user, access code, posting card number, origin CEP and service. If your store default currency is not BRL, enter the BRL rate. Fill in the fixed prices for other countries and as the fallback (see Configuration), turn on Enable Correios and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_correios.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 Correios, 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 the method is off until you turn on Enable Correios and save. If you install the extension again after an uninstall, the Correios settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox Correios > Edit. The sections are listed on the left. One Save button at the bottom saves the whole page without reloading it. Every save also clears the cached Correios prices and API tokens. Numbers can be typed with a point or a comma. Only admin users with the modify permission for this extension can save the settings.

The page shows warnings when live prices or the method cannot work: only some of the three credentials are filled in, the origin CEP is missing, the BRL rate is missing for a store 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 method is hidden. A warning also appears if the store has no weight class with the unit kg or no length class with the unit cm; product units are then converted by the unit name of their class (unknown units are read as kg or cm). Check System > Localisation > Weight Classes and Length Classes.

Saving is refused with a message if the method title is empty or invalid (64 characters max, without < > ; = # { }), 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, the other service code has more than 5 digits, or Sort order is not a whole number. Nothing is saved until you correct the value.

General

The settings apply to every geo zone. You can limit the method to a geo zone in Conditions, or to a list of countries with Ignore shipping zones.

Enable Correios: shows or hides Correios at checkout. Default: off.

Method title: the shipping method name shown to the customer in the cart and at checkout. Default: Correios. Required.

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

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 method 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. Clearing it also clears the saved access code.

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 API user 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 store.

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 (kg): sent to Correios for each product that has no weight. Default: 0.3. Product weights and dimensions are converted from their weight and length classes, and the cart is priced as one parcel.

BRL → store currency rate: the field name shows your store 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 store 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 × button to remove one. The row * 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 needs at least one price. A base price of 0 means free shipping for that country.

Fixed price per: Order (default) 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 (kg): hide the method below this cart weight. 0 means no limit. It cannot be greater than Max cart weight.

Max cart weight (kg): hide the method 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 method only when the subtotal of the products that need shipping (after the coupon, before tax) reaches this amount. Leave it empty to always show it.

Free shipping: turn on free delivery from the amount below.

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) from which delivery is free. No API request is made in that case.

Tax class: the tax class added on top of the shipping cost, or No tax (default).

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

Availability without shipping zones

Normally the method is offered in the geo zone selected in Conditions (in all zones when none is selected).

Ignore shipping zones: offer the method for the countries below, whatever geo zone matches. The Geo zone in Conditions is then not checked.

Countries: the destination countries for that mode. Leave it empty to use all countries enabled in the store. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: writes price calculations to storage/logs/vfd_crr_debug.log.php (on OpenCart 4 system/storage/logs/vfd_crr_debug.log.php). The file cannot be read 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. When the file reaches 5 MB, it is moved to vfd_crr_debug.old.log.php and a new log is started.

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 extension deletes the Correios settings and the log. When off (default), they are kept for a re-install. The Correios services saved with orders are always kept.

Import / Export

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

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the Correios price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, Correios is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the order amount. The extension then checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum order amount. The order amount is the price of the products that need shipping, after the coupon discount and before tax. If free shipping applies, the price is 0 and no request goes to Correios.

For an address in Brazil with credentials set, the extension 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, rounded to its decimals, and shown to the customer in their currency with the tax of the selected Tax class.

Each price is cached for 1 hour. 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 (at most for the OpenCart cache lifetime, 1 hour by default) 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 method is hidden when there is no fixed price. The customer never sees API error details; they go to the debug log.

The extension 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 store, and currency rates are not updated automatically.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks Correios in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order is placed with Correios, the extension saves how its shipping price was calculated. The order page in Sales > Orders then shows a Correios block with Correios service (for example PAC — contract (03298)) and Price: Live price (Correios API), Fixed price or Free shipping. The block is shown in the admin only, not in customer e-mails, and stays visible when the extension is disabled.

On OpenCart 4 the checkout keeps one order and updates it when the customer confirms again. The Correios data of the order is updated with it, and if the customer switches to another shipping method, the Correios block is no longer shown for that order.

License key

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

Correios does not appear at checkout: check that the license is active and Enable Correios is on. Check Geo zone (or Ignore shipping zones and Countries), the weight limits and Minimum order amount. Without a live price, a fixed price for the country or * must exist. Check that the products have Requires Shipping set to Yes.

The method shows a fixed price instead of the Correios price: look at the Log field on the extension 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 extension page. This clears the cached prices and the API token.

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

For developers: the Correios API host can be replaced with the setting vfd_crr_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 Correios. The license key and license status of this extension are always removed. OpenCart always resets Enable Correios, Sort order, Tax class and Geo zone. The cached prices and tokens are always removed. If Remove data on uninstall is on, the Correios 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. The Correios services saved with orders are always kept, 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 Correios in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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