VibeFox GLS ParcelShop for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e versões posteriores (testado na versão 4.1.0.3), com o tema padrão e o seu checkout em uma única página.
PHP: 8.0 ou superior.
GLS: a extensão não usa nem precisa de conta GLS ou chave de API. O mapa de ParcelShops é público. Você precisa de um contrato com a GLS para enviar as encomendas aos ParcelShops escolhidos.
Política de segurança de conteúdo: se a sua loja envia uma política de segurança de conteúdo (Content Security Policy), permita map.gls-croatia.com, de onde é carregado o script do mapa da GLS.
Chave de licença 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_gls_parcelshop-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_gls_parcelshop.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, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_gls_parcelshop-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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox GLS ParcelShop 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. Informe 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 License key).
5. Defina os seus preços: pelo menos uma linha em Country prices (por exemplo * Default) ou um Fallback cost (veja Configuração). Ative Enable/Disable e clique em Save.
OpenCart 4
1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_gls_parcelshop.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox GLS ParcelShop, 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.
Depois da instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações que você manteve voltam a ser usadas.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > Edit. As seções ficam listadas à esquerda. Um botão Save na parte de baixo salva a página inteira sem recarregá-la. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Avisos no topo da página, e novamente após cada salvamento, apontam problemas de configuração: nenhum preço definido, alguns ou todos os Countries (ignore zones mode) selecionados não estão cobertos pelo mapa da GLS, ou a unidade de peso da loja não é conhecida pela extensão e não existe uma classe de peso em kg (adicione uma em System > Localisation > Weight Classes). Um número inválido ou negativo é recusado com uma mensagem que indica o campo, por exemplo Fallback cost: "abc" is not a valid number of 0 or more - the previous value was kept. Os demais campos continuam sendo salvos. Um Name, uma ordem de classificação, uma classe de imposto ou uma zona geográfica inválidos são recusados da mesma forma.
Geral
A seção lista os países cobertos pelo mapa da GLS: Áustria, Bélgica, Bulgária, Croácia, República Tcheca, Dinamarca, Finlândia, França, Alemanha, Grécia, Hungria, Itália, Luxemburgo, Países Baixos, Polônia, Portugal, Romênia, Sérvia, Eslováquia, Eslovênia e Espanha. O método não é oferecido para outros países de destino.
Enable/Disable: mostra ou oculta o GLS ParcelShop no checkout. Padrão: desligado.
Name: o nome do método de envio exibido ao cliente. Padrão: GLS ParcelShop. Obrigatório, no máximo 64 caracteres, sem os caracteres < > ; = # { }.
Tax status: None (shipping is not taxed), ou a classe de imposto a aplicar quando o envio é tributável.
Sort order: a posição entre os métodos de envio no checkout. Um número inteiro.
Preços
Os preços são informados na moeda padrão da sua loja, sem impostos. As casas decimais podem usar vírgula ou ponto (4,99 ou 4.99). O preço é mostrado ao cliente na moeda dele.
Calculation type: como o preço é aplicado.
Country prices: uma tabela com uma linha por país de destino. Clique em Add country para adicionar uma linha. Cada linha tem um Country, um Price e cinco 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. É usada a coluna do peso do carrinho. Uma coluna de peso deixada em 0 usa a coluna Price. A linha * Default é usada para os países que não têm linha própria. Uma linha com todos os preços em 0 significa entrega grátis, então escolha o país e preencha os preços antes de salvar. Se algum valor da tabela não for um número válido de 0 ou mais, a tabela inteira não é salva e a mensagem lista os valores incorretos.
Fallback cost: o preço usado quando a tabela não tem linha para o país de destino nem uma linha * Default. Deixe vazio para ocultar o método para esses países.
Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual a entrega pelo GLS ParcelShop é grátis. Deixe vazio se a entrega nunca for grátis.
Disponibilidade
Minimum weight (kg): oculta o método quando o carrinho pesa menos. O peso é convertido a partir das classes de peso dos produtos. Vazio ou 0 significa sem limite.
Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 20. Os ParcelShops da GLS costumam aceitar pacotes de até 20 kg, então confira o seu contrato com a GLS. Vazio ou 0 significa sem limite. Se o mínimo for maior que o máximo, os dois pesos são recusados com uma mensagem e os valores anteriores são mantidos.
Minimum cart subtotal: oferece o método somente quando o subtotal do carrinho (após descontos, sem impostos) atinge este valor. Deixe vazio para não ter mínimo.
Geo zone: oferece o método somente para endereços desta zona geográfica. All zones significa sem limite. Não é usada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore shipping zones: quando ativado, o método é oferecido para os países selecionados abaixo (todos os países do mapa da GLS se a lista estiver vazia), independentemente da zona geográfica. Quando desativado, é oferecido somente na zona geográfica acima. Padrão: desligado.
Countries (ignore zones mode): os países de destino para esse modo. Deixe vazio para usar todos os países do mapa da GLS. Países não cobertos pelo mapa da GLS são ignorados. Este campo só é usado quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas e as escolhas de ParcelShop em storage/logs/vfd_glps_debug.log.php (no OpenCart 4, system/storage/logs/vfd_glps_debug.log.php). O arquivo não pode ser lido pela web. Os erros são sempre registrados. Nenhum dado pessoal do cliente é registrado. Desative o log quando terminar. Quando o arquivo atinge 5 MB, ele é movido para vfd_glps_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar a extensão apaga as configurações e o log. Quando desativado, tudo é mantido para uma reinstalação. O ParcelShop salvo nos pedidos é sempre mantido.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações, por exemplo em outra loja. Valores inválidos são informados e não são importados.
Como funciona no checkout
Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço do GLS ParcelShop. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, o método não é oferecido. Somente os produtos com Requires Shipping definido como Yes contam: os outros produtos não somam peso e não entram no subtotal do carrinho. O subtotal é o preço desses produtos após o desconto do cupom, sem impostos. Em seguida, a extensão verifica as condições: país de entrega coberto pelo mapa da GLS (e selecionado em Countries (ignore zones mode) quando esse modo está ativo), peso do carrinho e subtotal mínimo do carrinho. Se o subtotal do carrinho atingir Free shipping from, a entrega é grátis. Caso contrário, o preço vem da linha do país (ou da linha * Default) e da coluna de peso, ou de Fallback cost. Se nenhum preço for encontrado, o método é ocultado. O preço é arredondado para as casas decimais da moeda padrão e exibido com o imposto da Tax status selecionada.
Quando o cliente seleciona o GLS ParcelShop, aparece uma caixa GLS ParcelShop com um botão Select GLS ParcelShop abaixo do método. Ele abre o mapa oficial do GLS ParcelShop para o país de entrega. Um ParcelShop de outro país é recusado de imediato. Depois de escolher um ParcelShop, seu nome e endereço são exibidos e o botão muda para Change ParcelShop. A escolha é mantida na sessão do cliente, então continua disponível quando a etapa de envio é recarregada. Se o endereço de entrega mudar para outro país, o cliente precisa escolher um ParcelShop novamente.
Quando o cliente clica em Continue na etapa do método de entrega, a extensão verifica se um ParcelShop foi escolhido e se ele está no país de entrega. Caso contrário, o cliente vê Please select a GLS ParcelShop. ou The selected GLS ParcelShop is not in your shipping country. Please choose a ParcelShop again. e permanece nessa etapa. Se o ParcelShop não puder ser salvo, o cliente vê The ParcelShop could not be saved. Please try again. Se o script do mapa da GLS não puder ser carregado, o cliente vê The GLS ParcelShop map could not be loaded. Please reload the page or choose another shipping method.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de checkout e escolhe o GLS ParcelShop na janela Shipping method options. A caixa GLS ParcelShop com o botão Select GLS ParcelShop aparece nessa janela, abaixo do método, e o mapa da GLS abre sobre a janela. O botão Continue da janela não avança sem um ParcelShop válido, com as mesmas mensagens. O OpenCart 4 mantém um único pedido para o checkout e o atualiza sempre que o cliente confirma novamente, e o ParcelShop do pedido é atualizado junto com ele.
O mapa da GLS roda no navegador do cliente. Na página de checkout, a extensão carrega o script do mapa da GLS a partir de map.gls-croatia.com, e o mapa carrega da GLS os dados dos ParcelShops e os blocos de imagem do mapa. A GLS recebe os dados habituais da requisição do visitante (endereço IP, navegador). Nada é enviado do seu servidor para a GLS. Um erro na extensão nunca interrompe o checkout dos outros métodos de envio; ele é gravado no log.
A extensão não obtém tarifas da GLS em tempo real, não cria envios GLS, não imprime etiquetas e não rastreia encomendas. Ela não tem uma lista de ParcelShops no seu servidor, então não consegue verificar o ID do ParcelShop junto à GLS. Informe o ID do ParcelShop do pedido à GLS da forma habitual (MyGLS, seu software da GLS ou outra extensão).
Pontos de retirada
Quando o pedido é feito, o ParcelShop escolhido no checkout é salvo com o pedido: o seu ID, o nome com o endereço e o país. Depois que o pedido é concluído, a escolha é apagada, para que o próximo carrinho comece sem ParcelShop.
Shipping method name: o ParcelShop é adicionado ao nome do método de envio do pedido, por exemplo GLS ParcelShop: name, address (primeiro o nome do método, depois o ParcelShop) (o OpenCart 3 guarda no máximo 128 caracteres desse nome, o OpenCart 4 até 255). Assim, o ParcelShop aparece no e-mail de confirmação do pedido enviado ao cliente, na página do pedido no Order History do cliente e em Sales > Orders. O OpenCart não mostra o método de envio na página de sucesso do pedido.
Admin order page: em Sales > Orders, um painel GLS ParcelShop mostra o nome e o endereço do ParcelShop, com o ParcelShop ID e o país. Se um pedido do GLS ParcelShop não tiver ParcelShop, o painel mostra No ParcelShop was selected for this order. O painel apenas mostra o ParcelShop; ele não pode ser alterado ali.
E-mail ao lojista: o e-mail de aviso de novo pedido enviado à loja inclui o ParcelShop com o seu ParcelShop ID no bloco de comentários.
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 GLS ParcelShop é o primeiro bloco em Extensions > Extensions > Shipping > VibeFox GLS ParcelShop > Edit, 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 estão a linha Product: opencart-shipping-gls-parcelshop 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 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 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 na 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 GLS ParcelShop não é mostrado aos clientes no checkout e nenhuma tarifa é calculada. Um usuário administrador 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 de abrir uma vez a página Edit, 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 ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser informada e, depois, uma vez por semana. Não é preciso 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 GLS ParcelShop não aparece no checkout: verifique se a licença está ativa e se Enable/Disable está ativado. Confira Geo zone, ou Ignore shipping zones e Countries (ignore zones mode). Verifique se o país de destino é um dos países do mapa da GLS e se tem preço (uma linha de país, a linha * Default ou Fallback cost). Confira os limites de peso e o Minimum cart subtotal, e se os produtos têm Requires Shipping definido como Yes. Ative o Debug log e veja o campo Log para descobrir o motivo.
O mapa não abre: o cliente vê "The GLS ParcelShop map could not be loaded..." quando o script da GLS é bloqueado, por exemplo por um bloqueador de anúncios ou de privacidade, por uma política de segurança de conteúdo ou por uma queda da GLS. Permita map.gls-croatia.com na sua política de segurança de conteúdo.
A caixa do ParcelShop não aparece abaixo do método: a extensão foi testada com o tema padrão do OpenCart e o seu checkout. Um tema ou uma extensão de checkout que substitua a etapa do método de envio pode não exibir a caixa.
A entrega é grátis para um país por engano: confira a linha desse país em Country prices. Uma linha em que o Price e todas as colunas de peso são 0 significa entrega grátis.
A tabela ou um campo não foi salvo: um valor não é um número válido de 0 ou mais. A mensagem no topo da página indica o valor. Use dígitos com vírgula ou ponto como separador decimal.
Um pedido mostra No ParcelShop was selected for this order: o pedido foi feito sem um ParcelShop do país de entrega. O motivo está gravado no log. Peça o ParcelShop ao cliente e informe-o à GLS manualmente.
A página diz "Warning: You do not have permission to modify VibeFox GLS ParcelShop!": o seu grupo de usuários administradores só pode visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_gls_parcelshop (OpenCart 3) ou extension/vfd_gls_parcelshop/shipping/vfd_gls_parcelshop (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço do script do mapa da GLS pode ser substituído com a configuração vfd_glps_widget_url; ela não tem campo na página de configurações.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox GLS ParcelShop. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable/Disable, Sort order, Tax status e Geo zone. A extensão sempre remove os seus eventos. 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 voltam a ser usados quando você reinstalar a extensão. Um ParcelShop escolhido em um carrinho aberto permanece na sessão do cliente até expirar. O ParcelShop salvo nos pedidos é sempre mantido, e 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, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox GLS ParcelShop na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
GLS é uma marca registrada de seu titular. Esta extensão não é afiliada nem endossada pela GLS.