Token do Melhor Envio no Magento 2 expira em 30 dias

O ciclo de 30 e 45 dias

O Melhor Envio usa OAuth 2.0 com tokens no formato JWT. A documentação deles é objetiva nos prazos: o access token vale 30 dias e o refresh token vale 45. Passou dos 30 sem renovar, as chamadas de API param de ser autorizadas. Passou dos 45, nem dá mais para renovar pelo refresh: é começar o fluxo do zero.

O módulo oficial do Magento 2 não participa dessa dança. Ele tem um campo só, um textarea em Stores > Configuration > Sales > Delivery Methods > Melhor Envio, gravado no caminho carriers/melhorenvio/token. Toda chamada monta o cabeçalho assim:

'Authorization' => sprintf('Bearer %s', $this->helperData->getToken())

Quer dizer: quem renova é você, na mão, no painel do Melhor Envio. E não é só a cotação que depende disso — o cron melhorenvio_quote_check_to_updates, que roda a cada 30 minutos no grupo default e atualiza o andamento dos envios, usa o mesmo token.

O endpoint da cotação é o /api/v2/me/shipment/calculate, em https://melhorenvio.com.br ou em https://sandbox.melhorenvio.com.br quando a opção "É Sandbox" está ligada. Token de sandbox em loja de produção é o segundo motivo mais comum de frete que não aparece.

Descubra hoje quando o seu vence

Como é JWT, a data de validade está escrita dentro do próprio token, no campo exp do payload. Dá para ler sem chamar API nenhuma:

TOKEN=$(php bin/magento config:show carriers/melhorenvio/token | awk '{print $NF}')
php -r '$p = json_decode(base64_decode(strtr(explode(".", $argv[1])[1], "-_", "+/")), true); echo date("d/m/Y H:i", $p["exp"]), PHP_EOL;' "$TOKEN"

A saída é a data e a hora em que o frete vai sumir do seu checkout. Anote na agenda e renove uns cinco dias antes — não no dia, porque token que vence de madrugada de sábado vira prejuízo de fim de semana inteiro.

Se o comando não devolver nada, provavelmente o campo está vazio ou salvo em outro escopo. Confira com --scope=websites e o código do site.

Para renovar, o link é painel > gerenciar > tokens — o mesmo endereço que o próprio módulo oferece no aviso do admin. Gere, cole no campo, salve e limpe a configuração:

php bin/magento cache:clean config

Depois teste de verdade: carrinho novo, CEP real, e veja se a cotação volta. Se não voltar, o log do módulo fica em var/log/melhorenvio.log, com a requisição e a resposta da API.

Os avisos do admin, e por que não confiar só neles

O módulo tem duas mensagens de sistema que leem o exp do token. A primeira aparece quando falta mais de um dia e menos de 30:

Cadastre um novo token na Melhor Envio para manter o serviço funcionando.

E a segunda, quando já era:

Os serviços da Melhor Envio foram suspensos.

Só que o código calcula a diferença com DateTime::diff, que devolve intervalo absoluto. Token vencido há dez dias produz "10 dias de diferença" igualzinho a token que vence em dez dias — e o admin pode continuar mostrando o aviso ameno de renovação em vez do alerta de serviço suspenso.

Ou seja: o banner ajuda, mas não é termômetro confiável. Quem manda é a data que você leu do exp. E lembre que mensagem de sistema no admin só aparece para quem entra no admin — se a loja é operada por uma pessoa que passa a semana no ERP, ninguém vê nada até o cliente reclamar.

A rotina que evita o susto

O que eu deixo montado em loja que usa Melhor Envio:

• Um alerta fora do Magento. Aquele comando de ler o exp num script agendado, avisando por e-mail ou Telegram quando faltarem 7 dias. É meia hora de trabalho e resolve o problema para sempre.
• Data de renovação na agenda do time, não na cabeça de uma pessoa só. Token vence em fevereiro e o dev responsável está de férias é um cenário real.
• Checagem no monitoramento. Se você já monitora a loja, inclua uma cotação de frete de teste. Frete zerado no checkout é problema de receita, e merece o mesmo tratamento de um 500.
• Quem tem dev disponível pode ir além e implementar o refresh do OAuth com client_id e client_secret do próprio aplicativo, renovando dentro da janela de 45 dias. O módulo oficial não faz isso, então é código seu para manter — vale a pena em operação grande, não em loja pequena.

E uma dica de convivência: sempre que alguém reclamar de "frete sumiu", cheque o token antes de qualquer outra coisa. Em loja com Melhor Envio, essa é a primeira hipótese, não a última.