VibeFox Balikobot for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
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 as suas transportadoras. As tarifas em tempo real exigem uma transportadora e um serviço para os quais o Balikobot suporte "transportcosts". Os pontos de retirada exigem uma transportadora com suporte a "branchlocator" (por exemplo, Česká pošta, Zásilkovna, PPL, DPD, GLS). Na dúvida, consulte o suporte do Balikobot. Os preços fixos funcionam sem conta.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, acesse 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, mais tarde, encontre VibeFox Balikobot na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Informe o usuário e a chave da API, escolha a transportadora e o tipo de serviço, a origem do preço e os preços por país (veja Configuração). Para serviços com retirada, ative Pickup point selection. Clique em Save.
Na instalação, o módulo cria a transportadora Balikobot com o texto de prazo de entrega Delivery by Balikobot. A transportadora é atribuída às zonas da Tchéquia, da Eslováquia e da Hungria e a todos os grupos de clientes. Você pode alterar zonas, grupos de clientes, prazo de entrega, logotipo e limites de tamanho 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 Balikobot > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Após salvar, você vê Settings saved. Cached rates and pickup points were cleared. No topo da página aparecem avisos sobre configurações que ocultariam a transportadora, as tarifas em tempo real ou os pontos de retirada: tarifas em tempo real ou pontos de retirada sem usuário ou chave da API, moeda da loja diferente de CZK sem Exchange rate, Country prices vazio com preços fixos ou com o modo de fallback, uma unidade de peso da loja que o módulo não reconhece (os pesos são então lidos como kg; use kg, g, lb ou oz) e uma transportadora excluída. Um valor que não é número não é salvo, e você vê um aviso com o nome do campo.
General
Enable/Disable: ativa ou desativa o envio pelo Balikobot. É o mesmo interruptor do status da transportadora em Shipping > Carriers.
Name: o nome do método de envio exibido ao cliente (o nome da transportadora). Padrão: Balikobot. Obrigatório, no máximo 64 caracteres.
Tax status: None, ou Taxable com uma das suas regras de imposto. Com uma regra de imposto, o imposto dela é somado ao preço do envio. A escolha é salva na transportadora. Os preços do Balikobot geralmente não incluem impostos. Padrão: None.
Conta da API do Balikobot (necessária para tarifas em tempo real e pontos de retirada)
API user: o seu usuário da API do Balikobot, da área do cliente.
API key: a sua chave da API do Balikobot, da área do cliente. Depois de salvar, o campo fica vazio e exibe Saved - leave empty to keep it. Clear the API user to remove the saved key. Digite um novo valor somente para alterá-la.
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 das 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 padrão da sua loja)
Price source: como o preço é calculado.
Country prices: uma tabela de códigos de país de 2 letras (por exemplo, CZ, SK) e preços. Clique em Add row para adicionar um país e no ícone de lixeira para removê-lo. Use * como código de país para todos os outros países. Decimais com ponto ou vírgula. Usada no modo fixo e como fallback da API. Um país sem preço (e sem uma linha *) não recebe tarifa fixa. Linhas inválidas são removidas ao salvar, e um aviso as lista.
Fixed price per: Order cobra o preço uma vez. Item (price x quantity) multiplica o preço pela quantidade de itens no carrinho. Isso se aplica somente aos 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 padrão da sua loja, por exemplo 0.04. Usado somente quando o Balikobot devolve um preço em outra moeda. Deixe vazio para rejeitar esses preços, para que o cliente nunca pague um valor errado.
Condições
Min weight (kg): oculta a transportadora quando o carrinho é mais leve. 0 significa sem limite. Os pesos dos produtos são convertidos a partir da unidade de peso da loja.
Max weight (kg): oculta a transportadora quando o carrinho é mais pesado. Padrão: 100. 0 significa sem limite. Um campo vazio significa 100 kg. Se Min weight (kg) for maior que o máximo, você verá um aviso e os pesos anteriores são mantidos.
Minimum order amount: exibe a transportadora somente a partir deste subtotal do carrinho (após descontos, sem impostos). Deixe vazio para exibi-la sempre.
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 requisição é enviada à API.
Disponibilidade sem zonas de envio
Normalmente a transportadora é oferecida nas suas zonas em Shipping > Carriers.
Ignore shipping zones: oferece a transportadora nos países indicados abaixo, mesmo que ela não esteja vinculada à zona deles. O módulo vincula a transportadora a todas as zonas, inclusive às que você criar depois. Quando você desativa a opção, as zonas adicionadas dessa forma são removidas. As suas próprias zonas permanecem.
Countries: os países de destino desse modo. Deixe vazio 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 precisa escolher um ponto de retirada. Use para serviços com retirada, por exemplo Česká pošta NP ou NB, ou Zásilkovna. Requer o usuário e a 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 requisições da API e os cálculos de tarifas em logs/vfd_blkb_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros da API são sempre registrados. Credenciais e endereços de clientes nunca são registrados. Desative o log quando terminar.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativada, ao desinstalar o módulo são excluídas as suas configurações e a transportadora. Desinstalar sem essa opção nunca apaga dados. Os pontos de retirada salvos nos pedidos são mantidos.
Como funciona na finalização de compra
Na etapa de envio, o PrestaShop pede ao módulo o preço do Balikobot. Só os produtos físicos contam: produtos virtuais não somam peso e não entram no valor do pedido. O módulo verifica primeiro os países (com Ignore shipping zones), o peso do carrinho e o Minimum order amount. Se o frete grátis se aplicar, o preço é 0 e nenhuma requisição é enviada ao Balikobot.
No modo fixo, o preço é obtido de Country prices. Nos modos em tempo real, o módulo 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. Uma tarifa em tempo real é solicitada somente quando o endereço de entrega tem CEP. Um preço em outra moeda é convertido com Exchange rate, ou rejeitado se nenhuma taxa estiver definida. O preço é calculado na moeda padrão da loja e depois exibido na moeda do carrinho do cliente.
Os preços em tempo real ficam em cache por 1 hora, para que o mesmo carrinho não gere uma nova requisição. Uma requisiçã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 mostrados ao cliente: a transportadora é ocultada ou, no modo de fallback, o preço fixo é usado. Os detalhes vão para o log de depuração.
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 acompanha a nova versão automaticamente.
O módulo não cria envios no Balikobot, não imprime etiquetas e não 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 só transportadora e um só tipo de serviço são usados para todas as zonas. Os pontos de retirada são exibidos como lista suspensa, sem mapa.
Pontos de retirada
Com Pickup point selection ativado, uma lista de pontos de retirada aparece sob a transportadora do Balikobot na etapa de entrega. A lista é carregada do "branchlocator" do Balikobot para o país, a cidade e o CEP do endereço de entrega. Enquanto o endereço não tiver cidade, o cliente vê Enter your city to see the pickup points. A lista fica em cache por 12 horas.
A escolha é salva no carrinho assim que o cliente seleciona um ponto. Ela é obrigatória: Continue na etapa de entrega e Place order ficam bloqueados com Please select a pickup point. O servidor também verifica se o ponto escolhido pertence ao endereço de entrega. Caso contrário, o cliente vê The selected pickup point is not available for your shipping address. Please choose a pickup point again. Se nenhum ponto for encontrado, o cliente é orientado a verificar a cidade e o CEP ou a escolher outro método de envio. Se os pontos não puderem ser carregados, o cliente é orientado a tentar novamente mais tarde ou a escolher outro método de envio.
O ponto de retirada escolhido é salvo no pedido. Na página do pedido no back office, ele aparece no bloco 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 e clique em Save. Alterar o ponto exige apenas a permissão para editar pedidos, não o acesso às páginas de Módulos. Se um pedido não tiver ponto, o bloco mostra No pickup point was selected for this order.
O cliente vê o ponto como Pickup point: na página de confirmação do pedido e nos detalhes do pedido. No e-mail de confirmação do pedido e no e-mail de novo pedido para a loja (módulo Mail alerts), ele aparece depois do nome da transportadora. Os pedidos existentes mantêm os dados do ponto de retirada.
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 Balikobot é o primeiro bloco de Modules > Module Manager > VibeFox Balikobot > 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 aparecem a linha Product: presta-shipping-balikobot e o link Manage licenses and domains in your account, que abre a sua conta 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 um slot 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 domínio: o domínio da loja principal, inclusive em uma configuração multiloja. Remover a chave da loja não libera o slot do domínio. Libere o slot na sua conta vibefox.net.
Sem uma chave ativa, a transportadora do Balikobot não é exibida 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
O Balikobot não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado. Leia os avisos no topo da página do módulo. Em Shipping > Carriers, verifique se a transportadora cobre a zona do país do cliente e o grupo do cliente, ou ative Ignore shipping zones e confira Countries. Verifique os limites de peso e o Minimum order amount. No modo fixo, confirme que o país ou * tem um preço. Os produtos também podem ser limitados a determinadas transportadoras na página do produto.
As tarifas em tempo real não aparecem: ative Debug log, recarregue a finalização de compra e veja o campo Log na página do módulo. Ele mostra o motivo: credenciais da API ausentes, ainda sem CEP, o erro do Balikobot para a transportadora e o serviço (por exemplo, authorization failed; verifique o usuário e a chave da API) 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ê corrige o problema.
Os preços estão na moeda errada: os preços fixos estão na moeda padrão da sua loja. O Balikobot devolve as tarifas em tempo real na moeda do seu contrato com o Balikobot (geralmente CZK). Se ela for diferente da moeda padrão, defina Exchange rate.
O imposto está incluído?: os preços do Balikobot geralmente não incluem impostos. Com Tax status definido como uma regra de imposto, o PrestaShop adiciona o imposto do envio.
Não há pontos de retirada na lista: verifique se o usuário e a chave da API estão preenchidos, se a transportadora suporta "branchlocator" e se o endereço de entrega tem cidade e CEP. Verifique o log para o erro do Balikobot.
As tarifas ou os pontos de retirada parecem desatualizados após uma alteração: clique em Save na página do módulo. Isso limpa as tarifas e os pontos de retirada em cache.
A página informa que a transportadora do Balikobot não foi encontrada: a transportadora foi excluída em Shipping > Carriers. Redefina o módulo em Modules > Module Manager para criá-la novamente.
Para desenvolvedores: o módulo tem hooks próprios para alterar o endereço da API (actionVfdBlkbApiUrl), o pacote "transportcosts" (actionVfdBlkbTransportcostsPackage) e o número de pontos de retirada (actionVfdBlkbPickupMaxResults, padrão 30).
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Balikobot e escolha Uninstall. A chave de licença, o status da licença, as tarifas e os pontos de retirada em cache são sempre removidos. Se Remove data on uninstall estiver ativado, a transportadora é excluída (os pedidos mantêm o histórico), e as configurações, o log e os pontos de retirada de carrinhos sem pedido são removidos. Se estiver desativado, a transportadora é apenas desativada e todas as configurações são mantidas. Ao instalar o módulo novamente (ou redefini-lo), a transportadora salva recupera o status de antes da desinstalação: ativada continua ativada, desativada continua desativada. Os dados de ponto de retirada salvos nos pedidos nunca são excluídos.
O Balikobot é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pelo Balikobot.