VibeFox LP Express for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3), com o tema padrão e a finalização de compra padrão do OpenCart.

PHP: 8.0 ou superior.

LP Express: não é necessária uma conta de API. A LP Express não tem uma API pública de preços, e a extensão não usa a API da Unisend, por isso você digita os seus próprios preços (contratuais). Crie as encomendas na sua conta Unisend («Mano siuntos»).

Lista de terminais de encomendas: a extensão usa a lista aberta de terminais da LP Express (https://www.lpexpress.lt/index.php?cl=terminals&fnc=getTerminals). Não é necessária nenhuma chave. Se essa lista online estiver indisponível, a extensão usa a última cópia baixada, se houver, ou então a sua própria lista. Prepare-se para digitar a sua própria lista (veja Configuração).

Lituânia: o país precisa estar ativado em System > Localisation > Countries.

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 README.txt, o pacote do OpenCart 3 vfd_lp_express-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_lp_express.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_lp_express-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 do pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox LP Express 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 no campo License key do bloco de licença no topo da página Edit e clique em Activate (veja Chave de licença).

5. Preencha a tabela de preços (pelo menos uma linha; a primeira linha nova é a Lituânia) ou um custo de contingência. Confira a linha de status sobre os terminais de encomendas no topo da página e adicione a sua própria lista de terminais se a lista online não estiver disponível. Ative Enable/Disable e clique em Save.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_lp_express.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 LP Express, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Digite 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 campos são iguais nas duas versões.

Na instalação, a extensão cria duas pequenas tabelas (os terminais escolhidos e a lista de terminais em cache) e registra os seus eventos do OpenCart para a finalização de compra e para a página do pedido. O método fica desligado 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 serão usadas de novo.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox LP Express > Edit. As seções aparecem à esquerda. Um botão Save no final salva a página inteira sem recarregá-la. Cada salvamento também recarrega a lista de terminais. Somente usuários administradores com a permissão de modificação para esta extensão podem salvar as configurações.

No topo da página, avisos mostram problemas e o status dos terminais. Um alerta aparece quando nenhum preço está definido ou nenhum terminal de encomendas está disponível, pois nesse caso o método não é exibido na finalização de compra, e quando a loja não tem uma classe de peso com a unidade kg, pois então os pesos dos produtos são lidos pelo nome da sua unidade (kg, g, lb, oz) e qualquer outra unidade é tratada como kg. Uma linha informativa mostra quantos terminais de encomendas, em quantas cidades, estão disponíveis e de qual fonte: a lista online, uma cópia salva da lista online (com a data) ou a sua própria lista.

Ao salvar, um título de método vazio ou que contenha um dos caracteres < > ; = # { } é recusado com Enter a valid method title., e um título com mais de 64 caracteres também é recusado. Uma ordem de exibição que não seja um número inteiro também é recusada. Nesses casos, nada é salvo. Um valor ou peso que não seja um número (ou seja negativo) é informado, e o valor anterior é mantido. Um Minimum weight (kg) maior que o Maximum weight (kg) (30 kg quando o máximo está vazio) também é informado, porque o método nunca seria exibido; os dois pesos mantêm os valores anteriores. Preços da tabela que não sejam números são informados e deixados em branco. Os demais valores são salvos.

Geral

Enable/Disable: mostra ou oculta a LP Express na finalização de compra (o status desta extensão). Padrão: off.

Method title: o nome do método de envio exibido aos clientes no carrinho e na finalização de compra. Padrão: LP Express parcel terminal. Obrigatório, no máximo 64 caracteres.

Tax class: --- None --- (padrão) significa que os preços abaixo são finais. Com uma classe de imposto, o OpenCart acrescenta o imposto de envio aos preços abaixo.

Sort order: a posição da LP Express entre os métodos de envio na finalização de compra. Um número inteiro.

Preços (na moeda padrão da sua loja, exibida no título da seção; os decimais podem ser escritos como 2.99 ou 2,99)

Price table: uma linha por país de destino. Clique em Add country para adicionar uma linha e no botão de remover para excluir uma. Escolha * Any other country para todo país sem linha própria. Cada linha tem um Base price e colunas de peso: XS até 1 kg, S até 2 kg, M até 3 kg, L até 5 kg e XL acima de 5 kg. O peso é o do carrinho ou, com Per item, o peso de um item. Uma coluna vazia usa o preço base da linha. 0 significa grátis. Uma linha sem nenhum preço não é salva.

Fallback cost: usado quando a tabela de preços não tem linha (ou preço) para o país de destino. Deixe em branco para ocultar o método nesses países.

Calculation: como o preço é calculado.

Free shipping from: o valor do carrinho (produtos que precisam de envio, após descontos, sem impostos) a partir do qual a LP Express é grátis. Ele se aplica antes da tabela de preços, por isso também vale para países sem linha própria. Deixe em branco se não houver frete grátis.

Disponibilidade

Minimum weight (kg): oculta o método quando o carrinho é mais leve. Vazio ou 0 significa sem limite.

Maximum weight (kg): oculta o método quando o carrinho é mais pesado. Os terminais da LP Express aceitam encomendas de até 30 kg. Padrão: 30. 0 significa sem limite. Vazio significa 30 kg, ou sem limite quando Ignore shipping zones está ativado.

Minimum cart total: mostra o método somente a partir deste valor do carrinho (produtos que precisam de envio, após descontos, sem impostos). Deixe em branco para sempre mostrá-lo.

Geo zone: o método é oferecido somente para endereços nesta zona geográfica. All Zones (padrão) significa em todos os lugares. 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.

Ignore shipping zones: oferece a LP Express para os países listados abaixo, qualquer que seja a zona geográfica. Nesse modo, a zona geográfica não é verificada. Quando está desativado, os países são definidos pela zona geográfica. Recomendado. Padrão: off.

Countries (without zones): os países de destino desse modo. Este campo só é usado quando Ignore shipping zones está ativado. Deixe em branco para oferecer o método em todos os países.

Terminais de encomendas

Terminal list: de onde vêm os terminais.

Own terminal list: um terminal por linha no formato ID | Name | City | Address | ZIP, por exemplo 1234 | LP EXPRESS Akropolis | Vilnius | Ozo g. 25 | LT-07150. ID e City são obrigatórios. Linhas que começam com # são ignoradas. Use os IDs de terminal que a sua conta Unisend espera.

Avançado

Debug log: grava os detalhes do cálculo de preços e da lista de terminais em storage/logs/vfd_lpex_debug.log.php (no OpenCart 4, system/storage/logs/vfd_lpex_debug.log.php). O arquivo não pode ser lido pela web. Erros, como uma lista de terminais indisponível ou um pedido sem terminal, são sempre registrados. Nenhum dado do cliente é registrado. Quando o arquivo chega a 5 MB, um novo log é iniciado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Remove data on uninstall: quando ativado, ao desinstalar a extensão são apagadas as configurações, a lista de terminais salva, o log e os terminais de finalizações de compra não concluídas. Quando desativado (padrão), as configurações são mantidas para uma nova instalação. O terminal 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. Os valores são verificados como em um salvamento normal.

Como funciona na finalização de compra

Quando o OpenCart mostra os métodos de envio, ele pede à extensão o preço da LP Express. Se uma Geo zone estiver definida e o endereço estiver fora dela, a LP Express não é oferecida. Com Ignore shipping zones, a zona geográfica não é verificada: a LP Express é oferecida apenas para os países listados (todos os países quando a lista está vazia). Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no valor do carrinho. O valor do carrinho é o preço desses produtos após o desconto do cupom e antes dos impostos. Vales-presente, pontos de fidelidade e crédito da loja não são considerados.

A extensão verifica o peso do carrinho e o valor mínimo do carrinho. Se o frete grátis se aplicar, o preço é 0. Caso contrário, o preço vem da linha do país (ou da linha *): a coluna de peso, senão o preço base, senão o custo de contingência. Se não houver preço, ou nenhum terminal de encomendas estiver disponível, o método fica oculto, para que o cliente nunca veja uma finalização de compra que não possa ser concluída.

Preços e valores estão na moeda padrão da sua loja. O preço é arredondado para as suas casas decimais e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.

A lista online de terminais fica em cache por 24 horas. Um download que falhou é lembrado por 15 minutos, para que a finalização de compra não espere pela lista a cada atualização. O tempo limite do download é de 10 segundos. Somente os terminais ativos da lista são oferecidos. Terminais sem cidade aparecem em Other.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe a LP Express na janela Shipping method options. Os preços são os mesmos do OpenCart 3.

A extensão não solicita preços à LP Express nem à Unisend, não cria envios, não imprime etiquetas, não chama um courier nem rastreia encomendas. Crie as encomendas na sua conta Unisend («Mano siuntos»). A entrega porta a porta por courier não faz parte deste método.

Pontos de retirada

Quando o cliente seleciona a LP Express na etapa de método de entrega, o bloco LP Express parcel terminal aparece abaixo, com duas listas: -- Select city -- e -- Select parcel terminal --. A lista de terminais só é carregada quando a LP Express está selecionada. A cidade do endereço de entrega já vem selecionada quando corresponde a uma cidade da lista. Cada terminal é mostrado com nome, endereço e CEP. A escolha é salva para a finalização de compra imediatamente, então não se perde quando a finalização de compra é atualizada.

Um terminal é obrigatório. Quando o cliente clica em Continue, o servidor verifica o terminal na lista novamente. Sem terminal, a finalização de compra mostra Please select an LP Express parcel terminal. Um ID de terminal forjado ou desatualizado é recusado com The selected LP Express parcel terminal is not available any more. Please select a parcel terminal again. Se nenhum terminal puder ser carregado, o cliente vê The LP Express parcel terminal list is temporarily unavailable. Please try again later or choose another shipping method.

No OpenCart 4, o bloco LP Express parcel terminal com as duas listas aparece na janela Shipping method options, abaixo da opção LP Express, quando o cliente a seleciona. O botão Continue da janela não avança sem um terminal válido, com as mesmas mensagens.

O ID do terminal, o nome e a cidade são salvos com o pedido. O painel LP Express parcel terminal na página do pedido no admin (Sales > Orders, informações do pedido) mostra a cidade, o terminal e o seu Terminal ID. O método de envio do pedido mostra o título do método, dois pontos, a cidade e o terminal (por exemplo LP Express parcel terminal: Kaunas, …), por isso aparece nos detalhes do pedido do cliente, nos e-mails de pedido e na nota fiscal. Se um pedido não tiver terminal, a página do pedido no admin mostra No parcel terminal was chosen for this order. O painel também é mostrado para pedidos feitos enquanto a extensão está desativada. No OpenCart 4 ele é 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, e o terminal do pedido é atualizado junto com ele. Se o cliente mudar esse pedido para outro método de envio, o terminal dele é removido.

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 LP Express é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox LP Express > 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 de novo, Change key para digitar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-shipping-lp-express 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 seguido de uma data. Depois de mudar o endereço da loja, 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um 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. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio LP Express não é mostrado aos clientes na finalização de compra e nenhuma tarifa é 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 vê o login do admin, então sem uma chave ativa o método fica oculto para todos. Depois de 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 de novo automaticamente 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 digitada e, 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

A LP Express não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado. Confira a Geo zone (ou se Ignore shipping zones está ativado e o país é permitido). Abra a página da extensão: um alerta explica se nenhum preço está definido ou se nenhum terminal de encomendas está disponível. Verifique também os limites de peso e o Minimum cart total, e se os produtos têm Requires Shipping definido como Yes. Com Debug log ativado, o campo Log na página da extensão mostra por que o método foi ocultado.

Nenhum terminal de encomendas: a lista online não pôde ser carregada e não há cópia salva nem lista própria. A extensão tenta de novo a cada 15 minutos. Digite a sua própria lista em Own terminal list, ou escolha Only my own list.

A lista de terminais está desatualizada: clique em Save na página da extensão. Isso recarrega a lista de terminais. Com a sua própria lista, atualize as linhas você mesmo.

O cliente não consegue continuar: é preciso escolher um terminal de encomendas. Se o cliente vir a mensagem de que a lista de terminais está temporariamente indisponível, nenhum terminal está disponível no momento. Adicione a sua própria lista.

O seletor de terminais não aparece: o seletor é adicionado à etapa de método de entrega da finalização de compra padrão do OpenCart (no OpenCart 4, na janela Shipping method options) e foi testado com o tema padrão. Um tema muito alterado ou uma extensão de finalização de compra de terceiros pode não exibi-lo.

Em qual moeda estão os preços: na moeda padrão da sua loja. Clientes que pagam em outra moeda veem o preço convertido pela taxa de câmbio do OpenCart.

A página diz "Warning: You do not have permission to modify VibeFox LP Express!": 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_lp_express (OpenCart 3) ou extension/vfd_lp_express/shipping/vfd_lp_express (OpenCart 4) em System > Users > User Groups.

Para desenvolvedores: o endereço da lista de terminais pode ser substituído pela configuração vfd_lpex_feed_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 LP Express. 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 class e Geo zone. Os eventos da extensão são sempre removidos, e a lista de terminais em cache é apagada. Se Remove data on uninstall estiver ativado, também são removidas as configurações, o log, a cópia salva da lista de terminais e os terminais de finalizações de compra não concluídas. Se estiver desativado, as demais configurações e a cópia salva são mantidas e usadas novamente quando você instalar a extensão de novo. O terminal salvo nos pedidos nunca é excluído, e os pedidos existentes mantêm o terminal no método de envio.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox LP Express na lista de extensões instaladas e, depois, em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

LP Express é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela LP Express.