Frete é a última barreira antes do botão de compra — e uma das maiores causas de abandono de carrinho no Brasil. Um checkout que cota frete errado, não mostra prazo ou trava quando a API do transportador falha está devolvendo clientes para o Google. Este guia mostra como funciona a integração direta com os dois players mais usados no e-commerce brasileiro: os Correios e a J&T Express.

Correios: da SOAP antiga para a API REST

A integração moderna com os Correios usa a API oficial REST (api.correios.com.br) — o webservice SOAP de cálculo de preços e prazos está em descontinuação. O fluxo do módulo:

1. Autenticação por cartão de postagem: credenciais do seu contrato geram um token Bearer junto ao endpoint de autenticação.
2. Cotação em lote: peso, dimensões e CEP de origem/destino são enviados de uma vez para preço (preco/v1/nacional) e prazo (prazo/v1/nacional), retornando todos os serviços contratados numa única rodada.
3. Serviços: PAC, SEDEX, SEDEX 10, SEDEX 12, PAC Mini e SEDEX a Cobrar — você escolhe quais aparecem no checkout.
4. Rastreio integrado ao Magento: o módulo consulta o rastro oficial e alimenta o tracking nativo do pedido — o cliente acompanha pelo "Meus Pedidos" sem sair da loja.

O detalhe que separa amador de profissional: dimensões

Cotar só por peso é receita para prejuízo — os Correios cobram pelo maior entre peso real e peso cubado. O módulo permite mapear altura, largura e comprimento como atributos do produto (com fallback para defaults configuráveis), soma as dimensões dos itens do carrinho e envia o volume correto na cotação. Lojas que vendem produtos de tamanhos diferentes precisam disso desde o primeiro dia.

J&T Express: cotação, despacho e rastreio automático

A J&T Express chegou forte no last-mile brasileiro, e a integração cobre o ciclo completo via API oficial da Open Platform:

• Cotação no checkout: CEP de destino entra, preço e prazo em dias úteis saem — exibidos como método nativo de frete.
• Despacho integrado: ao faturar o pedido, o módulo cria a ordem na J&T automaticamente com os dados da nota fiscal informados no admin, gera o shipment e registra o código de rastreio real.
• Rastreio por cron: um job a cada 30 minutos consulta a API de tracking e move o pedido pelos status personalizados (aguardando coleta → em trânsito → saiu para entrega), sempre registrando o histórico no pedido.
• Etiqueta: download da etiqueta de postagem em PDF direto do admin.

Correios x J&T: quando usar cada um

Loja profissional oferece os dois lado a lado: o comprador escolhe entre cobertura máxima e melhor preço/prazo.

Checklist: o que exigir de um módulo de frete

• API atual do transportador (REST nos Correios, nada de SOAP legado).
• Cotação com dimensões reais por produto, não só peso.
• Rastreio integrado ao fluxo nativo de pedidos.
• Frete grátis configurável com regras claras (e teto de valor, para não dar prejuízo em carrinho pesado).
• Erro transparente: se a API do transportador falha, a loja avisa — nunca mostra R$ 0 nem esconde o método silenciosamente.

Instalação e configuração

Ambos os módulos instalam via Composer e aparecem como carriers nativos em Lojas > Configuração > Vendas > Métodos de Envio. Nos Correios, você informa as credenciais do contrato (cartão de postagem) e habilita os serviços; na J&T, as credenciais da Open Platform. A configuração completa com teste ponta a ponta faz parte do serviço de implantação.

Perguntas frequentes

O módulo cobra taxa por cotação ou por pedido?

Não. A integração é direta com a API do transportador; as tarifas são as do seu próprio contrato com eles.

Preciso de contrato com os Correios?

Para a API REST com tarifa comercial, sim — o cartão de postagem vem do seu contrato. Sem contrato, restam apenas tarifas avulsas bem mais caras.

O cliente rastreia dentro da loja?

Sim. Nos dois módulos o rastreamento alimenta o pedido no "Meus Pedidos", com histórico completo nas comentários da ordem.

E se a API do Correio estiver fora do ar?

O checkout continua funcionando: os métodos ficam indisponíveis com mensagem clara, e os demais métodos de entrega (inclusive a outra transportadora) seguem operando.

Funciona com produtos dimensionais?

Sim. Você cadastra altura/largura/comprimento por produto e a cotação soma os volumes do carrinho.