VibeFox Balikobot for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Conta Balikobot (para tarifas em tempo real e pontos de retirada): você precisa de uma conta Balikobot com acesso à API. O usuário 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 "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 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_balikobot-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_balikobot.ocmod.zip. Instale apenas 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 administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_balikobot-oc3-(version).ocmod.zip. A extensão não adiciona modificações OCMOD, então 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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Balikobot e clique em Install (o botão verde +).
3. Clique em Edit (o botão do lápis) para abrir a página de configurações.
4. Digite 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 Chave de licença).
5. Informe o usuário e a chave da API, escolha a transportadora e o tipo de serviço, a fonte do preço e os preços por país (veja Configuração). Para serviços com retirada, ative Pickup point selection. Ative Enable/Disable e clique em Save.
OpenCart 4
1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_balikobot.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão pelo 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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Balikobot, clique em Install (o botão verde +) e depois em Edit (o botão do lápis).
4. Digite a chave de licença e as configurações como nos passos 4 e 5 do OpenCart 3. A página de configurações e os campos são os mesmos nas duas versões.
Ao instalar, a extensão cria uma tabela para os pontos de retirada das finalizações de compra e dos pedidos. O método fica desativado até que você ative Enable/Disable e salve. Se você instalar a extensão novamente após uma desinstalação, as configurações do Balikobot 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 Balikobot > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Depois de salvar, você vê Settings saved. Cached rates and pickup points were cleared. Somente usuários administradores com a permissão de modificação desta extensão podem salvar as configurações.
Alguns erros impedem o salvamento, e nada é salvo: um Name vazio ou longo demais, um Sort Order que não é um número inteiro, ou uma classe de imposto ou zona geográfica desconhecida. Outros problemas são mostrados como avisos, e o restante das configurações é salvo: um valor que não é número (ou é negativo) não é salvo e o aviso indica o campo; linhas inválidas de Country prices são removidas e listadas.
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: tarifas em tempo real ou pontos de retirada sem usuário ou chave da API, uma moeda da loja diferente de CZK sem Exchange rate, Country prices vazio com preços fixos ou com o modo de contingência, e uma loja sem classe de peso com a unidade kg (os pesos dos produtos são então lidos pelo nome da unidade: kg, g, lb ou oz).
Geral
Enable/Disable: ativa ou desativa a entrega Balikobot na finalização de compra. Padrão: desativado.
Name: o nome do método de entrega exibido aos clientes. Padrão: Balikobot. Obrigatório, no máximo 64 caracteres.
Sort Order: a posição do método na lista de métodos de entrega. Um número inteiro.
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 da área do cliente.
API key: a sua chave de API do Balikobot da área do cliente. Depois de salvar, o campo fica vazio e mostra Saved - leave empty to keep it. Clear the API user to remove the saved key. Digite um valor novo somente se quiser 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 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 lista de países e preços. Clique em Add row para adicionar uma linha e no botão de remover para excluir uma. Escolha * All other countries para todos os países sem linha própria. Decimais com ponto ou vírgula. Usado no modo fixo e como alternativa da API. Um país sem preço (e sem linha *) não recebe tarifa fixa, então o método fica oculto para ele.
Fixed price per: Order (padrão) cobra o preço uma vez. Item (price x quantity) o multiplica pelo número 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 (normalmente CZK) na moeda padrão da sua loja, por exemplo 0.04. Usado somente quando o Balikobot retorna 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 o método quando o carrinho pesa menos. 0 significa sem limite (padrão). Os pesos dos produtos são convertidos a partir da classe de peso do OpenCart.
Max weight (kg): oculta o método quando o carrinho pesa mais. Padrão: 100. 0 significa sem limite. Um campo vazio equivale a 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: mostra o método somente a partir deste subtotal do carrinho (após cupons, sem impostos). Deixe vazio para mostrá-lo sempre.
Free shipping: ativa o frete grátis a partir do valor abaixo.
Free shipping from: o subtotal do carrinho (após cupons, sem impostos) a partir do qual o frete é grátis. Nesse caso nenhuma solicitação é enviada ao Balikobot. Usado somente quando Free shipping está ativado.
Tax Class: o imposto desta classe é somado ao preço da entrega. Os preços do Balikobot normalmente não incluem impostos. Padrão: --- None ---.
Disponibilidade
Normalmente o método é oferecido na zona geográfica selecionada aqui (All Zones significa em qualquer lugar). Ignore geo zone o oferece nos países da lista.
Geo Zone: oferece o método somente para endereços desta zona geográfica. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Ignore geo zone: oferece o método nos países abaixo, independentemente da zona geográfica.
Countries: os países de destino para esse modo. Deixe vazio para permitir todos os países. Usado somente com Ignore geo zone.
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. Exige 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 à API e os cálculos de tarifas em storage/logs/vfd_blkb_debug.log.php. O arquivo não pode ser lido pela web. Erros da API são sempre registrados. Credenciais e endereços de clientes nunca são registrados. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_blkb_debug.old.log.php e um novo log é iniciado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídos as configurações, o log e os pontos de retirada de finalizações de compra sem pedido. Quando desativado (padrão), as configurações são mantidas. Os pontos de retirada salvos nos pedidos são sempre mantidos.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave da API não é exportada.
Import: 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. A chave da API salva é mantida.
Como funciona na finalização de compra
Quando o OpenCart mostra os métodos de entrega, ele pede à extensão o preço do Balikobot. Se houver uma Geo Zone definida (e Ignore geo zone estiver desativado) e o endereço estiver fora dela, o Balikobot não é oferecido. Com Ignore geo zone, a lista Countries decide. Somente produtos com Requires Shipping definido como Yes contam: os demais não adicionam peso e não entram no valor do pedido. A extensão então verifica o peso do carrinho e o Minimum order amount. O valor do pedido é o preço dos produtos que precisam de entrega, após o desconto do cupom e antes dos impostos. Se o frete grátis se aplicar, o preço é 0 e nenhuma solicitação é enviada ao Balikobot.
No modo fixo, o preço vem de Country prices. Nos modos em tempo real, a extensão 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 só é solicitada 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, arredondado para as suas casas decimais e exibido ao cliente na moeda dele, com o imposto da Tax Class selecionada.
Tarifas em tempo real ficam em cache por 1 hora, para que o mesmo carrinho não gere uma nova solicitação. Uma solicitação com falha 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: o método fica oculto, ou o preço fixo é usado no modo de contingência. Os detalhes vão para o log de depuração.
A extensão não cria envios no Balikobot, não imprime etiquetas e não agenda coletas: faça o pedido de envio na área do cliente do Balikobot. Ela não rastreia encomendas nem altera os status dos pedidos. Uma transportadora e um tipo de serviço são usados para todos os destinos. Os pontos de retirada são exibidos como lista suspensa, sem mapa.
No OpenCart 4, o cliente clica em Choose no bloco do método de entrega da página de finalização de compra e escolhe o Balikobot na janela Shipping method options. O método funciona da mesma forma que no OpenCart 3; a lista de pontos de retirada está descrita em Pontos de retirada.
Pontos de retirada
Com Pickup point selection ativado, uma lista de pontos de retirada aparece abaixo do método Balikobot na etapa Delivery Method da finalização de compra do OpenCart. 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. Enquanto a lista carrega, ele vê Loading pickup points.... A lista fica em cache por até 12 horas.
A escolha é salva assim que o cliente seleciona um ponto. Ela é obrigatória: Continue na etapa de entrega é recusado 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 o Balikobot não puder ser acessado naquele momento, um ponto já escolhido é aceito. Se nenhum ponto for encontrado, o cliente é orientado a conferir a cidade e o CEP ou a escolher outro método de entrega. Se os pontos não puderem ser carregados, o cliente é orientado a tentar novamente mais tarde ou a escolher outro método de entrega.
No OpenCart 4, o cliente clica em Choose no bloco do método de entrega da página de finalização de compra. A janela Shipping method options mostra a lista de pontos de retirada abaixo do método Balikobot, com os mesmos textos e verificações. A lista é carregada sempre que a janela é aberta, porque o endereço pode mudar na mesma página de finalização de compra, e vem do cache quando possível. Se o cliente clicar em Continue na janela sem um ponto válido, a mensagem aparece no topo da página de finalização de compra e a janela continua aberta. O OpenCart 4 mantém um único pedido para a finalização de compra e o atualiza a cada confirmação; o ponto de retirada do pedido é atualizado junto.
O ponto escolhido é adicionado ao método de entrega do pedido como - Pickup point:, seguido do nome e do endereço. O cliente o vê nas páginas de pedido da conta dele e nos e-mails de pedido, e ele é impresso na nota fiscal.
Na página de pedido do administrador (Sales > Orders, View), o painel Balikobot pickup point mostra o ponto, o seu ID no Balikobot e a transportadora, que você precisa ao criar o envio no Balikobot. Clique em Change, escolha outro ponto perto do endereço do pedido e clique em Save. O texto do método de entrega do pedido também é atualizado, e você verá Pickup point updated. Alterar o ponto exige apenas a permissão de modificação de pedidos, não o acesso às configurações da extensão. Se um pedido não tiver ponto, o painel mostra No pickup point was selected for this order. O painel também funciona com o Balikobot desativado: os pedidos existentes mantêm os dados do ponto de retirada, e você ainda pode alterar o ponto.
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 Balikobot é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Balikobot > Edit, acima das configurações. Digite 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 digitar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-shipping-balikobot e o link Manage licenses and domains in your account, que abre a sua conta no vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 for alterado, 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 domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta do vibefox.net.
Sem uma chave ativa, o Balikobot não é exibido aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao painel 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 visualização não está disponível: a loja não enxerga o login do administrador, 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 painel. 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 painel ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, 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
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 da extensão. Confira Geo Zone (ou Ignore geo zone e Countries), os limites de peso e o Minimum order amount. No modo fixo, confira se o país ou * All other countries tem um preço. Confira se os produtos têm Requires Shipping definido como Yes.
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 da extensão. Ele mostra o motivo: credenciais de API ausentes, CEP ainda não informado, o erro do Balikobot para a transportadora e o serviço (por exemplo "authorization failed: check the API user and API key"), 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 ficam na moeda padrão da sua loja. O Balikobot retorna as tarifas em tempo real na moeda do seu contrato com o Balikobot (normalmente CZK). Se ela for diferente da moeda padrão, defina Exchange rate.
O imposto está incluído? Os preços do Balikobot normalmente não incluem impostos. Com uma Tax Class selecionada, o OpenCart adiciona o imposto sobre a entrega.
Nenhum ponto de retirada na lista: confira se o usuário e a chave da API estão preenchidos, se a transportadora oferece suporte a "branchlocator" e se o endereço de entrega tem cidade e CEP. Confira o log para ver o erro do Balikobot.
Tarifas ou pontos de retirada parecem desatualizados após uma alteração: clique em Save na página da extensão. Isso limpa as tarifas e os pontos de retirada em cache.
A página diz "Warning: You do not have permission to modify VibeFox Balikobot!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_balikobot (OpenCart 3) ou extension/vfd_balikobot/shipping/vfd_balikobot (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API do Balikobot pode ser substituído pela configuração vfd_blkb_api_url (para testes); ela não tem campo na página de configurações.
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Balikobot. 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 Class e Geo Zone. As tarifas e os pontos de retirada em cache são sempre removidos, e o painel de pontos de retirada e a lista da finalização de compra deixam de funcionar. Se Remove data on uninstall estiver ativado, as configurações, o log e os pontos de retirada de finalizações de compra sem pedido também são excluídos. Se estiver desativado, as demais configurações são mantidas e voltam a ser usadas quando você instalar a extensão novamente. Os dados de pontos de retirada salvos nos pedidos nunca são excluídos, e o texto do método de entrega dos pedidos existentes mantém o ponto de retirada.
No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Balikobot na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para excluir o pacote enviado.
O Balikobot é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pelo Balikobot.