VibeFox Packeta for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Chave de API da Packeta: você a encontra na seção de cliente da Packeta (client.packeta.com), em Client support. Ela tem 16 letras e dígitos. O widget precisa dela para abrir na finalização de compra, por isso o método só é mostrado aos clientes depois que a chave de API é inserida.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta vfd_packeta para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Packeta, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira sua API key da Packeta e seus preços: pelo menos uma linha em Country prices (por exemplo * Default) ou um Fallback cost. Salve. A página mostra se a Packeta aceitou a chave.
6. Adicione VibeFox Packeta às suas zonas de envio da República Checa, Eslováquia, Hungria ou Romênia em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Packeta. Elas valem para todas as zonas de envio. Quando você adiciona o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome que os clientes veem nesta zona. Deixe em branco para usar o Name global.
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 de problemas, por exemplo chave de API ausente, preço ausente ou países selecionados fora da rede da Packeta.
Todos os preços e limites aceitam vírgula ou ponto como separador decimal (4,99 ou 4.99). Um número inválido é recusado com uma mensagem, e o valor anterior é mantido.
Geral
Enable/Disable: ativa ou desativa o método em todas as zonas de uma vez.
Name: o nome do método de envio exibido ao cliente. Uma zona pode substituí-lo pelo seu próprio Title. Padrão: Packeta pickup point.
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 com o 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: Taxable adiciona o imposto do WooCommerce ao custo de envio; None não adiciona.
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 da loja.
Calculation type: Per order cobra o preço uma única vez. Per item (price x quantity) o multiplica pelo número de itens enviáveis 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 países sem 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 estiver em duas linhas, somente a primeira é mantida ao salvar.
Fallback cost: usado quando a tabela de países não tem linha para o destino e não existe uma linha * Default. Deixe em branco para não oferecer o método ali.
Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual a entrega pela Packeta é gratuita. Vale somente onde há um preço definido: uma linha de país, a linha * Default ou o custo de contingência. Deixe em branco para nunca oferecer frete grátis.
Disponibilidade
Minimum weight (kg): oculta o método 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 o método quando o carrinho pesa mais. Padrão: 15. Os pontos de retirada e os Z-BOXes da Packeta costumam aceitar encomendas de até 15 kg; confira o seu contrato com a Packeta. Vazio ou 0 significa sem limite.
Minimum cart subtotal: oferece o método somente quando o subtotal do carrinho (após descontos, sem impostos) atinge este valor.
Excluded shipping classes: oculta o método quando o carrinho contém um produto de qualquer uma destas classes de envio do WooCommerce.
Ignore shipping zones: quando ativado, o método é oferecido para os países selecionados abaixo, mesmo que não esteja adicionado à zona de envio correspondente. Quando desativado, o método é oferecido somente nas zonas às quais foi adicionado.
Countries (ignore zones mode): os países de destino para esse modo. Deixe em branco para usar todos os países da Packeta. 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: registra os cálculos de tarifas e as escolhas de pontos de retirada em WooCommerce > Status > Logs (origem “vfd-packeta”). Nenhum dado pessoal do cliente e nenhuma chave de API são registrados. As verificações de chave de API que falharam são sempre registradas. Desative o log quando terminar.
Remove data on uninstall: quando ativado, excluir o plugin remove as configurações e as instâncias do método nas zonas. Desativar o plugin nunca apaga nada. O ponto de retirada salvo nos pedidos é sempre mantido.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o WooCommerce pede uma tarifa ao plugin. O plugin verifica as condições: país de entrega na rede da Packeta, chave de API, peso do carrinho, subtotal mínimo do carrinho e classes de envio excluídas. O preço vem da tabela de países e, em seguida, do custo de contingência. Se não houver preço, o método fica oculto. Se o frete grátis se aplicar, o cliente vê o método sem custo.
Quando o cliente seleciona o método da Packeta, aparece abaixo dele 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 são exibidos abaixo do método, e o botão muda para Change pickup point. A escolha fica salva na sessão do cliente quando a finalização de compra é atualizada ou a página é recarregada.
Seu servidor não solicita nada à Packeta durante a 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 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.”
O método funciona na finalização de compra clássica e nos blocos de Carrinho e Finalização de compra. É compatível com o HPOS (High-Performance Order Storage) do WooCommerce.
Os preços da Packeta não são consultados em tempo real; eles vêm da sua tabela. O plugin não cria envios na Packeta, não imprime etiquetas e não rastreia encomendas. Também não oferece entrega em domicílio nem pontos de retirada de transportadoras parceiras por padrão. Envie o ID do ponto de retirada do pedido à Packeta da forma que você costuma fazer, por exemplo por importação no client.packeta.com.
Pontos de retirada
O ponto de retirada é obrigatório. Se o cliente fizer o pedido sem escolher um, a finalização de compra é interrompida com 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, a finalização de compra é interrompida com a mensagem “The selected Packeta pickup point is not in your shipping country. Please choose a pickup point again.”. As duas verificações são feitas no servidor, tanto na finalização de compra clássica quanto na de blocos. O plugin não verifica o ID do ponto junto à Packeta; ele apenas confere se um ponto foi escolhido e se o país corresponde.
O ponto é salvo com o pedido no momento em que ele é criado:
Tela do pedido no painel administrativo: Packeta pickup point com o nome, o endereço, Pickup point ID e o país, abaixo do endereço de entrega. Se um pedido da Packeta não tiver ponto, a tela informa “No pickup point was selected for this order.”.
Página de agradecimento e visualização do pedido: Packeta pickup point: com o nome e o endereço.
E-mails do pedido: o nome e o endereço do ponto nos e-mails em HTML e em texto simples. Os e-mails para o administrador também incluem o Pickup point ID.
No banco de dados, o ponto é armazenado nos metadados do pedido _vfd_pckt_point_id, _vfd_pckt_point_name (nome e endereço) e _vfd_pckt_point_country.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Shipping > VibeFox Packeta. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga de domínio dele. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, a Packeta não é exibida aos clientes na finalização de compra. Os gerentes da loja conectados ainda a veem, marcada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.
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á ligado, se a API key foi informada e se o país de destino é 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, Excluded shipping classes e se o método foi adicionado à zona correspondente (ou se Ignore shipping zones está ativado). A página de configurações lista no topo os problemas de configuração. Ative o Debug log para ver o motivo em WooCommerce > Status > Logs.
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. Desenvolvedores podem alterar a URL do script com o filtro vfd_pckt_widget_url.
O frete está grátis por engano: confira em Country prices as linhas com Price igual a 0, principalmente uma linha * Default adicionada com + Add country e deixada sem preencher.
Outros países ou transportadoras: por padrão, o método funciona para CZ, SK, HU e RO. Desenvolvedores podem adicionar países com o filtro vfd_pckt_countries e passar IDs de transportadoras ao widget com o filtro vfd_pckt_widget_options.
O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta na vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos, junto com a verificação de chave de API salva. As configurações e os métodos nas zonas só são removidos se Remove data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas linhas de envio e o ponto de retirada salvo.
A Packeta é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Packeta.