VibeFox Packeta for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Chave de API da Packeta: você a encontra na área de cliente da Packeta (client.packeta.com), em Client support. Ela tem 16 letras e números. O widget precisa dela para abrir na finalização de compra, por isso o método só é exibido aos clientes depois que a chave de API for informada.

Países: a República Tcheca, a Eslováquia, a Hungria ou a Romênia devem estar habilitados como países da sua loja. Eles constam nos dados padrão do OpenCart. A Hungria não tem regiões no OpenCart, por isso o campo de região do endereço fica vazio; isso não tem importância.

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_packeta-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_packeta.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 painel de administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_packeta-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, por isso 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. Localize VibeFox Packeta 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. Informe a sua API key da Packeta e os seus preços: pelo menos uma linha de Country prices (por exemplo * Default) ou um Fallback cost. Ative Enable/Disable e clique em Save. A página mostra se a Packeta aceitou a chave.

OpenCart 4

1. No painel de administração, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_packeta.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 Packeta, 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, a chave de API e os preços 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 desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente depois de desinstalá-la, as configurações da Packeta 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 Packeta > Edit. As seções ficam listadas à esquerda. Um único botão Save na parte inferior 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.

O método só é oferecido para os países da rede própria de pontos de retirada da Packeta: CZ, SK, HU e RO. Acima das configurações, a página mostra o resultado da verificação da chave de API e avisos sobre problemas: nenhuma chave de API, nenhum preço, países selecionados fora da rede da Packeta ou uma unidade de peso da loja que a extensão não reconhece. Os avisos são atualizados após cada salvamento.

Todos os preços e limites aceitam vírgula ou ponto como separador decimal (4,99 ou 4.99). Um número inválido ou negativo é recusado com uma mensagem, o valor anterior daquele campo é mantido e os demais campos são salvos.

Geral

Enable/Disable: ativa ou desativa a Packeta na finalização de compra. Padrão: desativado.

Name: o nome do método de envio exibido ao cliente. Padrão: Packeta pickup point. Obrigatório, no máximo 64 caracteres.

API key: a sua chave de API da Packeta, em client.packeta.com > Client support. Você também pode colar a senha de API de 32 caracteres: somente os seus primeiros 16 caracteres, que são a chave de API, são salvos. A chave de API é pública: ela é enviada ao navegador do cliente para abrir o widget. Ao salvar uma nova chave, ela é verificada no feed de transportadoras da Packeta, e a página mostra Packeta API key verified ou informa que a Packeta a recusou. Se a verificação não puder ser feita, a chave é salva e verificada novamente no próximo salvamento.

Widget language: o idioma do widget de pontos de retirada. Store / visitor language (padrão) segue o idioma da página. Você também pode fixá-lo em tcheco, eslovaco, húngaro, romeno, inglês, alemão, polonês ou ucraniano.

Pickup point types: quais pontos da Packeta o widget oferece.

Tax status: a classe de imposto do OpenCart aplicada ao preço do envio, ou None (no tax on shipping) (padrão).

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

Preços

A Packeta não tem uma API pública de tarifas. Os preços vêm desta tabela e são informados na moeda padrão da sua loja, sem impostos. Os clientes que pagam em outra moeda veem o preço convertido.

Calculation type: Per order (padrão) cobra o preço uma vez. Per item (price x quantity) o multiplica pela quantidade de produtos que precisam de envio.

Country prices: um preço por país de destino e por peso da encomenda. Clique em Add country para adicionar uma linha e no botão × para removê-la. 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 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 nova linha começa como * Default com todos os preços em 0, o que significa frete grátis. Escolha o país e informe os preços antes de salvar, ou remova a linha. Se o mesmo país (ou * Default) estiver em duas linhas, somente a primeira é mantida ao salvar. Se um valor da tabela não for um número igual ou maior que 0, a tabela não é salva e a página lista os valores incorretos.

Fallback cost: usado quando a tabela de países não tem linha para o destino nem linha * Default. Deixe vazio para não oferecer o método ali.

Free shipping from: o subtotal do carrinho (após o cupom, sem impostos) a partir do qual o envio pela Packeta é grátis. Ele é verificado antes da tabela de preços: a partir desse valor, o envio é grátis em todos os países da Packeta onde o método é oferecido, inclusive em um país sem linha de país ou custo de contingência. Deixe vazio para nunca oferecer frete grátis.

Disponibilidade

Minimum weight (kg): oculta o método quando o carrinho pesa menos. Os pesos dos produtos são convertidos a partir das classes de peso do OpenCart. Vazio ou 0 significa sem limite.

Maximum weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 15. Os pontos de retirada e os Z-BOX da Packeta costumam aceitar encomendas de até 15 kg; confira o seu contrato com a Packeta. Vazio ou 0 significa sem limite. Um peso mínimo maior que o máximo é recusado ao salvar, e os dois valores anteriores são mantidos.

Minimum cart subtotal: oferece o método somente quando o subtotal do carrinho (após o cupom, sem impostos) atinge este valor.

Geo zone: oferece a Packeta somente para endereços desta zona geográfica. All zones (padrão) significa sem limite. Não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: quando ativado, a zona geográfica não é verificada e o método é oferecido para os países selecionados abaixo. Quando desativado (padrão), ele é oferecido somente na zona geográfica indicada acima.

Countries (ignore zones mode): os países de destino para esse modo. Deixe vazio para usar todos os países da Packeta. Os países fora da rede de pontos de retirada da Packeta 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 pontos de retirada em storage/logs/vfd_pckt_debug.log.php. O arquivo não pode ser lido pela web. Dados pessoais dos clientes e a chave de API não são registrados. Erros e verificações de chave de API com falha são sempre registrados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_pckt_debug.old.log.php e um novo log é iniciado.

Log (last lines): mostra o tamanho e as últimas entradas do log de depuração. Clique em Clear log para limpá-lo.

Remove data on uninstall: quando ativado, a desinstalação da extensão apaga as configurações e o log. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. O ponto de retirada salvo nos pedidos é sempre mantido.

Importação / Exportação

Exportação: clique em Download JSON para salvar as configurações em um arquivo JSON, incluindo a chave de API, que é pública.

Importação: 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 exibe os métodos de envio, ele pede à extensão o preço da Packeta. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Packeta não é oferecida. Somente os produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no subtotal. A extensão verifica as condições: país de entrega na rede da Packeta, chave de API, lista de países no modo de ignorar zonas, peso do carrinho e subtotal mínimo do carrinho. O subtotal é o preço dos produtos que precisam de envio, após o desconto do cupom e sem impostos. Vale-presente, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o preço é 0. Caso contrário, o preço vem da tabela de países e, depois, do custo de contingência. Se não houver preço, o método fica oculto. O preço é exibido ao cliente em sua moeda, com o imposto da Tax status selecionada.

Abaixo da opção da Packeta na etapa de método de envio há um botão Choose pickup point. Ele abre no navegador do cliente o widget oficial da Packeta, com o país de destino, o peso do carrinho, os tipos de ponto escolhidos e o idioma do widget. Depois que o cliente escolhe um ponto, o nome e o endereço dele aparecem abaixo do método, e o botão muda para Change pickup point. O ponto é salvo para a sessão de finalização de compra e permanece quando a página é recarregada. Um ponto escolhido para outro país não é usado quando o endereço de entrega muda para outro país.

O seu servidor não solicita nada à Packeta durante a finalização de compra. O script do widget é carregado de widget.packeta.com, somente na página de finalização de compra. Se ele for bloqueado (por um bloqueador de anúncios ou de privacidade, uma política de segurança de conteúdo ou uma queda da Packeta), o cliente vê a mensagem "The Packeta pickup point widget could not be loaded. Please reload the page or choose another shipping method."

As tarifas da Packeta não são consultadas em tempo real; elas vêm da sua tabela. A extensão não cria envios na Packeta, não imprime etiquetas nem rastreia encomendas, e não oferece entrega em domicílio nem pontos de transportadoras parceiras de fábrica. Informe o ID do ponto de retirada do pedido à Packeta da forma habitual, por exemplo por importação em client.packeta.com. O botão de ponto de retirada funciona com a finalização de compra padrão do OpenCart no tema padrão.

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 a Packeta na janela Shipping method options. O botão Choose pickup point e o ponto escolhido aparecem nessa janela, abaixo da opção Packeta, e o widget da Packeta abre por cima dela. As tarifas são as mesmas do OpenCart 3.

Pontos de retirada

O ponto de retirada é obrigatório. Se o cliente clicar em Continue na etapa de método de envio sem escolher um, a etapa não é concluída e o cliente vê a mensagem "Please choose a Packeta pickup point." Se o ponto escolhido estiver em outro país que não o do endereço de entrega, o cliente vê "The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again." A extensão não verifica o ID do ponto na Packeta; ela só confere se um ponto foi escolhido e se o país dele confere.

O ponto é associado ao pedido quando ele é criado:

Método de envio do pedido: o nome e o endereço do ponto são acrescentados ao nome do método, por exemplo Packeta pickup point: <point> (até 128 caracteres). O cliente vê isso no histórico do pedido e no e-mail do pedido, e aparece impresso na nota fiscal. A página de confirmação do pedido do OpenCart não mostra o método de envio.

Página do pedido na administração: abra o pedido em Sales > Orders. Um painel Packeta pickup point mostra o nome e o endereço, o Pickup point ID e o país. Se um pedido da Packeta não tiver ponto, o painel indica "No pickup point was selected for this order."

No OpenCart 4, o botão Continue da janela Shipping method options não avança sem um ponto, com as mesmas mensagens. 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 ponto do pedido é atualizado junto. O painel Packeta pickup point da página do pedido na administração é exibido acima da seção History.

O ponto é armazenado na tabela própria da extensão, vfd_pckt_point (sessão de finalização de compra, pedido, ID do ponto, nome e endereço, país).

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 Packeta é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Packeta > 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 deles estão a linha Product: opencart-shipping-packeta e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do administrador (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 ú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 vibefox.net.

Sem uma chave ativa, a Packeta não é exibida 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 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

A Packeta não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ativado, se a API key foi informada e se o país de entrega é CZ, SK, HU ou RO. Confira se há um preço definido para o país (linha do país, linha * Default ou Fallback cost), os limites de peso e de subtotal, e a Geo zone (ou Ignore shipping zones e os seus países). Confira se os produtos têm Requires Shipping definido como Yes. A página de configurações lista no topo os problemas de configuração. Ative o Debug log para ver o motivo em Log (last lines).

A Packeta recusou a chave de API: copie a chave de API novamente em client.packeta.com > Client support e salve. Até lá, o widget não pode abrir na finalização de compra.

O widget não abre: o script da Packeta está bloqueado por um bloqueador de anúncios ou de privacidade, por uma política de segurança de conteúdo ou por uma queda da Packeta. Permita widget.packeta.com na sua política de segurança de conteúdo.

O frete está grátis por engano: confira em Country prices as linhas com Price igual a 0, especialmente uma linha * Default adicionada com Add country e deixada sem preencher, e confira o Free shipping from.

Os limites de peso ou as colunas de peso parecem errados: se a página avisar sobre a unidade de peso da loja, use classes de peso com a unidade kg, g, lb ou oz e defina a classe de peso padrão em System > Settings, guia Local. As demais unidades são lidas como quilogramas.

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

Para desenvolvedores: outras extensões podem adicionar países, passar opções como IDs de transportadoras ao widget, alterar a URL do script do widget ou o seu idioma com os eventos do OpenCart vfd_packeta/countries, vfd_packeta/widget_options, vfd_packeta/widget_url e vfd_packeta/widget_language (gatilhos com o prefixo catalog/, por exemplo catalog/vfd_packeta/widget_options).

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Packeta. 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 verificação salva da chave de API é sempre removida, e o botão de ponto de retirada e o painel do pedido deixam de ser exibidos. Se Remove data on uninstall estiver ativado, as configurações, o log e os pontos de retirada das finalizações de compra que nunca se tornaram pedidos são apagados. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas ao reinstalar a extensão. Os pedidos existentes mantêm sempre o ponto de retirada salvo e o ponto no método de envio.

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 Packeta na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Packeta é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Packeta.