VibeFox Balikobot 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.
Conta no Balikobot (para tarifas em tempo real e pontos de retirada): você precisa de uma conta no Balikobot com acesso à API. O usuário da API e a chave da API ficam na área do cliente do Balikobot (client.balikobot.cz). O suporte do Balikobot (podpora@balikobot.cz) ativa a API para a sua conta e para as suas transportadoras. As tarifas em tempo real exigem uma transportadora e um serviço para os quais o Balikobot oferece suporte a "transportcosts". Os pontos de retirada exigem uma transportadora com suporte a "branchlocator" (por exemplo Česká pošta, Zásilkovna, PPL, DPD, GLS). Em caso de dúvida, consulte o suporte do Balikobot. Os preços fixos funcionam sem conta.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_balikobot para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Shipping > VibeFox Balikobot, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Informe o usuário e a chave da API, escolha a transportadora, o tipo de serviço, a fonte de preço e os preços por país (veja Configuração). Para serviços com retirada, ative Pickup point selection.
6. Adicione VibeFox Balikobot a uma zona de envio (por exemplo, Tchéquia) em WooCommerce > Settings > Shipping > Shipping zones, ou ative Ignore shipping zones e escolha os países.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Shipping > VibeFox Balikobot. Elas valem para todas as zonas de envio. Avisos sobre configurações que ocultariam o método, as tarifas em tempo real ou os pontos de retirada aparecem no topo da página. Sempre que você salva as configurações, as tarifas e os pontos de retirada em cache são limpos. Ao adicionar o método a uma zona, a janela da zona tem apenas um campo:
Title (zone): o nome do método de envio exibido aos clientes nesta zona. Deixe em branco para usar o Name global.
Geral
Enable/Disable: ativa ou desativa o envio pelo Balikobot em todas as zonas de uma vez.
Name: o nome do método de envio exibido aos clientes. Uma zona pode substituí-lo pelo próprio Title. Padrão: Balikobot.
Tax status: Taxable significa que o WooCommerce adiciona o imposto sobre o envio ao preço; None significa que não adiciona. Os preços do Balikobot geralmente não incluem imposto.
Conta de API do Balikobot (necessária para tarifas em tempo real e pontos de retirada)
API user: o seu usuário de API do Balikobot, obtido na área do cliente.
API key: a sua chave de API do Balikobot, obtida na área do cliente.
Carrier: a transportadora do Balikobot usada para tarifas e pontos de retirada: Česká pošta (padrão), Zásilkovna (Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS (Slovak Parcel Service) ou Magyar Posta. Ela precisa estar ativada na sua conta do Balikobot.
Service type: o código de serviço do Balikobot da transportadora. Padrão: NP. Para Česká pošta: NP = encomenda para uma agência dos Correios, NB = encomenda para a Balíkovna, DR = entrega em domicílio. Os códigos de outras transportadoras estão na área do cliente do Balikobot e na documentação da API.
Preço (todos os preços estão na moeda da sua loja)
Price source: como o preço é calculado.
Country prices: um preço fixo por país de destino (código de 2 letras, por exemplo CZ, SK). Use * para todos os demais países. Decimais com ponto ou vírgula. Usado no modo fixo e como alternativa quando a API falha. Um país sem preço (e sem linha *) não recebe tarifa fixa.
Fixed price per: Order cobra o preço uma única vez. Item (price × quantity) multiplica o preço pela quantidade de itens no carrinho. Isso vale somente para preços fixos. Uma tarifa em tempo real do Balikobot é sempre para o pacote inteiro.
Exchange rate: o valor de 1 unidade da moeda do preço do Balikobot (geralmente CZK) na moeda da sua loja, por exemplo 0.04. Usado apenas quando o Balikobot retorna um preço em outra moeda. Deixe em branco para rejeitar esses preços, para que o cliente nunca pague um valor incorreto.
Condições
Min weight (kg): oculta o método quando o carrinho é mais leve. 0 significa sem limite. Os pesos dos produtos são convertidos a partir da unidade de peso da sua loja.
Max weight (kg): oculta o método quando o carrinho é mais pesado. Padrão: 100. 0 significa sem limite.
Minimum order amount: exibe o método somente a partir deste subtotal do carrinho (após descontos, sem impostos). Deixe em branco para exibi-lo sempre.
Excluded shipping classes: oculta o método se o carrinho contiver um produto de qualquer uma destas classes de envio do WooCommerce.
Free shipping: ativa o frete grátis a partir do valor indicado abaixo.
Free shipping from: o subtotal do carrinho (após descontos, sem impostos) a partir do qual o frete é grátis. Nesse caso, nenhuma solicitação é feita à API.
Disponibilidade sem zonas de envio
Ignore shipping zones: oferece o método nos países indicados abaixo, mesmo que ele não tenha sido adicionado à zona correspondente.
Countries: os países de destino para esse modo. Deixe em branco para usar todos os países para os quais você envia. Usado somente com Ignore shipping zones.
Pontos de retirada
Pickup point selection: o cliente deve escolher um ponto de retirada. Use para serviços com retirada, por exemplo Česká pošta NP ou NB, ou Zásilkovna. Exige usuário e chave da API.
Selector width: a largura CSS da lista de pontos de retirada, por exemplo 100% ou 400px. Padrão: 100%.
Avançado
Debug log: registra as solicitações à API e os cálculos de tarifas em WooCommerce > Status > Logs, origem "vfd-balikobot". Erros da API são sempre registrados. Credenciais e endereços dos clientes nunca são registrados.
Remove data on uninstall: quando ativado, ao excluir o plugin suas configurações e os métodos das zonas são removidos. Desativar o plugin nunca apaga dados. Os pontos de retirada salvos nos pedidos são mantidos.
Como funciona na finalização de compra
Quando o cliente informa um endereço de entrega, o plugin verifica o peso do carrinho, o Minimum order amount e as Excluded shipping classes. Se o frete grátis se aplicar, a tarifa é 0 e nenhuma solicitação é enviada ao Balikobot.
No modo fixo, o preço é obtido de Country prices. Nos modos em tempo real, o plugin envia ao Balikobot a transportadora, o tipo de serviço, o país e o CEP de destino e o peso do carrinho em kg. A tarifa em tempo real só é solicitada depois que o cliente informa um CEP. Um preço em outra moeda é convertido com Exchange rate ou rejeitado, caso nenhuma taxa esteja definida.
Os preços em tempo real ficam em cache por 1 hora, para que o mesmo carrinho não gere uma nova solicitação. Uma solicitação que falhou fica em cache por 5 minutos, e o tempo limite da API é de 12 segundos, para que a finalização de compra não espere pelo Balikobot a cada atualização. Erros da API nunca são exibidos ao cliente: o método é ocultado ou, no modo de contingência, é usado o preço fixo. Os detalhes são registrados no log.
O método funciona na finalização de compra clássica e nos blocos Carrinho e Finalização de compra. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin não cria envios no Balikobot, não imprime etiquetas nem solicita coletas: faça o pedido de envio na área do cliente do Balikobot. Ele não rastreia pacotes nem atualiza os status dos pedidos. Uma única transportadora e um único tipo de serviço são usados em todas as zonas. Os pontos de retirada são exibidos como uma lista suspensa, sem mapa.
Pontos de retirada
Com Pickup point selection ativado, uma lista de pontos de retirada aparece abaixo da opção do Balikobot na finalização de compra, tanto na clássica quanto no bloco. A lista é carregada do "branchlocator" do Balikobot para o país, a cidade e o CEP do cliente. Enquanto a cidade e o CEP não forem informados, o cliente vê Enter your city and postcode to see the pickup points. A lista fica em cache por 12 horas.
A escolha é obrigatória: o cliente vê Please select a pickup point. O servidor também verifica se o ponto escolhido pertence ao endereço de entrega. Após uma mudança de endereço, o cliente é solicitado a escolher um ponto de retirada novamente. Se os pontos não puderem ser carregados, o cliente é orientado a tentar mais tarde ou a escolher outro método de envio.
O ponto de retirada escolhido é salvo no pedido. Na tela de pedido do admin, ele aparece abaixo do endereço de entrega como Balikobot pickup point, com o ID da filial do Balikobot e a transportadora, que você precisa ao criar o envio no Balikobot. Clique em Change para escolher outro ponto perto do endereço do pedido. O cliente vê o ponto como Pickup point na página do pedido e nos e-mails do pedido (HTML e texto simples). Os pedidos já existentes mantêm os dados do ponto de retirada.
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 Balikobot. 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 informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta no vibefox.net.
Sem uma chave ativa, o Balikobot não é exibido aos clientes na finalização de compra. Os gerentes da loja conectados ainda o veem, marcado 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 novamente de forma automática em segundo plano.
Solução de problemas
O Balikobot não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o método foi adicionado à zona do país do cliente (ou se Ignore shipping zones está ligado e o país está permitido). Leia os avisos no topo da página de configurações. Confira os limites de peso, Minimum order amount e Excluded shipping classes. No modo fixo, verifique se o país ou * tem um preço.
As tarifas em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e abra WooCommerce > Status > Logs (origem "vfd-balikobot"). Ali aparece o motivo: credenciais da API ausentes, CEP ainda não informado, o erro do Balikobot para a transportadora e o serviço, ou um preço em outra moeda sem Exchange rate. Com Live Balikobot rate, fixed price if the API fails, os clientes continuam recebendo o preço fixo enquanto você resolve o problema.
Os preços estão na moeda errada: os preços fixos estão na moeda da sua loja. O Balikobot retorna os preços em tempo real na moeda do seu contrato com o Balikobot (geralmente CZK). Se ela for diferente da moeda da loja, defina Exchange rate.
O IVA está incluído? Os preços do Balikobot geralmente não incluem imposto. Com Tax status definido como Taxable, o WooCommerce adiciona o imposto sobre o envio.
Nenhum ponto de retirada na lista: verifique se o usuário e a chave da API estão preenchidos, se a transportadora oferece suporte a "branchlocator" e se o cliente informou cidade e CEP. Consulte o log para ver o erro do Balikobot.
Tarifas ou pontos de retirada parecem desatualizados após uma mudança: salve a página de configurações. Isso limpa as tarifas e os pontos de retirada em cache.
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 do 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 todas as configurações e apenas limpa os caches. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin, assim como as tarifas e os pontos de retirada em cache, são sempre removidos. As configurações e os métodos das zonas são removidos somente se Remove data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados de pontos de retirada salvos nos pedidos nunca são excluídos.
O Balikobot é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo Balikobot.