Melhor Envio Shipping & Labels for OpenCart

Overview

Melhor Envio Shipping & Labels brings the Melhor Envio carriers to your OpenCart 4 shop in Brazil: live prices at checkout from the destination CEP, shipments created from the order page, paid from your Melhor Envio wallet, generated and printed as labels, and the tracking code and status written to the order history. It connects with your own Melhor Envio app (OAuth2); there is no third-party service in between and no per-label fee from us.

What it does

• Live prices at checkout. One "Melhor Envio" shipping method with a line per service (for example Correios PAC, Correios SEDEX, Jadlog .Package), each with its delivery estimate, in reais and converted to your store currency. Only the destination CEP, the product sizes, weights and values are sent for a quote; no name, e-mail or phone.
• Price rules. Percent markup, handling fee, rounding, free shipping above a subtotal, a fallback rate when Melhor Envio cannot be reached, a services filter, tax class and geo zone like any OpenCart shipping method.
• Labels from the order page. A "Melhor Envio" tab on the order: service preselected from the customer's choice, recipient CPF or CNPJ, street, number and district filled from the order, content declaration or NF-e key, then Add to Melhor Envio cart or Pay and generate label. The print link opens the label.
• Tracking. The tracking code and the posted and delivered steps are written to the order history (the customer sees them in the account, with an optional e-mail). They arrive by an hourly cron and, when you register it, by the signed Melhor Envio webhook. Posted and delivered can move the order to the statuses you choose.
• Cancel. The extension asks Melhor Envio whether the label can still be cancelled and cancels it; Melhor Envio processes the refund of a generated label.
• Safe. Client secret and tokens are encrypted at rest and renewed automatically, the API log masks secrets and personal data, phone and e-mail go to Melhor Envio only when you switch that on. Events, cron and a shipping extension only: no OCMOD, no core edits. OpenCart 4.1, tested on 4.1.0.4.

Limits to know

• You need a Melhor Envio account and your own app (Integracoes, Area Dev.) to get the Client ID and Secret. The sandbox (sandbox.melhorenvio.com.br) is a separate environment with its own account and app; it quotes Correios and Jadlog services only.
• Paying a label uses the balance of your Melhor Envio wallet. Without balance the label stays in the Melhor Envio cart and you can continue it from the order page after adding funds.
• OpenCart has no CPF/CNPJ, street number or district fields by default. Create custom fields and pick them in the settings, or type the values on the order page before you create the label.
• One label covers all shippable items of the order in one package (the size comes from the package presets and can be changed). An order that already has an open label gets no create form, so a label is never bought twice by mistake; for a real second parcel use "additional package" (checkbox plus confirmation). The label uses the package you set, not the packages of the checkout quote, so the billed price can differ slightly from the quoted one.
• Commercial shipments need the 44-digit NF-e access key, the sender CNPJ and the sender state registration. A content declaration is allowed for individuals and for companies that do not contribute ICMS; the rules differ by carrier and state, and Melhor Envio decides.
• Azul Cargo can be quoted but its labels cannot be bought through the Melhor Envio API (see the Melhor Envio documentation); offer it only if you handle it elsewhere.
• Tested against a stand-in built from the official Melhor Envio documentation, not against the live Melhor Envio service. Run the manual steps in the Developer notes with your own sandbox account once (the exact encoding of the webhook signature is also assumed: both hex and base64 are accepted).

Melhor Envio is a trademark of its owner. This extension is not affiliated with, endorsed by or sponsored by Melhor Envio, Correios or any carrier.

Installation

Requirements: OpenCart 4.1.0.x, PHP 7.4 or newer with cURL and OpenSSL, a Melhor Envio account with a registered app.

1. In the Melhor Envio panel open Integracoes > Area Dev., create an app and note the Client ID and Client Secret. Enter the redirect address shown on the Connection tab of the extension as the app's callback URL (it must match exactly). Use the sandbox account and app first if you want to test.
2. In the OpenCart admin open Extensions > Installer, upload kv_melhor_envio.ocmod.zip and click Install.
3. Open Extensions > Extensions, choose Shipping, find Melhor Envio Shipping & Labels and click the green Install button, then the blue pencil to open the settings.
4. On the Connection tab enter your own technical contact e-mail (required: Melhor Envio asks for it in every request; nothing is filled in for you), the Client ID, the Client Secret and the sender data (name, CPF or CNPJ, address with number and district, CEP), click Save app and sender, then Connect to Melhor Envio. Melhor Envio asks you to authorize the app and sends you back; the tab shows Connected. Test connection requests one quote.
5. On the Checkout tab choose the environment (production or sandbox), click Load services and tick the services you offer (or none for all), set the status to on and save.
6. On the Orders and labels tab pick the custom fields for CPF/CNPJ, street number and district, the order statuses for posted and delivered, then save.
7. Make sure the OpenCart cron job runs (see Orders and labels), so tracking refreshes by itself.

Uninstall: Extensions > Shipping > Uninstall removes the settings, the app credentials and tokens, the label records and the log. Labels already bought stay valid at Melhor Envio and their tracking codes stay in the order history. The authorization stays listed in your Melhor Envio panel until you revoke it there. Then remove the extension in Extensions > Installer.

Update: upload the new zip in the Installer; the settings, the connection and the labels stay.

Configuration

Extensions > Extensions > Shipping > Melhor Envio Shipping & Labels > edit.

Connection

• Technical contact e-mail (required): Melhor Envio requires every request to carry your application name and a contact e-mail in the User-Agent header. Enter your own support or technical e-mail address on the Connection tab. Nothing is filled in for you (not our address and not the shop e-mail) and nothing is connected, quoted or sent to Melhor Envio until it is set. It is sent to Melhor Envio only, as KavioLabs-MelhorEnvio-OpenCart/1.0 (your-address).
• Client ID / Client Secret: from your Melhor Envio app. The secret is stored encrypted and never shown again. Changing the Client ID or the secret drops the stored tokens: connect again.
• Connect to Melhor Envio: sends you to the Melhor Envio authorization page and back. The access token is valid for 30 days and the refresh token for 45 days; the extension renews them before they expire, again when a request answers "Unauthenticated", and the hourly cron renews the connection when the last renewal is older than 15 days, so a shop without quotes or labels does not lose it after 45 days (it needs the OpenCart cron to run). If the refresh token has expired or the authorization was revoked, connect again.
• Sender: name or company, CPF (11 digits) or CNPJ (14 characters: the numeric one, or the alphanumeric CNPJ issued from July 2026, digits and letters A-Z with two check digits), state registration (IE) and CNAE (needed for some carriers and for commercial shipments), address with number and district, city, UF and CEP. The CEP is also the origin of every quote. Phone and e-mail are optional and sent only when you switch that on.

Checkout

• Environment: production or sandbox. Tokens are separate: connect again after switching.
• Services offered: Load services reads the service list from Melhor Envio. Tick the services you want; none ticked offers everything a quote returns.
• Price rules: markup (%), handling fee, free shipping from a subtotal, fallback rate (shown when Melhor Envio cannot be reached; empty hides the method then), rounding. Prices come in reais and are converted to the store currency with the currencies of your shop (add BRL in Localisation > Currencies when the store currency is another one).
• Show the delivery estimate and the carrier name in the method name, quote with insured value, receipt notice (Aviso de Recebimento) or own hand delivery (Mao Propria); tax class, geo zone, quote cache (minutes), sort order.

Orders and labels

• CPF / CNPJ, street number and district fields: pick the custom fields (System > Customers > Custom Fields, location address) that hold these values. A street line like "Rua das Flores, 120" is split into street and number automatically; address line 2 is used as district when no field is chosen. You can always edit the values on the order page before creating the label.
• Order status when posted / delivered: moved through the OpenCart order model, so your own order status events run.
• E-mail the customer when the tracking code becomes available (it is always in the order history).
• Send the recipient phone and e-mail: off by default. Both are optional in the Melhor Envio API.
• Create public print links: off by default; a private link needs a Melhor Envio login.
• Cron and webhook: the OpenCart cron (php cron.php) runs the hourly tracking refresh; the secret cron address works from any scheduler. To get instant updates register the webhook address in your Melhor Envio app (Novo Webhook); requests are checked with the X-ME-Signature header.

Packaging

Quotes send each product with its own size and weight and Melhor Envio does the packing; the default size and weight fill products without dimensions. Package presets (name, size, packing weight, maximum weight) pick the package for a label: the smallest preset that holds the order. You can change size and weight on the order page.

API log

The API log tab lists errors (and every request with the debug log on). Secrets, tokens, CPF/CNPJ, names, street addresses, phone and e-mail are masked before saving; entries older than 60 days are removed.

Usage

At checkout

The customer enters a Brazilian address and chooses the shipping method Melhor Envio and one of its lines, for example "Correios SEDEX (3-4 days) - R$ 34,40". Addresses outside Brazil get no Melhor Envio quote.

Create a label

Open the order (Sales > Orders > view) and the Melhor Envio tab under the history.

1. The service is preselected from the customer's choice. The weight and size come from the package presets; change them to what is really in the box.
2. The recipient is filled from the order. Check the CPF or CNPJ, the street number and the district; the label cannot be created without them.
3. Content declaration (the default) or commercial shipment with the 44-digit NF-e access key. Optionally tick receipt notice or own hand.

1. Add to Melhor Envio cart only inserts the shipment in the cart (you can pay it later in the Melhor Envio panel or continue it here). Pay and generate label pays with your wallet balance, generates the label and gets the print link.

The label row shows the protocol, the status and, after posting, the tracking code. Print opens the print link, Refresh reads the status from Melhor Envio (the cron job does it for open labels), Cancel cancels the label.

One label per order, and timeouts

While an order has an open label (in the cart, paid, generated, posted) the Create a label form is hidden and the server refuses a second purchase. If you really have to send a second parcel, click add an additional package, tick the box and confirm. If Melhor Envio does not answer while a label is added, paid or generated, the extension reads the real state from Melhor Envio before it does anything again: press Continue after a minute. If the message says the outcome is unknown and could not be checked, do not pay in the Melhor Envio panel either: wait and press Continue, it never pays a label Melhor Envio already shows as paid.

Pending and cancelled labels

A label that was added to the cart but not paid stays "In cart, not paid": the green Continue button pays and generates it, for example after you add funds to the wallet.

Cancel first asks Melhor Envio whether the label can be cancelled. A label the carrier has already been notified about cannot be cancelled; the refund of a cancelled generated label is processed by Melhor Envio.

Developer notes

Identity

Events and cron

Melhor Envio API conformance

Source: the official documentation at docs.melhorenvio.com.br, read on 2026-11-07. Hosts: production https://melhorenvio.com.br, sandbox https://sandbox.melhorenvio.com.br (reference "Introducao API Melhor Envio" and "Sandbox"). Every API request sends Accept: application/json, Content-Type: application/json, Authorization: Bearer <token> and the User-Agent header (see "User-Agent" below); non-GET payloads are JSON bodies.

Scopes requested (names from /reference/fluxo-de-autorização): shipping-calculate cart-write shipping-checkout shipping-generate shipping-print shipping-cancel shipping-tracking shipping-companies orders-read. Only the scopes a call of the extension needs are requested, as the page demands (cart-read is not used: the extension never reads the cart; orders-read covers GET /me/orders/{id} and the label list used to reconcile). Shops connected with the earlier list keep working; connect again only if you want the narrower authorization.

Rules from the documentation and how they are handled

User-Agent

Every page of the reference states that the User-Agent header is mandatory and must carry the application name and an e-mail for technical contact (the cancellable page shows MinhaApp ([email protected])). The extension sends KavioLabs-MelhorEnvio-OpenCart/1.0 (<contact e-mail>). The contact e-mail is a required setting that the shop owner enters (Connection tab) and is validated as an e-mail address. Nothing is pre-filled (not a Kavio Labs address and not the shop e-mail): without it no request (quote, token, label) is sent and the Connect button reports what is missing.

Double purchase protection, timeouts and reconcile

• One label per order: Labels::create runs under the database lock kv_me_label_<hash>_<order> and refuses when the order already has a label that is not cancelled or delivered (pending, released, generated, posted, ...), unless the form carries the explicit "additional package" flag together with its confirmation. The order panel hides the form while a label is open.
• Labels::advance (Continue, Pay and generate) runs under the same lock, re-reads the label row and first reads the real state with GET /api/v2/me/orders/{id} (reference "Listar informacoes de uma etiqueta"). A payment is sent only when Melhor Envio still says pending. After a checkout or generate request that ended without an answer (timeout, transport error) or with a 5xx / 408 / 429, the state is read again and the flow continues from what Melhor Envio says; if it cannot be read nothing is paid.
• A cart request without an answer leaves a marker for the order. Before another cart request the extension lists the labels in the cart (GET /api/v2/me/orders?status=pending) and adopts the one that carries the order id in options.tags, the same service and the same destination CEP instead of inserting a second one. (The search route GET /api/v2/me/orders/search?q= only looks at id, protocol, document, tracking and authorization code, so it cannot find a tag.) If the lookup fails, no new cart item is created.
• Tracking updates (webhook and cron) claim every history entry with a conditional UPDATE, so the tracking code, "posted" and "delivered" entries (and the customer e-mail) are written once.
• Token renewal fails closed when its lock cannot be taken (two renewals at once would burn the rotating refresh token); a response without a refresh_token keeps the stored one.

Flagged: not verifiable from the documentation

Testing

tests/unit.php (php81 and php83) runs against tests/mock-server/mock.php, a stand-in built from the documentation pages above (samples and error shapes copied where the pages show them), and a throw-away MariaDB database: OAuth code exchange and refresh rotation, renewal on 401, quote body and parsing, price rules, order mapping (CPF, street number, district), cart body rules, the whole flow (cart, pay, generate, print, tracking), no-balance and cancel, webhook signature, log masking, and the regression tests of the 2026-11-07 review: one label per order, order lock, double submit, lost cart / checkout / generate answers reconciled from the real state, alphanumeric CNPJ and NF-e key, content declaration without state registration, contact e-mail in the User-Agent, concurrent tracking updates, token lock, keep-alive and a missing refresh token. tests/e2e.js drives an OpenCart 4.1.0.4 store in a headless browser: app and sender form, OAuth through the authorization redirect, checkout quotes for a Brazilian address, price rules, fallback, the order page flow, cron, signed webhook, expired token renewal, uninstall.

Manual steps with your own account (not done by us): create a sandbox account and app, enter the Client ID and Secret, connect, compare a quote with the Melhor Envio calculator, create one label (content declaration) and cancel it; check the exact response of the services list and the webhook signature encoding against your account, and report differences.

Melhor Envio is a trademark of its owner. This extension is not affiliated with, endorsed by or sponsored by Melhor Envio, Correios or any carrier.

FAQ

Do I need a Melhor Envio account?

Yes, and your own app (Integracoes, Area Dev.) for the Client ID and Secret. There is no aggregator account and no per-label fee from us.

Can I test without spending money?

Yes. Create a sandbox account and app at sandbox.melhorenvio.com.br, choose the sandbox environment and connect. The sandbox quotes Correios and Jadlog services, starts with a fictitious balance and moves shipments to posted and delivered by itself.

Where do the CPF/CNPJ, street number and district come from?

From custom fields you choose in the settings, from the street line (number) and address line 2 (district), or typed on the order page. OpenCart has no such fields by default.

Which customer data is sent to Melhor Envio?

For a quote only the destination CEP and the product sizes, weights and values. For a label the recipient data the API requires (name, document, address). Phone and e-mail only when you switch it on.

What if the wallet has no balance?

The label stays in the Melhor Envio cart; after adding funds use Continue on the order page.

Can I cancel a label?

Yes, from the order page, as long as Melhor Envio says it can still be cancelled.

Does it work with OpenCart 3?

No, OpenCart 4.1 only.

Does it use OCMOD?

No. A shipping extension, events and cron.

Is it affiliated with Melhor Envio?

No. Melhor Envio is a trademark of its owner.