VibeFox Packeta for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões mais antigas do PHP.
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 a transportadora só é mostrada aos clientes depois que a chave de API é informada.
Países: a República Tcheca, a Eslováquia, a Hungria ou a Romênia devem ser países ativos da sua loja, em uma zona à qual a transportadora esteja vinculada.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em 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 VibeFox Packeta depois na lista de módulos e clique em Configure.
3. Informe sua chave de licença VibeFox em License key no bloco de licença no topo da página de configuração e clique em Activate (veja Chave de licença).
4. Informe sua API key da Packeta e seus preços: pelo menos uma linha em Country prices (por exemplo * Default) ou um Fallback cost. Clique em Save. A página mostra se a Packeta aceitou a chave.
Na instalação, o módulo cria a transportadora Packeta pickup point com o texto de prazo de entrega Packeta pickup point or Z-BOX. Ela é vinculada às zonas da República Tcheca, da Eslováquia, da Hungria e da Romênia e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega e logotipo em Shipping > Carriers. Não defina preços ali: o preço sempre vem do módulo.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Packeta > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira.
A transportadora só é oferecida 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 de problemas: chave de API ausente, preço ausente, países selecionados fora da rede da Packeta, transportadora ausente ou uma unidade de peso da loja que o módulo não reconhece.
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, e o valor anterior é mantido.
Geral
Enable/Disable: ativa ou desativa a Packeta na finalização de compra.
Name: o nome da transportadora mostrado ao cliente. É também o nome da transportadora em Shipping > Carriers. Padrão: Packeta pickup point. Obrigatório, no máximo 64 caracteres.
API key: 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 16 primeiros 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 chave nova, ela é verificada no feed de transportadoras da Packeta, e a página mostra Packeta API key verified ou que a Packeta a recusou. Se a verificação não puder ser feita, a chave é salva e verificada de novo na próxima vez que você salvar.
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: as regras de imposto aplicadas ao preço do envio. None (no tax on shipping) ou Taxable com um dos seus grupos de regras de imposto. A escolha é salva na transportadora.
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. Clientes que pagam em outra moeda veem o preço convertido.
Calculation type: Per order cobra o preço uma única vez. Per item (price x quantity) multiplica o preço pelo número de itens físicos no carrinho.
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 x para remover uma. 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 linha nova 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, ao salvar só a primeira é mantida. Se algum valor da tabela não for um número válido, 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 uma linha para o destino e não há linha * Default. Deixe em branco para não oferecer a transportadora nesse caso.
Free shipping from: o subtotal do carrinho (após descontos, 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 a transportadora é oferecida, mesmo em um país sem linha ou custo de contingência. Deixe em branco para nunca oferecer frete grátis.
Disponibilidade
Minimum weight (kg): oculta a transportadora quando o carrinho pesa menos. O peso do carrinho é convertido a partir da unidade de peso da sua loja. Vazio ou 0 significa sem limite.
Maximum weight (kg): oculta a transportadora quando o carrinho pesa mais. Padrão: 15. Os pontos de retirada e os Z-BOXes da Packeta geralmente aceitam 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 a transportadora somente quando o subtotal do carrinho (após descontos, sem impostos) atinge este valor.
Ignore shipping zones: quando ativado, a transportadora fica vinculada a todas as zonas e é oferecida para os países selecionados abaixo. Zonas criadas depois são vinculadas imediatamente. Ao desativar, a transportadora recupera as zonas que tinha antes. Quando desativado, ela é oferecida somente nas zonas definidas para a transportadora em Shipping > Carriers.
Countries (ignore zones mode): os países de destino para esse modo. Deixe vazio para usar todos os países da Packeta. Países fora da rede de pontos de retirada da Packeta são ignorados. Mantenha Ctrl pressionado e clique para selecionar vários. 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 modules/vfd_packeta/logs/. O arquivo não pode ser aberto pela web. Não são registrados dados pessoais de clientes nem a chave de API. Erros e verificações de chave de API que falham são sempre registrados. Desative o log quando terminar.
Log (last lines): mostra as últimas entradas do log de depuração. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, desinstalar o módulo apaga as configurações e o log. O ponto de retirada salvo nos pedidos é sempre mantido.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço da Packeta. Somente produtos físicos contam: produtos virtuais não somam peso e não entram no subtotal. O módulo 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. 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, a transportadora fica oculta.
Quando o cliente seleciona a transportadora da Packeta, aparece abaixo dela o 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 da transportadora, e o botão muda para Change pickup point. O ponto é salvo com o carrinho e mantido quando a página é recarregada. Um ponto escolhido para outro país é descartado quando o endereço de entrega muda.
Seu servidor não consulta a Packeta na finalização de compra. O script do widget é carregado de widget.packeta.com. Se ele for bloqueado (por um bloqueador de anúncios ou de privacidade, uma política de segurança de conteúdo ou uma instabilidade 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.”
Se você editar a transportadora em Shipping > Carriers depois que ela tiver pedidos, o PrestaShop a salva como uma nova versão da transportadora. O módulo passa a seguir a nova versão automaticamente.
Os preços da Packeta não são consultados em tempo real; eles vêm da sua tabela. O módulo não cria envios na Packeta, não imprime etiquetas nem rastreia encomendas, e não oferece entrega em domicílio nem pontos de retirada de transportadoras parceiras por padrão. Informe o ID do ponto de retirada do pedido à Packeta da forma habitual, por exemplo por importação no client.packeta.com.
Pontos de retirada
O ponto de retirada é obrigatório. Se o cliente clicar em Continue na etapa 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ê a mensagem: “The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again.” O módulo não verifica o ID do ponto junto à Packeta; ele apenas confere se um ponto foi escolhido e se o país dele corresponde.
O ponto é associado ao pedido quando o pedido é criado:
Página do pedido no back office: um bloco Packeta pickup point com o nome, o endereço, o Pickup point ID e o país. Se um pedido da Packeta não tiver ponto, o bloco diz: “No pickup point was selected for this order.”
Páginas de confirmação e de detalhes do pedido: Packeta pickup point: com o nome e o endereço.
E-mails do pedido: o nome e o endereço do ponto são acrescentados à transportadora no e-mail de confirmação do pedido. O e-mail de novo pedido para o lojista também inclui o Pickup point ID.
O ponto é armazenado na tabela do módulo vfd_pckt_point (carrinho, pedido, ID do ponto, nome e endereço, país).
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 Packeta é o primeiro bloco de Modules > Module Manager > VibeFox Packeta > Configure, 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 deles estão a linha Product: presta-shipping-packeta 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 para o 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 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, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o domínio da loja principal, também em uma configuração 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 da Packeta não é mostrada aos clientes na finalização de compra e nenhuma tarifa é calculada. A vitrine do 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 pode testá-lo na finalização de 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 Packeta não aparece na finalização de compra: verifique 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 se a transportadora cobre a zona do país do cliente e o grupo do cliente em Shipping > Carriers (ou se Ignore shipping zones está ativado). Produtos também podem ser limitados a determinadas transportadoras na página do produto. 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 instabilidade da Packeta. Permita widget.packeta.com na sua política de segurança de conteúdo. Desenvolvedores podem alterar a URL do script com o hook actionVfdPcktWidgetUrl.
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 não preenchida, e confira o Free shipping from.
Os limites de peso ou as colunas de peso parecem errados: se a página alertar sobre a unidade de peso da loja, defina kg, g, lb ou oz em International > Localization (Local units). Outras unidades são lidas como quilogramas.
Outros países ou transportadoras: por padrão, a transportadora funciona para CZ, SK, HU e RO. Desenvolvedores podem adicionar países com o hook actionVfdPcktCountries e passar os IDs das transportadoras ao widget com o hook actionVfdPcktWidgetOptions.
A página informa que a transportadora da Packeta está ausente: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Packeta e escolha Uninstall. A chave de licença e o status da licença são sempre removidos. A transportadora da Packeta é sempre removida (os pedidos mantêm a transportadora deles), junto com o resultado salvo da verificação da chave de API. Se Remove data on uninstall estiver ativado, são apagados as configurações, o log e os pontos de retirada de carrinhos que nunca se tornaram pedidos. Se estiver desativado, as configurações são mantidas para uma reinstalação, que cria a transportadora novamente. Os pedidos existentes sempre mantêm o ponto de retirada salvo.
A Packeta é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pela Packeta.