VibeFox Melhor Envio for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superiores (testado na 4.1.0.3).
PHP: 8.0 ou superior.
Conta do Melhor Envio (somente para cotações em tempo real): as cotações em tempo real 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). Tokens de produção e de sandbox são diferentes. Não há botão de «conectar»: você cola o token nas configurações da extensão. Sem token, o método usa os preços de contingência.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 vfd_melhor_envio-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_melhor_envio.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_melhor_envio-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então você não precisa atualizar Extensions > Modifications. Em vez do Installer, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Melhor Envio e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.
4. Digite a sua chave de licença VibeFox em License key no bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).
5. Cole o token de acesso, o seu e-mail de contato e o CEP de origem. Se a moeda padrão da sua loja não for BRL, defina BRL exchange rate. Opcionalmente, preencha a tabela de preços de contingência (por exemplo, para o Brasil) ou um custo de contingência. Ative Enable Melhor Envio shipping e clique em Save.
OpenCart 4
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_melhor_envio.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.
2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.
3. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Melhor Envio, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Informe a chave de licença e as configurações como nos passos 4 e 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.
Após a instalação, o método fica desligado até que você ative Enable Melhor Envio shipping e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações que você manteve serão usadas de novo.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit. As seções aparecem à esquerda. Um botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as cotações do Melhor Envio em cache e o último erro da API. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.
Avisos no topo da página (e após cada salvamento) mostram uma configuração incompleta: um CEP de origem vazio ou que não tenha 8 dígitos, um e-mail de contato ausente, uma taxa de câmbio BRL ausente, nenhum token e nenhum preço de contingência (nesse caso o método nunca é exibido), o último erro da API do Melhor Envio com a data (quando há um token salvo), ou uma loja sem uma classe de peso «kg» ou uma classe de comprimento «cm» (as unidades são então convertidas pelo nome, e unidades desconhecidas são lidas como kg ou cm). Se Name estiver vazio, for longo demais ou contiver um dos caracteres < > ; = # { }, se um campo numérico tiver 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.
Geral
As configurações valem para todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Availability. O preço sempre vem da extensão.
Enable Melhor Envio shipping: mostra ou oculta o Melhor Envio na finalização de compra. Padrão: off.
Name: o nome do método de envio exibido aos clientes no carrinho e na finalização de compra. Padrão: Melhor Envio. Obrigatório, no máximo 64 caracteres.
Sort order: a posição do Melhor Envio entre os métodos de envio na finalização de compra. Um número inteiro.
API do Melhor Envio
Access token: o token do ambiente selecionado abaixo. Ele é enviado ao Melhor Envio como token Bearer. Após salvar, o campo fica vazio e mostra A token is saved — leave empty to keep it. Digite um novo token somente para trocá-lo. Para apagar o token salvo, marque Remove the saved token e salve. O token nunca é gravado no log.
Sandbox: use o sandbox do Melhor Envio (sandbox.melhorenvio.com.br) para testes. Use com ele um token de sandbox. Padrão: off.
Contact e-mail: um e-mail de contato técnico, enviado ao Melhor Envio no cabeçalho User-Agent de cada requisição, por exemplo tech@example.com. 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. O OpenCart não tem um CEP da loja, por isso as cotações em tempo real precisam deste campo. Um CEP que não tenha 8 dígitos é salvo com um aviso, mas nenhuma cotação é solicitada.
Services: IDs de serviço do Melhor Envio separados por vírgula, opcionais, para cotar, 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 mostradas.
Delivery time: mostra a estimativa de entrega do Melhor Envio ao lado do nome, por exemplo «(3-5 business days)». Padrão: on.
Declared value: declara o valor dos produtos (seguro) nas cotações. Quando desligado, as cotações são feitas sem valor declarado: mais baratas, mas as encomendas não ficam seguradas. Padrão: on.
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 em tempo real não são usadas. O valor deve ser maior que 0. O valor declarado é convertido para BRL com a mesma taxa. Se a sua moeda padrão for BRL, o campo informa que os preços do Melhor Envio são usados como estão.
Default product weight (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 (cm): comprimento x largura x altura, usado para produtos sem dimensões. Padrão: 16x11x5.
Preços de contingência (na moeda padrão da sua loja)
Os preços de contingência são usados quando não há token, o CEP de destino está ausente ou a API não fornece cotação (erro, tempo esgotado, falta de cobertura).
Fallback price table: preço por país e peso do carrinho, sem impostos. Clique em Add country para adicionar uma linha (uma linha nova começa com o Brasil) e no botão de remover para excluir uma. Escolha * Any country para todo país sem linha própria. Cada linha tem um Price e colunas de peso: XS até 1 kg, S de 1 a 2 kg, M de 2 a 3 kg, L de 3 a 5 kg e XL acima de 5 kg. Uma coluna vazia ou 0 usa o Price, e um Price de 0 significa frete grátis. 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. Linhas sem nenhum preço são removidas.
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 (padrão) cobra o preço de contingência uma vez. Per item (each item priced by its own weight x quantity) procura o preço de contingência para o peso de cada item (o peso padrão, se ele não tiver peso) e o multiplica pela quantidade. Isso vale apenas para os preços de contingência. As cotações do Melhor Envio já incluem todos os itens.
Disponibilidade
Min weight (kg): oculta o método quando o carrinho pesa menos. 0 significa sem limite (padrão).
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 30. 0 significa sem limite. Campo vazio significa 30 kg, ou sem limite quando Ignore shipping zones está ativado.
Minimum subtotal: mostra o método somente se o subtotal do carrinho (produtos que precisam de envio, após o cupom, antes dos impostos) for pelo menos este valor. Deixe em branco para sempre mostrá-lo.
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 em branco para desativar.
Tax class: a classe de imposto acrescentada sobre o custo do envio, ou No tax (padrão). Os preços do Melhor Envio são tarifas finais das transportadoras. Escolha No tax se o OpenCart não deve acrescentar imposto a eles.
Geo zone: oferece o Melhor Envio somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones. A zona geográfica não é verificada quando Ignore shipping zones está ativado.
Disponibilidade sem zonas de envio
Normalmente o método é oferecido na zona geográfica selecionada em Availability (todas as zonas quando nenhuma está selecionada).
Ignore shipping zones: oferece o método para os países indicados abaixo, qualquer que seja a zona geográfica selecionada. Nesse modo, a zona geográfica não é verificada.
Countries: os países de destino desse modo. Deixe em branco para todos os países. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava as requisições à API e o cálculo das tarifas em storage/logs/vfd_menv_debug.log.php (no OpenCart 4, system/storage/logs/vfd_menv_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados, mesmo com esta opção desativada. O token nunca é registrado, e o CEP do cliente é abreviado para os 5 primeiros dígitos. Quando o arquivo chega a 5 MB, ele é movido para vfd_menv_debug.old.log.php e um novo log é iniciado.
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 ativado, desinstalar a extensão apaga todas as configurações e o log. Quando desativado (padrão), eles são mantidos para uma nova instalaçã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.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. O token de acesso não é exportado.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Os valores são verificados como em um salvamento normal. O token de acesso salvo é mantido.
Como funciona na finalização de compra
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do Melhor Envio. Se uma Geo zone estiver definida e o endereço estiver fora dela, o Melhor Envio não é oferecido. Com Ignore shipping zones, a zona geográfica não é verificada: o Melhor Envio só é oferecido quando o país está em Countries (ou Countries está vazio). Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no subtotal. Em seguida, a extensão verifica o peso do carrinho e o subtotal mínimo.
Para um endereço de entrega no Brasil com CEP de 8 dígitos, a extensão 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. O Model do produto é enviado como ID do item. Serviços com erro ou sem preço são ignorados. As cotações são convertidas para a sua moeda padrão, arredondadas nas suas casas decimais, ordenadas por preço e exibidas na moeda do cliente com o imposto da Tax class selecionada. Se o frete grátis se aplicar, o serviço mais barato custa 0.
Com One option - the cheapest service, o cliente vê uma opção, por exemplo Melhor Envio (6-7 business days). Com One option per service, o cliente vê uma opção por serviço, por exemplo Melhor Envio: Correios SEDEX (1-2 business days). A estimativa de entrega só é adicionada quando Delivery time está ativado.
Cada cotação fica em cache por 1 hora, então o mesmo carrinho não dispara uma nova requisição. Uma chamada com falha é lembrada por 5 minutos, para que uma indisponibilidade 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, faltar a taxa de câmbio BRL, ou o Melhor Envio retornar erro ou nenhum serviço para a rota, os preços de contingência são usados: a linha do país (ou a linha * quando o país não tem linha), senão o custo de contingência. Essa opção leva simplesmente o nome indicado em Name. Se o frete grátis se aplicar, o método é mostrado sem custo mesmo sem preço. Se não houver preço nenhum, o método fica oculto. O cliente nunca vê um erro da API. O motivo é gravado no log.
No OpenCart 4, o cliente clica em Choose no bloco de método de envio da página de finalização de compra e escolhe uma opção do Melhor Envio na janela Shipping method options. As opções e os preços são os mesmos do OpenCart 3.
A extensão calcula apenas os preços. Ela 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 escolha de agências transportadoras (pontos de postagem). Gerencie os envios no seu painel do Melhor Envio. O Melhor Envio envia somente dentro do Brasil. Os demais países recebem apenas os preços de contingência.
Pedidos
O OpenCart salva o nome da opção escolhida como método de envio do pedido, então o serviço e a estimativa de entrega aparecem nos e-mails de pedido, na conta do cliente e em Sales > Orders.
Quando um pedido é feito com uma cotação em tempo real, a extensão também salva o serviço do Melhor Envio exatamente como o cliente o viu na etapa de entrega, sem uma nova requisição. A página do pedido no admin, em Sales > Orders, mostra um bloco Melhor Envio com Melhor Envio service, Service ID e Delivery estimate, para que você saiba qual serviço contratar no Melhor Envio. O cliente vê Melhor Envio service e Delivery estimate na página do pedido em sua conta. Pedidos feitos com um preço de contingência não têm serviço. Os pedidos existentes não são afetados.
No OpenCart 4, o bloco Melhor Envio é exibido acima de History. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza sempre que o cliente confirma de novo: o serviço salvo é atualizado junto, e é removido quando o cliente troca para outro método de envio ou quando o pedido recebe um preço de contingência.
Chave de licença
A extensão funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Melhor Envio é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Melhor Envio > Edit, acima das configurações. Digite 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo aparecem a linha Product: opencart-shipping-melhor-envio e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 com 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o endereço da loja da configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio dela. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o Melhor Envio não é mostrado aos clientes na finalização de compra e nenhuma cotação é calculada. Um usuário administrador conectado ao admin no mesmo navegador ainda vê o método na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do admin, então, sem uma chave ativa, o método fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar a extensão 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: verifique se a licença está ativa e se Enable Melhor Envio shipping está ativado. Confira a Geo zone, ou ative Ignore shipping zones e confira Countries. Veja os avisos no topo da página da extensão, os limites de peso e o Minimum subtotal. Sem token ou cotação, o método precisa de um preço de contingência: uma linha na Fallback price table ou um Fallback cost. Verifique se os produtos têm Requires Shipping definido como Yes.
Somente preços de contingência são mostrados: ative Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Motivos comuns: não há token, um CEP de origem que não tem 8 dígitos, não há BRL exchange rate para uma moeda padrão 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 recusou 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.
O imposto é acrescentado ao preço do Melhor Envio: defina Tax class como No tax.
As cotações parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as cotações em cache.
A página diz "Warning: You do not have permission to modify VibeFox Melhor Envio!": o seu grupo de usuários administradores só pode visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_melhor_envio (OpenCart 3) ou extension/vfd_melhor_envio/shipping/vfd_melhor_envio (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API de cotações do Melhor Envio pode ser substituído pela configuração vfd_menv_api_url (para testes); ela não tem campo na página de configurações.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Melhor Envio. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Melhor Envio shipping, Sort order, Tax class e Geo zone. O cache de cotações é sempre removido. Se Remove data on uninstall estiver ativado, as demais configurações e o log de depuração também são apagados. Se estiver desativado, eles são mantidos e usados novamente quando você instalar a extensão de novo. Os serviços salvos com os pedidos são sempre mantidos, e os pedidos existentes conservam o seu método de envio e o seu custo.
No OpenCart 4, para remover também os arquivos da extensão, depois da desinstalação acesse Extensions > Installer e clique em Uninstall (o botão laranja −) ao lado de VibeFox Melhor Envio na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
O Melhor Envio é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo Melhor Envio.