VibeFox Melhor Envio for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Conta no Melhor Envio (apenas 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 tokens (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. Não há botão de «conectar»: você cola o token nas configurações do módulo. Sem token, a transportadora usa os preços alternativos.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure ou encontre depois o VibeFox Melhor Envio na lista de módulos e clique em Configure.
3. Informe sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Cole o token de acesso, seu e-mail de contato e o CEP de origem. Se a moeda padrão 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. Clique em Save.
Ao instalar, o módulo cria a transportadora Melhor Envio com o texto de prazo Delivery by the carriers of your Melhor Envio account. A transportadora é associada a todas as zonas e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Melhor Envio > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações em cache do Melhor Envio e o último erro da API.
Os avisos no topo da página indicam uma configuração incompleta: CEP de origem vazio ou sem 8 dígitos, e-mail de contato ausente, taxa de câmbio BRL ausente, o último erro da API do Melhor Envio com a data, ausência de token, ausência de preço alternativo (nesse caso a transportadora nunca é exibida) ou uma unidade de peso ou de dimensão da loja que o módulo não reconhece (ela é então lida como kg ou cm). Se um campo numérico contiver algo que não seja um número igual ou maior que 0, se Min weight for maior que Max weight ou se Default product size não estiver no formato comprimento x largura x altura, a página mostra um erro e nada é salvo.
General
Enable Melhor Envio shipping: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome da transportadora mostrado aos clientes na finalização de compra. Padrão: Melhor Envio. Obrigatório, no máximo 64 caracteres.
Tax: a regra de imposto da transportadora, ou No tax. Os preços do Melhor Envio são preços finais da transportadora. Escolha No tax se o PrestaShop não deve acrescentar imposto a eles.
Melhor Envio API
Access token: o token do ambiente selecionado abaixo. Ele é enviado ao Melhor Envio como token Bearer. Depois de salvar, o campo fica vazio e mostra A token is saved — leave empty to keep it. Digite um token novo somente para trocá-lo. Para apagar o token salvo, marque Remove the saved token e salve. O token 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: desligado.
Contact e-mail: um e-mail de contato técnico, enviado ao Melhor Envio no cabeçalho User-Agent de cada requisição. O Melhor Envio exige essa informação de todas as integrações. Um endereço inválido não é salvo, e um aviso informa isso.
Origin CEP: o CEP (8 dígitos) de onde as encomendas são enviadas, por exemplo 01310-100. Ele é salvo no formato 00000-000. Sem um CEP de origem válido, nenhuma cotação é solicitada.
Services: IDs de serviços do Melhor Envio separados por vírgula, para cotar (opcional), por exemplo 1 = Correios PAC, 2 = Correios SEDEX, 17 = Correios Mini Envios, 3 = Jadlog .Package, 4 = Jadlog .Com. Deixe vazio para cotar todos os serviços da sua conta.
Quotes at checkout: como as cotações são exibidas.
Delivery time: exibe na finalização de compra a estimativa de entrega do Melhor Envio, por exemplo «3-5 business days». Padrão: ligado.
Declared value: declara o valor do produto (seguro) nas cotações. Quando desligado, as cotações são feitas sem valor declarado: ficam mais baratas, mas as encomendas não ficam seguradas. Padrão: ligado.
BRL exchange rate: o Melhor Envio cota em reais. Só é necessário se a moeda padrão da sua loja não for BRL: informe o preço de 1 BRL na sua moeda padrão, por exemplo 0.17. Sem ele, as cotações ao vivo não são usadas. O valor precisa ser maior que 0. O valor declarado é convertido para BRL com a mesma taxa. Se a sua moeda padrão for BRL, o campo mostra Store currency is BRL.
Default product weight: em kg, usado para produtos sem peso, tanto nas cotações quanto nos limites de peso. Deve ser maior que 0. Padrão: 0.3.
Default product size: comprimento x largura x altura em cm, usado para produtos sem dimensões. Padrão: 16x11x5.
Preços alternativos (na moeda padrão da sua loja)
Os preços alternativos são usados quando não há token, o CEP de destino está ausente ou a API não devolve uma 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 ícone de lixeira para remover uma. Escolha * Default como país para todos os países que não tiverem 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 o salvamento e ignorados.
Fallback cost: usado quando a tabela também não tem preço. Deixe vazio para ocultar a transportadora nesse caso.
Fallback calculation: Per order cobra o preço alternativo uma vez. Per item (each item priced by its own weight x quantity) busca o preço alternativo para o peso de cada item (o peso padrão, se ele não tiver um) e o multiplica pela quantidade. Se um item não tiver preço, a transportadora fica oculta. Isso vale somente para os preços alternativos. As cotações do Melhor Envio já incluem todos os itens.
Disponibilidade
Min weight: oculta a transportadora quando o carrinho pesa menos, em kg. 0 significa sem limite.
Max weight: oculta a transportadora quando o carrinho pesa mais, em kg. Padrão: 30. 0 significa sem limite. Um campo vazio significa 30 kg nas zonas da transportadora, e sem limite apenas para os países de Ignore shipping zones que estiverem fora delas.
Minimum subtotal: mostra a transportadora somente se o subtotal do carrinho (produtos que precisam de envio, após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para mostrar sempre.
Free shipping from: o subtotal do carrinho a partir do qual o frete é grátis. Com uma opção por serviço, somente o serviço mais barato fica grátis. Serviços mais rápidos mantêm o preço. Deixe vazio para desativar.
Ignore shipping zones: oferece a transportadora nos países indicados abaixo, mesmo que ela não esteja associada às zonas deles. Enquanto estiver ligado, a transportadora fica vinculada a todas as zonas, inclusive zonas inativas e zonas criadas depois. Ao desligar, a transportadora recupera as próprias zonas.
Countries: os países de destino para esse modo. Deixe vazio para todos os países. Este campo só é usado quando Ignore shipping zones está ligado.
Avançado
Debug log: grava as requisições à API e o cálculo das cotações em logs/vfd_menv_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros são sempre registrados, mesmo com esta opção desligada. O token nunca é registrado e o CEP do cliente é encurtado para os 5 primeiros dígitos.
Log: mostra o tamanho e as entradas mais recentes do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ligado, desinstalar o módulo apaga todas as configurações do módulo, a transportadora e o log. Quando desligado, tudo é mantido para uma reinstalação. O cache de cotações é sempre removido. Os serviços salvos com os pedidos fazem parte do histórico de pedidos e são mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço do Melhor Envio. Apenas produtos que precisam de envio são considerados: produtos virtuais não somam peso e não entram no subtotal. O módulo verifica primeiro as condições: os países de Ignore shipping zones, o peso do carrinho e o subtotal mínimo.
Para um endereço de entrega no Brasil com CEP de 8 dígitos, o módulo 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 padrão da sua loja, ordenadas por preço e então exibidas na moeda do carrinho do cliente. Se o frete grátis se aplicar, o serviço mais barato custa 0.
Com One option - the cheapest service, a transportadora mostra o preço do serviço mais barato e a linha Delivery estimate: abaixo da transportadora, se Delivery time estiver ligado. Com One option per service, o cliente vê Choose a delivery service: abaixo da transportadora, com um botão de opção por serviço, seu preço e a estimativa de entrega. A escolha é salva imediatamente, e o preço da transportadora e o resumo do carrinho são atualizados. Se o serviço não for mais oferecido para o endereço, o cliente vê This service is not available for your address any more. Please choose another one. e a escolha anterior volta.
Cada cotação fica em cache por 1 hora por encomenda, CEP, token e ambiente, então o mesmo carrinho não dispara uma nova requisição. Uma chamada que falhou é lembrada por 5 minutos, para que uma queda da API não deixe lenta 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, o BRL exchange rate estiver ausente, ou o Melhor Envio retornar erro ou nenhum serviço para a rota, os preços alternativos são usados: a linha do país (ou a linha *), senão o custo alternativo. Se o frete grátis se aplicar, a transportadora é exibida sem custo, mesmo sem preço. Se não houver nenhum preço, a transportadora fica oculta. O cliente nunca vê um erro da API.
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo passa a seguir a nova versão automaticamente.
O módulo 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 e não envia dados da nota fiscal (NF-e). Não oferece a seleção de agências (pontos de postagem) da Jadlog, da Azul ou da 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 preços alternativos.
Pedidos
Quando um pedido é feito com uma cotação ao vivo, o módulo salva com o pedido o serviço do Melhor Envio e a sua estimativa de entrega. A página do pedido no back office mostra um bloco Melhor Envio com Melhor Envio service (com o ID do serviço) e Delivery estimate, para que você saiba qual serviço comprar no Melhor Envio. O cliente vê as mesmas informações na página do pedido em sua conta. No e-mail de confirmação do pedido, elas são acrescentadas depois do nome da transportadora. Pedidos feitos com preço alternativo não têm serviço. Pedidos existentes não são afetados.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Melhor Envio é o primeiro bloco em Modules > Module Manager > VibeFox Melhor Envio > Configure, acima das configurações. Cole a chave em License key e clique em Activate. Depois disso, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-shipping-melhor-envio e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure do módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Depois que o endereço da loja mudar, ou depois que você liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a transportadora Melhor Envio não é exibida aos clientes na finalização de compra e nenhuma cotação é calculada. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a transportadora também fica oculta para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida e depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
O Melhor Envio não aparece na finalização de compra: confira se a licença está ativa e se Enable Melhor Envio shipping está ligado. Em Shipping > Carriers, confira se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ligue Ignore shipping zones e confira Countries. Verifique os avisos no topo da página do módulo, os limites de peso e o Minimum subtotal. Sem token ou cotação, a transportadora precisa de um preço alternativo: uma linha em Fallback price table ou um Fallback cost. Produtos também podem ser limitados a certas transportadoras na página do produto.
Só aparecem preços alternativos: ligue o Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Motivos comuns: falta o token, o CEP de origem não tem 8 dígitos, falta o BRL exchange rate para uma moeda padrão diferente de BRL, ainda não há CEP de destino ou nenhum serviço cobre 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 token novo e confira se o Sandbox corresponde a ele.
O cliente vê «The service could not be saved. Please try again.»: a escolha não chegou à loja, por exemplo por causa de um erro de rede. O cliente pode escolher o serviço novamente. O serviço selecionado quando o cliente clica em Continue também é salvo.
O imposto é somado ao preço do Melhor Envio: defina Tax como No tax.
As cotações parecem desatualizadas após uma mudança: clique em Save na página do módulo. Isso limpa as cotações em cache.
A página diz que a transportadora do Melhor Envio não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Restaure o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Melhor Envio e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. O cache de cotações é sempre removido. Se Remove data on uninstall estiver ligado, a transportadora é excluída (os pedidos mantêm o histórico), suas próprias zonas são restauradas e as configurações, as escolhas de serviço dos carrinhos abertos e o log são removidos. Se estiver desligado, a transportadora apenas é desativada e todas as configurações são mantidas. Ao instalar o módulo novamente, a transportadora recupera o status que tinha antes. Os serviços salvos com os pedidos são sempre mantidos.
Melhor Envio é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Melhor Envio.