VibeFox Correios for Adobe Commerce — Допомога
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.
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
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-correios-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/CorreiosShipping/, so that registration.php is directly in that folder.
2. Run bin/magento module:enable Vibefox_CorreiosShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.
3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Correios. 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. Enter the Correios API user, access code, posting card number, origin CEP and service. If the base currency of your store is not BRL, enter the BRL conversion rate. Fill in the fixed prices for other countries and as the fallback (see Configuration). Set Enable Correios to Yes and click Save Config.
The module adds the Correios shipping method to Magento. Customers see it as Correios - Parcel delivery (method title and method name). It is off after installation (Enable Correios = No).
Configuration
All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Correios, 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 and Method 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 Correios prices and API tokens. Numbers can be typed with a point or a comma.
If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title, longer than 64 characters or with one of the characters < > ; = # { }; an empty Method name or one longer than 64 characters; a Sort order that is not a whole number; a number field or a price in Country prices that is not a number of 0 or more; a BRL conversion rate of 0; a Min cart weight greater than the Max cart weight; an origin CEP that does not have 8 digits; an other service code with more than 5 digits.
While Enable Correios is Yes, warnings after saving remind you of settings that stop live prices or the method: only some of the three credentials are filled in, the origin CEP is missing, the BRL conversion rate is missing when the base currency is not BRL, 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. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.
General
Enable Correios: shows or hides Correios at checkout. Default: No.
Method title: the carrier name shown in the cart and at checkout. Default: Correios. Required, at most 64 characters.
Method name: shown after the method title, as "Method title - Method name". Default: Parcel delivery. Required, at most 64 characters.
Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.
The module has no tax field. If your store charges tax on shipping, set the tax class in Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.
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. Clear it and click Save Config to remove the user and 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. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved code, type a new value to change it. To delete the saved code, clear the field and click Save Config. Live prices then stop and only the fixed prices are used.
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. Default: No. Set it to No 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 are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs), and the cart is priced as one parcel of up to 30 kg.
Magento products have no standard dimensions. If your products have the attributes ts_dimensions_length, ts_dimensions_width and ts_dimensions_height, or length, width and height (in cm when the weight unit is kgs, in inches when it is lbs), the parcel size is estimated from them. Otherwise the Correios minimum size is sent.
BRL conversion rate: Correios prices are in BRL. If the base currency of your store is not BRL, enter how many units of the base 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 base 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 the base currency of your store, 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 Delete button of a row to remove it. 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 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 (the 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 discounts, tax excluded, in the base currency) reaches this amount. Leave empty to always show it.
Free shipping: turn on free delivery from the amount below. Default: No.
Free shipping from: the subtotal of the products that need shipping (after discounts, tax excluded, in the base currency) from which shipping is free. No API request is made in that case.
Ship to Applicable Countries: All Allowed Countries offers Correios for every country your store allows, Specific Countries only for the countries below.
Ship to Specific Countries: the destination countries for Specific Countries. Countries other than Brazil always get the fixed prices.
Advanced
Debug log: writes price calculations to var/log/vfd_crr_debug.log.php in the Magento 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 log. Click Clear log to empty it.
Remove data on uninstall: when Yes, uninstalling the module with its data deletes the Correios settings and the log (see Uninstall). The license key, the cached prices and tokens are always removed. The Correios services saved with orders are never deleted.
How it works at checkout
At the shipping step Magento asks the module for the Correios price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the order amount. Magento first checks the destination country, then the module checks the cart weight and Minimum order amount. If free shipping applies, the price is 0 and no request goes to Correios. A Magento cart price rule with free shipping also makes the price 0.
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. Parcels over 30 kg are not sent to the API. The BRL price is converted with your rate to the base currency; Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.
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 log.
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 store, and currency rates are not updated automatically.
Orders
When an order is placed with Correios, the module saves how its shipping price was calculated. On the admin order page (Sales > Orders > View, Information tab) the Correios block shows Correios service (for a live price, for example PAC — contract (03298)) and Price source: Live price (Correios API), Fixed price or Free shipping. The block also works for older orders and when the module is switched off. The customer does not see it.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Correios is the first row of the VibeFox Correios 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-correios 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, the Correios method is not 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 the method 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
Correios does not appear at checkout: check that the license is active and Enable Correios is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum order amount. Without a live price, a fixed price for the country or * must exist.
The method shows a fixed price instead of the Correios price: look at the Log field in the Advanced section. 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 base currency is not BRL, the BRL conversion 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 = Yes, and a production code only with No.
Rates look outdated after a change: click Save Config on the Delivery Methods page. This clears the cached prices and the API token.
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_CorreiosShipping. It removes the data and the code.
Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_CorreiosShipping to remove the data, then bin/magento module:disable Vibefox_CorreiosShipping, delete the folder app/code/Vibefox/CorreiosShipping and run bin/magento setup:upgrade.
The license key, the license status and the cached prices and tokens are always removed. If Remove data on uninstall is Yes, the Correios settings and the log are removed too. If it is No, the settings are kept for a re-install. The Correios services saved with orders (service and price source) stay with the orders.
Correios is a trademark of its respective owner. This module is not affiliated with or endorsed by Correios.