VibeFox Frenet for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e superior (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Conta no Frenet (somente para cotações em tempo real): crie uma conta gratuita no painel do Frenet (painel.frenet.com.br), ative as transportadoras que você usa e copie o seu token de API. Se você usa apenas preços fixos, não precisa de uma conta no Frenet.
Produtos: preencha o peso e as dimensões para preços precisos. Produtos sem esses dados são cotados como 0,3 kg e 16 × 11 × 2 cm (a menor caixa dos Correios).
Chave de licença do VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_frenet-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_frenet.ocmod.zip. Instale apenas 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_frenet-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ê também 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 Frenet e clique em Install (o botão verde +).
3. Clique em Edit (o botão de lápis) para abrir a página de configurações.
4. Informe sua chave de licença do 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 API e informe o CEP de origem. Se a moeda padrão não for o BRL, informe a taxa de câmbio para o BRL. Opcionalmente, adicione preços fixos e um custo de contingência. Ative Enable Frenet e clique em Save.
OpenCart 4
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_frenet.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 Frenet, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).
4. Informe a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões.
Depois da instalação, o método fica desativado até que você ative Enable Frenet e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações do Frenet que você manteve serão usadas de novo.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Frenet > Edit. As seções ficam listadas à esquerda. Um único botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também limpa as cotações do Frenet em cache. Os campos de preço aceitam tanto o ponto quanto a vírgula como separador decimal. Se um valor estiver errado, nada é salvo e a página mostra o motivo, por exemplo Enter a valid method title (64 characters max, without < > ; = # { })., "…" must be a number. ou "…" must not be negative. Um BRL exchange rate igual ou menor que 0 e um Minimum weight (kg) maior que o Maximum weight (kg) também são recusados. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
No topo da página, e de novo após cada salvamento, a extensão mostra avisos: sem token de API (somente preços fixos são usados, ou o método nunca aparece se também não houver preços fixos), sem CEP de origem, um CEP de origem sem 8 dígitos, ou uma moeda padrão diferente de BRL sem taxa de câmbio. Ela também avisa quando a loja não tem uma classe de peso com a unidade kg nem uma classe de comprimento com a unidade cm. Pesos e dimensões dos produtos são então convertidos pelo nome da unidade da sua classe, e unidades desconhecidas são lidas como kg ou cm. Verifique System > Localisation > Weight Classes e Length Classes.
Geral
As configurações se aplicam a todas as zonas geográficas. Você pode limitar o método a uma zona geográfica em Conditions, ou usar Ignore shipping zones. O preço sempre vem desta extensão.
Enable Frenet: mostra ou oculta o Frenet na finalização de compra. Padrão: desativado.
Method title: o nome do método de envio mostrado ao cliente no carrinho e na finalização de compra. Padrão: Frenet. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.
Sort order: a posição do Frenet entre os métodos de envio na finalização de compra. Um número inteiro.
Cotações do Frenet em tempo real
O Frenet compara as transportadoras ativadas na sua conta do Frenet (Correios, Jadlog, Loggi e outras) e retorna os preços delas para o carrinho. As cotações em tempo real são solicitadas somente para endereços no Brasil com um CEP completo de 8 dígitos. A seção tem um link para o painel do Frenet.
API token: seu token de API do Frenet, obtido no painel do Frenet. Deixe o campo vazio para usar somente preços fixos. Após salvar, o campo fica vazio e exibe A token is saved — leave empty to keep it. Digite um valor novo apenas para alterá-lo. Para excluir o token salvo, marque Remove the saved token e salve.
Origin CEP: o CEP de onde os pacotes são enviados, por exemplo 01001-000. O OpenCart não tem CEP de loja, por isso as cotações em tempo real precisam deste campo. Um CEP sem 8 dígitos é salvo como digitado, e a página mostra Frenet: the origin CEP must have 8 digits.
Service to offer: Cheapest service (padrão) ou Fastest service. O Frenet retorna vários serviços, e o método exibe um único preço. A transportadora, o serviço e o prazo de entrega escolhidos são salvos com o pedido.
BRL exchange rate: o Frenet cota em reais. Se a moeda padrão não for o BRL, informe quanto vale 1 BRL na sua moeda padrão, por exemplo 0.16. A cotação e o valor declarado do pedido são convertidos com essa taxa. Sem ela, as cotações em tempo real não são usadas. Quando a moeda padrão é o BRL, o campo indica que os preços do Frenet são usados como estão.
Preços fixos
Usados quando não há token de API, para países que o Frenet não atende e sempre que o Frenet não retorna preço (API fora do ar, CEP não atendido).
Price per country: uma tabela com as colunas Country, Price, XS, S, M, L e XL, com preços na moeda padrão, sem impostos. Clique em Add country para adicionar uma linha. As colunas de tamanho dependem do peso do carrinho: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg, XL acima de 5 kg. Price é usado quando a coluna de tamanho está vazia. Um Price de 0 significa frete grátis para esse país. Use * Default (all other countries) para todos os países sem linha própria. Linhas sem nenhum preço são removidas ao salvar.
Fallback cost: usado quando nem o Frenet nem a tabela fornecem um preço. Deixe vazio para ocultar o método.
Fixed price applies: Per order (padrão) cobra o preço uma vez. Per item (price × quantity) o multiplica pela quantidade de itens. Isso vale apenas para os preços fixos e para o custo de contingência. As cotações do Frenet já cobrem o carrinho inteiro.
Condições
Minimum weight (kg): oculta o método abaixo deste peso de carrinho. 0 significa sem limite.
Maximum weight (kg): oculta o método acima deste peso de carrinho. Padrão: 30 (também usado quando o campo está vazio). 0 significa sem limite. Não pode ser menor que o Minimum weight (kg).
Minimum order amount: exibe o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes de impostos) é pelo menos este valor. Deixe vazio para exibi-lo sempre.
Free shipping from: o subtotal (após o cupom, antes de impostos) a partir do qual o frete é grátis. Deixe vazio para nunca oferecer frete grátis.
Tax class: a classe de imposto somada ao custo do envio, ou No tax. Os preços do Frenet são os preços finais da transportadora. Escolha No tax se o OpenCart não deve aplicar imposto sobre eles.
Geo zone: ofereça o Frenet somente para endereços desta zona geográfica. All zones significa sem limite. Não é usada com Ignore shipping zones. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Disponibilidade sem zonas de envio
Normalmente o método é oferecido na zona geográfica selecionada em Conditions (em todas as zonas, se nenhuma for selecionada).
Ignore shipping zones: ofereça o Frenet para os países abaixo, independentemente da zona geográfica que corresponder. A Geo zone em Conditions então não é verificada.
Countries: os países de destino para esse modo, escolhidos entre os países ativos da sua loja. Deixe vazio para usar todos os países para os quais você envia. Usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: registra cada solicitação e resposta de cotação em storage/logs/vfd_frn_debug.log.php (no OpenCart 4 system/storage/logs/vfd_frn_debug.log.php). O arquivo não pode ser lido pela web. Erros da API são sempre registrados. O token nunca é registrado e o CEP do cliente é abreviado. Desative quando terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_frn_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para limpá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídas todas as configurações do Frenet e o log. Quando desativado, tudo é mantido para uma reinstalação. As cotações em cache são sempre removidas. Os serviços do Frenet 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 API 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 API 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 Frenet. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o Frenet não é oferecido. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no valor do pedido. A extensão então verifica a lista de países (se Ignore shipping zones estiver ativado), o peso do carrinho e o valor mínimo do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes de impostos. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada ao Frenet.
Para um endereço no Brasil com CEP completo de 8 dígitos, e quando o token de API e o CEP de origem estão definidos, a extensão envia ao Frenet os CEPs de origem e de destino, cada item do carrinho (peso em kg, dimensões em cm, quantidade, o Model do produto e suas categorias), o valor do pedido em BRL e o código do cupom do carrinho. Nenhuma solicitação é feita enquanto o CEP estiver incompleto. O Frenet retorna os serviços das suas transportadoras ativadas. Serviços com erro ou sem preço são ignorados. A extensão escolhe o serviço mais barato ou o mais rápido e converte o preço para a moeda padrão. O preço é arredondado conforme as casas decimais da moeda padrão e exibido ao cliente na moeda dele, com o imposto da Tax class selecionada.
Cada resposta fica em cache por 1 hora para o mesmo carrinho e o mesmo endereço. Uma solicitação com falha, ou um CEP que nenhuma transportadora ativada atende, fica registrado por 10 minutos. O tempo limite da API é de 10 segundos. Nesses casos o cliente não vê erro algum: o preço fixo ou o custo de contingência é usado, ou o método fica oculto se não houver nenhum. O motivo é gravado no log. Para endereços fora do Brasil, somente preços fixos são usados.
No OpenCart 4, o cliente clica em Choose no bloco de métodos de envio da página de finalização de compra e escolhe o Frenet na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3.
A extensão calcula somente as tarifas. Ela não cria envios, não imprime etiquetas e não rastreia pacotes. Ela exibe um serviço do Frenet por carrinho, e não vários, e não tem pontos de retirada nem armários. O Frenet cota somente dentro do Brasil; use os preços fixos para outros países.
Pedidos
Quando um pedido é feito com o Frenet, a extensão salva como o preço do envio foi calculado: exatamente a opção que o cliente viu na etapa de envio, sem uma nova solicitação ao Frenet. A página do pedido em Sales > Orders então mostra um bloco Frenet com estas linhas:
Carrier: a transportadora e o serviço do Frenet, por exemplo um serviço dos Correios ou da Jadlog. Exibido para cotações em tempo real.
Delivery time: o prazo de entrega em dias úteis retornado pelo Frenet. Exibido para cotações em tempo real.
Price source: Live Frenet quote, Fixed price (price per country), Fallback cost ou Free shipping.
No OpenCart 4, o bloco é exibido acima de History. O OpenCart 4 atualiza o mesmo pedido quando o cliente o confirma novamente: os dados salvos do Frenet também são atualizados e, se o cliente tiver escolhido outro método de envio, os dados do Frenet do pedido são removidos.
O bloco também é exibido quando a extensão está desativada. Esses dados são mantidos ao desinstalar a extensão, inclusive com Remove data on uninstall.
Chave de licença
A extensão funciona com uma chave de licença do VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Frenet é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Frenet > Edit, acima das configurações. Informe 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 estão a linha Product: opencart-shipping-frenet 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 de modificação da 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 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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o Frenet não é exibido aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador que esteja conectado ao admin no mesmo navegador ainda vê o método na loja, marcado com (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 no 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 cron job. Ao desinstalar a extensão, a chave de licença e o status da licença são sempre removidos.
Solução de problemas
O Frenet não aparece na finalização de compra: verifique se a licença está ativa e se Enable Frenet está ligado. Verifique a Geo zone, ou Ignore shipping zones e Countries, os limites de peso e o Minimum order amount. Verifique os avisos no topo da página da extensão. Motivos típicos: o cliente ainda não informou um CEP completo de 8 dígitos e não há preços fixos, ou o Frenet não retornou nenhum serviço para a rota e não há preço fixo. Verifique se os produtos têm Requires Shipping definido como Yes.
As cotações em tempo real não aparecem: ative o Debug log, recarregue a finalização de compra e veja o campo Log na página da extensão. Ele mostra o motivo: sem CEP de origem, sem taxa de câmbio para o BRL, CEP do cliente incompleto, um limite de peso ou de valor, ou as mensagens dos serviços ignorados.
O log informa que o token de API foi rejeitado (HTTP 401 ou 403): copie o token novamente do painel do Frenet e cole-o em API token.
O log informa que o Frenet não retornou serviços: ative pelo menos uma transportadora no painel do Frenet.
Minha loja vende em euros ou dólares: o Frenet responde em BRL. Informe a BRL exchange rate (quanto vale 1 BRL na sua moeda padrão).
Há imposto cobrado sobre o preço do Frenet: os preços do Frenet são os preços finais da transportadora. Defina Tax class como No tax.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as cotações do Frenet em cache.
A página diz "Warning: You do not have permission to modify VibeFox Frenet!": o grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_frenet (OpenCart 3) ou extension/vfd_frenet/shipping/vfd_frenet (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço de cotação do Frenet pode ser substituído pela configuração vfd_frn_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 Frenet. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Frenet, Sort order, Tax class e Geo zone. As cotações em cache são sempre removidas. O evento OpenCart da extensão também é removido (no OpenCart 4, também os eventos que salvam os dados do Frenet de novos pedidos), por isso o bloco do Frenet não é mais exibido na página do pedido. Os dados do Frenet salvos com os pedidos são mantidos e exibidos novamente após uma reinstalação. Se Remove data on uninstall estiver ativado, as configurações do Frenet e o log de depuração também são excluídos. Se estiver desativado, as demais configurações são mantidas e usadas novamente ao reinstalar a extensão. Os pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Frenet na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com lixeira) para remover o pacote enviado.
O Frenet é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pelo Frenet.