VibeFox Melhor Envio for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Conta no Melhor Envio (somente para cotações ao vivo): as cotações ao vivo precisam de um token de acesso. Na sua conta do Melhor Envio, abra a página de permissões de acesso para tokens (Integrações > Permissões de acesso, melhorenvio.com.br/painel/gerenciar/tokens) e gere um token com a permissão «shipping-calculate». Para testes, gere um token no sandbox do Melhor Envio (sandbox.melhorenvio.com.br/painel/gerenciar/tokens). Tokens de produção e de sandbox são diferentes. Os tokens expiram. Não há botão de «conectar»: você cola o token nas configurações. Sem token, o método usa os valores alternativos.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_melhor_envio para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Melhor Envio, ou clique em Settings abaixo do nome do plugin na página de Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Cole o token de acesso, seu e-mail de contato e o CEP de origem. Se a moeda da sua loja não for BRL, defina o BRL exchange rate. Opcionalmente, preencha a tabela de preços alternativos (por exemplo, para o Brasil) ou um custo alternativo.
6. Adicione uma zona para o Brasil em WooCommerce > Settings > Shipping > Shipping zones e inclua nela o VibeFox Melhor Envio, ou ative Ignore shipping zones e escolha os países.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Elas valem para todas as zonas de envio. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome desta opção na finalização de compra. Deixe em branco para usar o Name global.
Os avisos no topo da página indicam configuração incompleta: um CEP de origem que não tem 8 dígitos, um e-mail de contato ausente, uma taxa de câmbio BRL ausente, o último erro da API do Melhor Envio com a data, ou nenhum token e nenhum preço alternativo. Sempre que você salva as configurações, as cotações em cache são limpas.
Geral
Enable/Disable: ativa ou desativa o envio pelo Melhor Envio em todas as zonas de uma vez.
Name: o nome do método de envio exibido aos clientes na finalização de compra. Padrão: Melhor Envio.
Tax status: Taxable adiciona o imposto do WooCommerce ao valor do frete, None não adiciona.
API do Melhor Envio
Access token: o token do ambiente selecionado abaixo. Ele nunca é gravado no log.
Sandbox: usa o sandbox do Melhor Envio (sandbox.melhorenvio.com.br) para testes. Use com um token de sandbox. Padrão: desativado.
Contact e-mail: um e-mail de contato técnico, enviado ao Melhor Envio em cada requisição. O Melhor Envio exige esse dado de todas as integrações.
Origin CEP: o CEP (8 dígitos) de onde as encomendas são enviadas, por exemplo 01310-100. Sem um CEP de origem válido, nenhuma cotação é solicitada.
Services: IDs de serviço do Melhor Envio opcionais, separados por vírgula, para cotar, por exemplo 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Deixe em branco para cotar todos os serviços da sua conta.
Quotes at checkout: como as cotações são exibidas.
Delivery time: exibe ao lado do nome a estimativa de entrega do Melhor Envio, por exemplo «(3-5 business days)». Padrão: ativado.
Declared value: declara o valor do produto (seguro) nas cotações. Quando desativado, as cotações são feitas sem valor declarado: mais baratas, mas as encomendas não ficam seguradas. Padrão: ativado.
BRL exchange rate: o Melhor Envio cota em reais. Só é necessário se a moeda da sua loja não for BRL: informe o preço de 1 BRL na moeda da loja, por exemplo 0.17. Sem ele, as cotações ao vivo não são usadas. O valor declarado é convertido para BRL com a mesma taxa.
Default product weight (kg): usado para produtos sem peso, tanto nas cotações quanto nos limites de peso. Padrão: 0.3.
Default product size (cm): comprimento x largura x altura usados para produtos sem dimensões. Padrão: 16x11x5.
Fallback prices (na moeda da sua loja)
Os valores alternativos são usados quando não há token, o CEP de destino está ausente ou a API não retorna cotação (erro, tempo esgotado, sem cobertura).
Fallback price table: preço por país e peso do carrinho. Clique em + Add country para adicionar uma linha e no X para remover uma. Escolha * Any country para todos os países sem linha própria. Cada linha tem um Price e colunas de peso: XS até 1 kg, S 1-2 kg, M 2-3 kg, L 3-5 kg e XL acima de 5 kg. Uma coluna vazia ou com 0 usa o Price. Tanto «9.99» quanto «9,99» são aceitos. Valores que não são números são informados após salvar e ignorados.
Fallback cost: usado quando a tabela também não tem preço. Deixe em branco para ocultar o método nesse caso.
Fallback calculation: Per order cobra o valor alternativo uma vez. Per item (each item priced by its own weight x quantity) busca o valor alternativo para o peso de cada item (o peso padrão, se ele não tiver) e o multiplica pela quantidade. Isso vale apenas para os valores alternativos. As cotações do Melhor Envio já incluem todos os itens.
Availability
Min weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite.
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite.
Minimum subtotal: exibe o método somente se o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe em branco para exibir sempre.
Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Com uma opção por serviço, só o serviço mais barato fica grátis. Serviços mais rápidos mantêm o preço. Deixe em branco para desativar.
Excluded shipping classes: oculta o método quando o carrinho contém itens de qualquer uma dessas classes de envio do WooCommerce.
Ignore shipping zones: oferece o método para os países abaixo, mesmo sem ele estar incluído em uma zona de envio.
Countries: os países de destino para esse modo. Deixe em branco para todos os países. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: registra as requisições à API e o cálculo das cotações em WooCommerce > Status > Logs (origem vfd-melhor-envio). Erros são sempre registrados, mesmo com esta opção desativada. O token e os endereços dos clientes nunca são registrados.
Remove data on uninstall: quando ativado, excluir o plugin remove todas as suas configurações e os métodos das zonas. Desativar o plugin nunca apaga as configurações.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede uma cotação ao plugin. O plugin verifica primeiro as condições: peso do carrinho, subtotal mínimo e classes de envio excluídas.
Para um endereço de entrega no Brasil com CEP de 8 dígitos, o plugin envia ao Melhor Envio o CEP de origem e o de destino e cada item enviável com peso, tamanho, quantidade e valor declarado, além da lista de serviços, se você tiver definido uma. As cotações são convertidas para a moeda da loja e ordenadas por preço. O cliente vê o serviço mais barato ou uma opção por serviço, com a estimativa de entrega se ela estiver ativada. Se o frete grátis se aplicar, o serviço mais barato custa 0.
Cada cotação fica em cache por 1 hora por encomenda, CEP e ambiente, para que o mesmo carrinho não gere uma nova requisição. Uma chamada que falhou é lembrada por 5 minutos, para que uma queda da API não deixe lento cada atualização da finalização de compra. O tempo limite da API é de 12 segundos.
Se não houver token, o endereço estiver fora do Brasil ou ainda não tiver um CEP válido, a taxa de câmbio BRL estiver ausente, ou o Melhor Envio retornar erro ou nenhum serviço para a rota, são usados os valores alternativos: a linha do país (ou a linha *) e, se não houver, o custo alternativo. Se o frete grátis se aplicar, o método aparece sem custo mesmo sem preço. Se não houver nenhum preço, o método fica oculto. O cliente nunca vê um erro da API.
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalizar compra. É compatível com o HPOS (armazenamento de pedidos de alta performance) do WooCommerce.
O plugin calcula apenas os preços. Ele não compra nem gera etiquetas, não adiciona envios ao carrinho do Melhor Envio, não rastreia encomendas, não agenda coletas nem envia dados da nota fiscal (NF-e). Não oferece a escolha de agências (pontos de postagem) da Jadlog, Azul ou LATAM, nem os serviços extras «mão própria» e «aviso de recebimento». Gerencie os envios no seu painel do Melhor Envio. O Melhor Envio envia somente dentro do Brasil. Outros países recebem apenas os valores alternativos.
Pedidos
Quando o pedido é feito com uma cotação ao vivo, o serviço e a estimativa de entrega são salvos na linha de frete do pedido. Eles aparecem na tela do pedido e nos e-mails de pedido como Melhor Envio service e Delivery estimate, para que você saiba qual serviço contratar no Melhor Envio. Pedidos existentes mantêm suas linhas de frete.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Melhor Envio. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta no vibefox.net.
Sem uma chave ativa, o Melhor Envio não é exibido aos clientes na finalização de compra. Os gestores da loja logados continuam vendo o método, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente, automaticamente, em segundo plano.
Solução de problemas
O Melhor Envio não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o método está incluído na zona do país do cliente (ou se Ignore shipping zones está ativado e o país está permitido). Confira os avisos no topo da página de configurações, os limites de peso, Minimum subtotal e Excluded shipping classes. Sem token ou cotação, o método precisa de um preço alternativo: uma linha em Fallback price table ou um Fallback cost.
Só aparecem preços alternativos: ative o Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs, origem vfd-melhor-envio. Motivos comuns: falta o token, o CEP de origem não tem 8 dígitos, falta o BRL exchange rate para uma moeda da loja diferente de BRL, ainda não há CEP de destino ou nenhum serviço atende a rota.
HTTP 401 ou 403 no log ou nos avisos: o Melhor Envio rejeitou o token de acesso. Ele está errado, expirado ou revogado, ou pertence ao outro ambiente. Gere um novo token e verifique se Sandbox corresponde a ele.
Qual preço o cliente vê: com uma opção, o serviço mais barato retornado pelo Melhor Envio. Com uma opção por serviço, cada serviço que atende a rota. Per item vale apenas para os preços alternativos.
As cotações parecem desatualizadas após uma mudança: salve a página de configurações. Isso limpa as cotações em cache.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta no vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todas as configurações. Somente o cache de cotações é limpo. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin, assim como as cotações em cache, são sempre removidos. Configurações e métodos das zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Pedidos existentes mantêm suas linhas de frete.
Melhor Envio é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo Melhor Envio.