VibeFox Correios for WooCommerce — Help
Requirements
WordPress: 5.8 or later.
WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.
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 plugin works with fixed prices only.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_correios folder to /wp-content/plugins/ by FTP.
2. Click Activate.
3. Open the settings: WooCommerce > Settings > Shipping > VibeFox Correios, or click Settings under the plugin name on the Plugins page.
4. Enter your VibeFox license key in the license block at the top of the page and click Activate.
5. Enter the Correios API user, access code, posting card number, origin CEP and service. If your store currency is not BRL, enter the BRL rate. Fill in the fixed prices for other countries and as the fallback (see Configuration).
6. Add VibeFox Correios to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.
Configuration
All settings are on one page: WooCommerce > Settings > Shipping > VibeFox Correios. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:
Title (zone): the name shown to the customer for this zone. Leave it empty to use the global Method title.
The settings 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. Every time you save the settings, the cached prices and the API token are cleared. Numbers can be typed with a point or a comma.
General
Enable/Disable: turns the method on or off in all zones at once.
Method title: the shipping method name shown in the cart and at checkout. Default: Correios. A zone can override it with its own title.
Tax status: Taxable adds WooCommerce tax on top of the shipping cost, None does not.
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.
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.
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 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. 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 your store units, and the cart is priced as one parcel.
BRL → store currency rate: the field name shows your store currency. Correios prices are in BRL. If your store 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. If your store 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 currency: 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 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 (kg): hide the method below this cart weight. 0 means no limit.
Max cart weight (kg): hide the method above this cart weight. Default: 30. 0 means no limit. Correios PAC and SEDEX parcels can weigh up to 30 kg.
Minimum order amount: show the method only when the cart subtotal reaches this amount. Leave empty to always show it.
Excluded shipping classes: hide the method if any cart item has one of these WooCommerce shipping classes.
Free shipping: turn on free delivery from the amount below.
Free shipping from: the cart subtotal from which shipping is free. No API request is made in that case.
Availability without shipping zones
Ignore shipping zones: offer the method for the countries below, whatever zone matches.
Countries: the destination countries for that mode. Leave empty to use all countries the store ships to. This field is used only when Ignore shipping zones is on.
Advanced
Debug log: logs price calculations in WooCommerce > Status > Logs, source vfd-correios. 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.
Remove data on uninstall: when on, deleting the plugin removes its settings, zone methods and cached prices. Deactivating the plugin never deletes anything.
How it works at checkout
When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: cart weight, minimum order amount and excluded shipping classes. If free shipping applies, the customer gets a free rate and no request goes to Correios.
For an address in Brazil with credentials set, the plugin 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 service is saved with the order's shipping line as Correios service and is visible in the order admin.
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 method is hidden when there is no fixed price. The customer never sees API error details; they go to the WooCommerce log.
The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS).
The plugin 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.
License key
The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox Correios. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.
One key works on one domain. Removing the key from a site 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. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.
When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.
Troubleshooting
Correios does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. Without a live price, a fixed price for the country or * must exist.
The method shows a fixed price instead of the Correios price: open WooCommerce > Status > Logs, source vfd-correios. The Correios error is 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 and, if the store 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: save the settings page. This clears the cached prices and the API token.
The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.
Uninstall
Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods and cached prices are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Orders are never touched.
Correios is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Correios.