VibeFox Frenet for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta na Frenet (somente para cotações ao vivo): crie uma conta gratuita no painel da 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 conta na 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 VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse 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 Frenet na lista de módulos e clique em Configure.
3. Cole 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 API e informe o CEP de origem. Se a moeda padrão da sua loja não for o BRL, informe a taxa de câmbio do BRL. Opcionalmente, adicione preços fixos e um custo de reserva. Clique em Save.
Na instalação, o módulo cria a transportadora Frenet com o texto de prazo de entrega Delivery by the carriers of your Frenet account. A transportadora é atribuída 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 ficam na página do módulo: Modules > Module Manager > VibeFox Frenet > Configure. Elas valem para todas as zonas da transportadora. Cada seção tem o seu próprio botão Save, que salva a página inteira. Cada salvamento também limpa as cotações da Frenet em cache. Os campos de preço aceitam tanto o ponto quanto a vírgula como separador decimal; um valor que não é número é recusado com a mensagem "…" must be a number. Também são recusados valores e pesos negativos, uma BRL exchange rate igual a 0 ou menor, e um Minimum weight maior que o Maximum weight. Quando há erro, nada é salvo.
No topo da página, o módulo exibe avisos: nenhum token de API (somente preços fixos são usados, ou a transportadora nunca é exibida se também não houver preços fixos), nenhum CEP de origem com 8 dígitos, ou uma moeda padrão diferente do BRL sem taxa de câmbio. Também avisa quando a unidade de peso ou de dimensão da sua loja não é reconhecida pelo módulo; essa unidade é tratada como kg ou cm. Defina uma unidade padrão (kg, g, lb ou oz; cm, mm, m ou in) em International > Localization (Local units).
Geral
Enable Frenet: liga ou desliga a transportadora. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Method title: o nome da transportadora exibido no carrinho e na finalização da compra. Default: Frenet. Obrigatório, no máximo 64 caracteres.
Cotações ao vivo da Frenet
A Frenet compara as transportadoras ativadas na sua conta da Frenet e retorna os preços delas para o carrinho. As cotações ao vivo são solicitadas apenas para endereços no Brasil com CEP completo de 8 dígitos. A seção tem um link para o painel da Frenet.
API token: o seu token de API da Frenet, obtido no painel da Frenet. Deixe vazio para usar somente preços fixos. Depois de salvar, o campo fica vazio e mostra A token is saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. Para apagar o token salvo, marque Remove the saved token e salve.
Origin CEP: o CEP de onde os pacotes são enviados, por exemplo 00000-000. Deixe vazio para usar o CEP da loja definido em Shop Parameters > Contact > Stores, se o endereço da loja estiver no Brasil. Um CEP com menos de 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. A Frenet retorna vários serviços, e a transportadora mostra um único preço.
BRL exchange rate: a Frenet cota em reais. Se a moeda padrão da sua loja não for o BRL, informe quanto vale 1 BRL na 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 ao vivo não são usadas. Quando a moeda padrão é o BRL, o campo mostra Not needed (shop currency is BRL).
Preços fixos
Usados quando não há token de API, para países que a Frenet não atende e sempre que a Frenet não retorna um 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 e no ícone de lixeira para remover uma. 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. O Price é usado quando a coluna de tamanho está vazia. Um Price de 0 significa frete grátis para esse país. Use * Default para todos os outros países. Linhas sem nenhum preço são removidas ao salvar.
Fallback cost: usado quando nem a Frenet nem a tabela fornecem um preço. Deixe vazio para ocultar a transportadora.
Fixed price applies: Per order cobra o preço uma vez. Per item (price × quantity) multiplica pelo número de itens. Isso vale apenas para os preços fixos e para o custo de reserva. As cotações da Frenet já cobrem o carrinho inteiro.
Condições
Minimum weight: oculta a transportadora abaixo deste peso do carrinho, em kg. 0 significa sem limite.
Maximum weight: oculta a transportadora acima deste peso do carrinho, em kg. Default: 30 (usado também quando o campo está vazio). 0 significa sem limite. Não pode ser menor que o Minimum weight.
Minimum order amount: exibe a transportadora somente quando o subtotal do carrinho (após descontos, antes dos impostos) for pelo menos este valor. Deixe vazio para exibi-la sempre.
Free shipping from: o subtotal do carrinho (após descontos, antes dos impostos) a partir do qual o frete é grátis. Deixe vazio para nunca oferecer frete grátis.
Tax: a regra de imposto da transportadora, ou No tax. Os preços da Frenet são preços finais da transportadora. Escolha No tax se o PrestaShop não deve acrescentar imposto a eles.
Os pesos e as dimensões dos produtos são convertidos das unidades da sua loja para kg e cm.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas zonas às quais está atribuída em Shipping > Carriers.
Ignore shipping zones: oferece a Frenet para os países abaixo, independentemente da zona correspondente. Ao salvar, a transportadora é adicionada a todas as zonas, e também às zonas que você criar depois. Quando você desliga a opção de novo, a transportadora volta a ter as zonas que tinha antes.
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 logs/vfd_frn_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados. O token nunca é registrado e o CEP do cliente é encurtado. Desative quando terminar.
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 o módulo são apagadas todas as configurações da Frenet, a transportadora e o log. Quando desativado, tudo é mantido para uma reinstalação. As cotações em cache são sempre removidas. Os serviços da Frenet salvos com os pedidos fazem parte do histórico de pedidos e são mantidos.
Como funciona na finalização da compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da Frenet. Só contam os produtos físicos: produtos virtuais não somam peso e não entram no valor do pedido. Antes de o cliente informar um endereço, o módulo usa o país que a loja estima para o visitante. O módulo verifica primeiro a lista de países (quando Ignore shipping zones está ativado), o peso do carrinho e o valor mínimo do pedido. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada à Frenet.
Para um endereço no Brasil com CEP completo de 8 dígitos, o módulo envia à Frenet os CEPs de origem e de destino, cada item do carrinho (peso em kg, dimensões em cm, quantidade, referência do produto e categorias), o valor do pedido em BRL e o primeiro código de cupom do carrinho. Nenhuma requisição é feita enquanto o CEP estiver incompleto. A Frenet retorna os serviços das suas transportadoras ativadas. Serviços com erro ou sem preço são ignorados. O módulo escolhe o serviço mais barato ou o mais rápido e converte o preço para a moeda padrão da loja. Depois, o preço é exibido na moeda do carrinho do cliente.
Cada resposta fica em cache por 1 hora para o mesmo carrinho e o mesmo endereço. Uma requisiçã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: é usado o preço fixo ou o custo de reserva, ou a transportadora é ocultada se não houver nenhum. O motivo é gravado no log. Para endereços fora do Brasil, são usados somente preços fixos.
Se você editar a transportadora em Shipping > Carriers depois que ela já tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo acompanha a nova versão automaticamente.
O módulo calcula apenas as taxas. Ele não cria envios, não imprime etiquetas nem rastreia encomendas. Mostra um serviço da Frenet por carrinho, e não vários, e não tem pontos de retirada nem armários. A Frenet cota apenas dentro do Brasil; use os preços fixos para os demais países.
Pedidos
Quando um pedido é feito com a transportadora Frenet, o módulo salva como o preço do frete foi calculado. A página do pedido no back office exibe então um bloco Frenet com estas linhas:
Carrier: a transportadora Frenet e o serviço, por exemplo um serviço dos Correios ou da Jadlog. Exibido para cotações ao vivo.
Delivery time: o prazo de entrega em dias úteis retornado pela Frenet. Exibido para cotações ao vivo.
Price source: Live Frenet quote, Fixed price (price per country), Fallback cost ou Free shipping.
Esses dados são mantidos quando o módulo é desinstalado, inclusive com Remove data on uninstall.
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 Frenet é o primeiro bloco em Modules > Module Manager > VibeFox Frenet > 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-shipping-frenet e o link Manage licenses and domains in your account, que abre a sua conta em 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 de 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, também em configurações multiloja. 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, a transportadora Frenet não é exibida aos clientes na finalização da compra e nenhuma tarifa é calculada. A loja 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 testá-lo na finalização da compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 informada, 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
A Frenet não aparece na finalização da compra: verifique se a licença está ativa e se Enable Frenet está ligado. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou se Ignore shipping zones está ligado e o país é permitido. Confira os avisos no topo da página do módulo, os limites de peso e o Minimum order amount. Motivos comuns: o cliente ainda não informou um CEP completo de 8 dígitos e não há preços fixos, ou a Frenet não retornou nenhum serviço para a rota e não há preço fixo. Os produtos também podem estar limitados a determinadas transportadoras na página do produto.
As cotações ao vivo não aparecem: ative o Debug log, recarregue a finalização da compra e veja o campo Log na página do módulo. Ele mostra o motivo: nenhum CEP de origem, nenhuma taxa de câmbio do 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 recusado (HTTP 401 ou 403): copie o token novamente do painel da Frenet e cole em API token.
O log informa que a Frenet não retornou serviços: ative pelo menos uma transportadora no painel da Frenet.
Minha loja vende em euros ou dólares: a Frenet responde em BRL. Informe a BRL exchange rate (quanto vale 1 BRL na moeda padrão da loja).
O imposto é cobrado além do preço da Frenet: os preços da Frenet são preços finais da transportadora. Defina Tax como No tax.
As tarifas parecem desatualizadas depois de uma alteração: clique em Save na página do módulo. Isso limpa as cotações da Frenet em cache.
A página informa que a transportadora Frenet não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para recriá-la. Até lá, ao salvar aparece The settings were saved, but the carrier could not be updated.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Frenet e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. As cotações em cache são sempre removidas. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico) e as configurações e o log são removidos. Se estiver desativado, a transportadora apenas é desativada e todas as configurações são mantidas. Reinstalar o módulo ou usar Reset devolve à transportadora salva o status que ela tinha antes: uma transportadora que você havia desligado continua desligada. Os pedidos existentes mantêm a transportadora Frenet e o bloco Frenet na página do pedido.
Frenet é marca de seu respectivo proprietário. Este módulo não é afiliado à Frenet nem endossado por ela.