Solução de problemas

Quando algo dá errado, o caminho quase sempre é o mesmo: abra o log, encontre o erro, ajuste a configuração. Esta página cobre os cenários mais comuns.

Antes de qualquer coisa: ative os logs

Em WooCommerce → Configurações → Integrações → Melhor Envio, marque Log e salve. Os arquivos ficam em WooCommerce → Status → Logs, com prefixo wc-melhor-envio-. São arquivos por dia, separados por contexto:

• wc-melhor-envio-calculator-* — cotações de frete.
• wc-melhor-envio-cart-* — carrinho e checkout do Melhor Envio.
• wc-melhor-envio-tracking-* — verificação de rastreio (cron).
• wc-melhor-envio-orders-* — processamento de pedidos.
• wc-melhor-envio-queue-* — eventos de cron.
• wc-melhor-envio-webmania-* — captura de NF Webmania.

A maioria dos problemas se resolve abrindo o log certo do dia.

Métodos de entrega não aparecem no checkout

Causas mais comuns, em ordem:

1. Token expirou ou está inválido. Vá em Configurações → Integrações → Melhor Envio, gere um novo token no painel do Melhor Envio e cole. Salve.
2. Produto sem peso ou dimensões. Edite o produto e preencha Peso, Comprimento, Largura, Altura. Sem isso, o Melhor Envio não consegue cotar.
3. Zona de envio mal configurada. Em Configurações → Entrega, verifique que a zona cobre o CEP do cliente. Ordem importa: zonas mais específicas (cidade, estado) precisam vir antes das mais amplas (Brasil inteiro).
4. Métodos não habilitados na sua conta do Melhor Envio. Acesse o portal do Melhor Envio e confirme que tem PAC, Sedex, JadLog, etc ativados.
5. Lista de métodos defasada. Vá em Status → Ferramentas e clique em Atualizar lista de métodos do Melhor Envio.

Se nada disso resolveu, abra wc-melhor-envio-calculator-* do dia e procure pelo último erro — geralmente a mensagem da API do Melhor Envio aponta o problema direto.

Código de rastreio não foi importado

O rastreio é importado uma vez por intervalo do cron (a cada hora, 12 horas ou diariamente, conforme você configurou). A próxima execução pode ser disparada manualmente:

1. Vá em Configurações → Integrações → Melhor Envio.
2. Role até Eventos agendados.
3. Clique no link Forçar execução.

Se mesmo assim o rastreio não chega:

• Confirme que o rastreio já foi liberado pela transportadora no painel do Melhor Envio. O plugin só importa quando a API tem o código.
• Confirme que o pedido está num dos Status para monitorar (veja status do pedido).
• Abra wc-melhor-envio-tracking-* do dia. O log mostra exatamente quais pedidos foram verificados e o que a API retornou.

Status do pedido não atualiza automaticamente

Cheque, na ordem:

1. Token válido. Tokens expirados quebram o cron silenciosamente.
2. Status configurados corretamente. O status definido em Status após gerar etiqueta precisa estar incluído em Status para monitorar — senão o cron perde o pedido. Mesma regra pra Status após adicionar ao carrinho quando está usando esse modo. Veja status do pedido.
3. Logs do cron. Abra wc-melhor-envio-tracking-* e wc-melhor-envio-queue-* pra ver se o cron está rodando e qual a resposta da API por pedido.

Etiqueta volta com erro de "agência inválida"

Aplica-se a JadLog e Latam. A lista de agências fica em cache local e pode ficar desatualizada quando o Melhor Envio remove uma agência.

1. Vá em Status → Ferramentas.
2. Clique em Atualizar agências JadLog (ou Latam).
3. Volte em Configurações → Integrações → Melhor Envio e confirme que a agência selecionada continua na lista.

Se ela não está mais lá, escolha outra agência ativa.

Etiqueta volta com erro de "nota fiscal obrigatória"

Acontece com transportadoras privadas (todas menos Correios). Você tem três caminhos:

1. Emita a NF antes de gerar a etiqueta. Bling e Webmania importam automaticamente — veja importar nota fiscal.
2. Preencha manualmente o campo Nº da nota fiscal no metabox do pedido.
3. Marque como envio não-comercial (amostras, brindes). O plugin já envia tudo como não-comercial por padrão, então amostras passam mesmo sem NF — verifique se algum filtro customizado não está sobrescrevendo isso.

Sandbox em produção

Se você esqueceu o checkbox Sandbox marcado e gerou etiquetas, elas não são reais — não despacham. O sintoma típico: os clientes nunca recebem o pedido e o rastreio nunca atualiza.

Solução:

1. Desmarque o Sandbox.
2. Troque o token pra um da conta de produção (o token de sandbox não funciona em produção).
3. Cancele as etiquetas geradas no sandbox e gere novas.

Conflito após cancelar etiqueta

Se você cancelou uma etiqueta no painel do Melhor Envio mas não excluiu os dados no plugin (ou o contrário), a próxima tentativa de gerar etiqueta pode falhar com erro de conflito.

Solução: abra o pedido, no metabox clique em Excluir dados, depois gere a etiqueta novamente. Se ainda der conflito, confirme no painel do Melhor Envio que não há nenhum protocolo aberto pra esse pedido.

Quando nada resolveu

Reúna estas três coisas e abra um chamado de suporte:

1. Versão do plugin (em Plugins ou em composer.json).
2. Versão do WooCommerce (em Status → Status do sistema).
3. Conteúdo do log mais recente do dia em que o problema aconteceu (wc-melhor-envio-*). Os logs já vêm com tokens e dados sensíveis sanitizados, então pode anexar à vontade.

Próximos passos

• Rastreamento automático — funcionamento do cron.
• Status do pedido — mapeamento dos status.