VibeFox Bob Go for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado com 3.0.5.0) ou 4.0.2 e posteriores (testado com 4.1.0.3).
PHP: 8.0 ou superior.
Conta Bob Go (somente para tarifas em tempo real): a Bob Go não usa chaves de API. Você precisa de uma conta Bob Go (bobgo.co.za), da sua loja instalada como canal de vendas WooCommerce na sua conta Bob Go (Sales channels) e de "Rates at checkout" ativado para esse canal. Serviços, preços e regras são configurados na Bob Go. Se você usar apenas preços fixos, não precisa de uma conta Bob Go.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 README.txt, o pacote do OpenCart 3 vfd_bob_go-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_bob_go.ocmod.zip. Instale somente o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.
OpenCart 3
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_bob_go-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ê também pode copiar o conteúdo da pasta upload do pacote para a pasta raiz da sua loja.
2. Acesse Extensions > Extensions e escolha o tipo de extensão Shipping. Localize VibeFox Bob Go e clique em Install (o botão verde +).
3. Clique em Edit (o botão com o lápis) para abrir a página de configurações.
4. Informe 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. Na sua conta Bob Go, instale sua loja como canal de vendas. Ative "Rates at checkout" para esse canal e configure seus serviços e preços.
6. Na página Edit, confira o domínio da loja, o endereço de origem (de onde você envia) e, se a moeda da sua loja não for ZAR, a taxa de conversão para ZAR (veja Configuração). Ative Enable Bob Go e clique em Save.
OpenCart 4
1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo vfd_bob_go.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do 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. Acesse Extensions > Extensions e escolha o tipo Shipping. Localize VibeFox Bob Go, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).
4. Configure a Bob Go, informe a chave de licença e as configurações como nos passos 4 a 6 do OpenCart 3. A página de configurações e seus campos são iguais nas duas versões.
Depois da instalação, o método fica desativado até que você ative Enable Bob Go e salve. Por padrão, ele usa as tarifas em tempo real da Bob Go. Se você instalar a extensão novamente após uma desinstalação, as configurações da Bob Go que você manteve voltam a ser usadas.
Configuração
Todas as configurações ficam na página da extensão: Extensions > Extensions > Shipping > VibeFox Bob Go > Edit. As seções ficam listadas à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as tarifas da Bob Go em cache. Os números aceitam ponto ou vírgula como separador decimal. Se um valor estiver errado, nada é salvo e a página mostra o motivo: um Method title vazio ou com mais de 64 caracteres, um valor que não é um número ("…" must be a number.), um valor ou peso negativo ("…" must be a number of 0 or more.), uma ZAR conversion rate igual ou menor que 0, um Minimum weight (kg) maior que o Maximum weight (kg), ou uma classe de imposto ou zona geográfica desconhecida. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.
Acima das configurações, a página avisa quando as tarifas em tempo real não podem funcionar: Live rates are not requested: your store currency is … — set the "ZAR conversion rate"., quando a África do Sul não tem zonas (províncias) na sua loja, ou quando a loja não tem uma classe de peso com a unidade "kg" ou uma classe de comprimento com a unidade "cm". Nesse último caso, pesos e dimensões são convertidos pelo nome da unidade da sua classe (kg, g, lb, oz; cm, mm, m, in), e as demais unidades são lidas como kg ou cm.
Geral
As configurações valem para todas as zonas geográficas. Na finalização da compra, cada serviço da Bob Go é uma opção de entrega separada sob o título do método.
Enable Bob Go: mostra ou oculta a Bob Go na finalização da compra. Padrão: desativado.
Method title: o nome do método de envio exibido ao cliente. Os serviços da Bob Go, por exemplo "The Courier Guy - Economy", aparecem listados abaixo com os nomes da Bob Go. Padrão: Bob Go. Obrigatório, no máximo 64 caracteres.
Shipping cost: como o preço é calculado.
O motivo da ausência de tarifas em tempo real é gravado no log. Ele nunca é mostrado ao cliente.
Sort order: a posição da Bob Go entre os métodos de envio na finalização da compra. Um número inteiro.
Conta Bob Go
Esta seção explica o que você precisa ter na Bob Go, com links para sua conta Bob Go, Sales channels e Rates at checkout. Ela também mostra a última resposta da Bob Go para o domínio da sua loja: connected, the WooCommerce channel is not installed on Bob Go (HTTP 404), "Rates at checkout" is not enabled for this channel (HTTP 401 ou 403), ou request failed com o código do erro, ou no connection.
Store domain: a Bob Go identifica sua loja pelo domínio. Deixe em branco para usar o domínio da sua loja, exibido na descrição do campo. Informe outro domínio somente se o seu canal na Bob Go estiver instalado em um endereço diferente, por exemplo example.co.za/shop para uma loja em uma subpasta. O protocolo e a barra final são removidos.
ZAR conversion rate: a Bob Go cota em rand sul-africano (ZAR). Se a moeda padrão da sua loja não for ZAR, informe quanto vale 1 ZAR na sua moeda, por exemplo 0.05. As tarifas são convertidas com esse valor, e os preços dos produtos são enviados à Bob Go em ZAR. Deixe em branco para não usar as tarifas em tempo real da Bob Go na sua moeda (os preços fixos continuam funcionando). A taxa deve ser maior que 0. Se a moeda da sua loja for ZAR, deixe em branco.
Delivery dates: mostra a faixa de datas de entrega estimada pela Bob Go ao lado de cada serviço na finalização da compra. A estimativa é sempre salva com o pedido e fica visível na página do pedido.
Envio de (endereço de origem)
O endereço de origem é enviado à Bob Go em cada solicitação de tarifas. O endereço da loja no OpenCart é texto livre, então só são usados o país e a região da sua loja (System > Settings > Store > Local): se o país da loja for o país de origem, uma província vazia é obtida da região da loja. Informe aqui a cidade, o CEP e a rua.
Origin country: o país de onde você envia. Padrão: South Africa. A Bob Go envia somente dentro da África do Sul.
Origin province: uma província sul-africana, ou Store region (if in South Africa).
Origin city / suburb: a cidade ou o bairro de onde você envia, por exemplo Johannesburg.
Origin postal code: o código postal de onde você envia, por exemplo 2001.
Origin street address: o endereço da rua de onde você envia, por exemplo 123 Main Street.
Preços fixos (usados quando Shipping cost está em Fixed prices (below), e como alternativa quando a Bob Go não retorna tarifas)
Price per country: uma linha por país: um código de país de 2 letras, um sinal de igual e o preço na moeda padrão da sua loja, sem impostos, por exemplo ZA=99.99. Use * para todos os demais países, por exemplo *=199.99 na linha seguinte. Linhas em outro formato são removidas ao salvar, e a página as lista em um aviso.
Flat price: o preço para os países sem uma linha acima. Deixe em branco para ocultar o método nesses países.
Fixed price applies: Per order (padrão) cobra o preço uma vez. Per item (price × quantity) multiplica pelo número de itens no carrinho. As tarifas em tempo real da Bob Go são sempre para o envio inteiro.
Condições
Minimum weight (kg): oculta o método abaixo deste peso do carrinho. 0 significa sem limite (padrão).
Maximum weight (kg): oculta o método acima deste peso do carrinho. 0 significa sem limite (padrão).
Minimum order amount: mostra o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) atinge este valor. Deixe em branco para sempre mostrá-lo.
Free shipping: ativa o frete grátis quando o valor do pedido indicado abaixo é atingido.
Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, sem impostos) a partir do qual o frete é grátis. Usado somente quando Free shipping está ativado. Nesse caso, a Bob Go não é consultada para tarifas.
Tax class: a classe de imposto do custo de envio, ou No tax (padrão). As tarifas da Bob Go normalmente já incluem o IVA. Nesse caso, mantenha No tax para que o imposto não seja cobrado duas vezes sobre o envio.
Geo zone: oferece a Bob Go somente para endereços nesta zona geográfica. All zones (padrão) significa sem limite. Não é usada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.
Disponibilidade sem zonas de envio
Ignore shipping zones: quando ativado, a zona geográfica não é verificada e o método é oferecido para os países abaixo.
Countries: os países de destino para esse modo. Deixe em branco para permitir todos os países. Usado somente quando Ignore shipping zones está ativado.
Avançado
Debug log: grava os cálculos de tarifas e as solicitações à Bob Go em storage/logs/vfd_bobg_debug.log.php. O arquivo não pode ser lido pela web. Os endereços dos clientes não são registrados. Os erros da Bob Go são registrados mesmo quando esta opção está desativada. Desative o log quando terminar. Quando o arquivo chega a 5 MB, ele é movido para vfd_bobg_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 limpá-lo.
Remove data on uninstall: quando ativado, ao desinstalar a extensão são excluídos as configurações da Bob Go, as tarifas em cache e os logs. O serviço da Bob Go salvo com os pedidos é mantido. Quando desativado (padrão), tudo é mantido para uma nova instalação.
Importar / Exportar
Export: clique em Download JSON para salvar as configurações em um arquivo JSON.
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.
Como funciona na finalização da compra
Quando o OpenCart exibe os métodos de envio, ele pede à extensão as tarifas da Bob Go. Se uma Geo zone estiver definida (e Ignore shipping zones estiver desativado) e o endereço estiver fora dela, a Bob Go não é oferecida. Somente produtos com Requires Shipping definido como Yes são considerados: os demais produtos não somam peso e não entram no valor do pedido. Em seguida, a extensão verifica o país de destino (com Ignore shipping zones), o peso do carrinho e o Minimum order amount. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. Vale-presentes, pontos de fidelidade e crédito da loja não são considerados. Se o frete grátis se aplicar, o cliente vê Bob Go (free) (o seu Method title) e nenhuma solicitação é enviada à Bob Go.
Nos modos em tempo real, a extensão envia à Bob Go o domínio da sua loja, os endereços de origem e de entrega (com a província) e os itens do carrinho: preços dos produtos em ZAR, pesos e dimensões, e o modelo do produto como SKU. Para endereços sul-africanos, a zona do OpenCart é enviada como código de província (EC, FS, GP, KZN, LP, MP, NC, NW, WC). As tarifas em tempo real só são solicitadas depois que o cliente informa uma cidade ou um CEP. As tarifas em ZAR são convertidas com a ZAR conversion rate quando a moeda da sua loja não é ZAR. O preço é calculado na moeda padrão, arredondado para as casas decimais dela e mostrado ao cliente na moeda dele, com o imposto da Tax class selecionada.
Abaixo do título do método, o cliente vê uma opção por serviço da Bob Go, com o nome, o preço e, se Delivery dates estiver ativado, as datas estimadas de entrega entre parênteses. O cliente escolhe um serviço como qualquer outra opção de envio do OpenCart. Com preço fixo, há uma única opção com o título do método.
No OpenCart 4, o cliente clica em Choose no bloco do método de envio na página de finalização da compra e escolhe um serviço da Bob Go na janela Shipping method options, por exemplo SkyNet - Overnight (by 17/10/2026) com o preço. O método funciona da mesma forma que no OpenCart 3.
As tarifas ficam em cache por 1 hora para cada solicitação completa, 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 é de 12 segundos, para que uma queda da Bob Go não deixe lenta cada atualização da finalização da compra. Uma solicitação com falha nunca interrompe a finalização da compra: o método fica oculto ou, no modo de alternativa, é usado o preço fixo. O motivo vai para o log.
A extensão mostra apenas tarifas. Ela não cria envios, conhecimentos de transporte ou etiquetas, não rastreia pacotes, não sincroniza pedidos com a Bob Go e não envia notificações. Use o painel da Bob Go para o atendimento dos pedidos. Não há seleção de ponto de retirada ou de armário. A Bob Go envia somente dentro da África do Sul.
Pedidos
O nome do serviço escolhido é o método de envio do pedido, por isso aparece nos e-mails do pedido, em Sales > Orders e na conta do cliente. Quando o pedido é feito, o serviço da Bob Go, o código dele e a estimativa de entrega também são salvos com o pedido. Alterações posteriores no carrinho ou nos preços da Bob Go não os modificam. No OpenCart 4, a finalização da compra mantém um único pedido: se o cliente voltar e confirmar o pedido novamente com outro serviço da Bob Go, o serviço salvo é atualizado, e com outro método de envio ou um preço fixo ele é removido.
No admin, a página do pedido em Sales > Orders mostra um bloco Bob Go com Bob Go service (nome e código) e Estimated delivery. O cliente vê Bob Go service e Estimated delivery na página de detalhes do pedido na conta dele. Pedidos com preço fixo ou frete grátis não têm serviço da Bob Go.
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 Bob Go é o primeiro bloco de Extensions > Extensions > Shipping > VibeFox Bob Go > Edit, 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 ficam a linha Product: opencart-shipping-bob-go e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão de modificação para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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, a extensão continua funcionando com o último status conhecido.
Uma chave funciona em um único domínio: o endereço da loja na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Bob Go não é mostrada aos clientes na finalização da compra e nenhuma tarifa é calculada. Um usuário administrador que esteja logado no admin 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 prévia não está disponível: a loja não enxerga o login do admin, então, sem uma chave ativa, o método fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. 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 ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após informar a chave 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
A Bob Go não aparece na finalização da compra: verifique se a licença está ativa e se Enable Bob Go está ativado. Verifique a Geo zone, ou ative Ignore shipping zones e verifique Countries. Verifique os limites de peso e o Minimum order amount. No modo de preço fixo, confirme que o país, o * ou o Flat price têm um preço. Confirme que os produtos têm Requires Shipping definido como Yes.
Nenhuma tarifa da Bob Go é exibida: abra a página da extensão. A seção Conta Bob Go mostra a última resposta da Bob Go. "The WooCommerce channel is not installed on Bob Go" (HTTP 404) significa que o domínio da loja não é um canal de vendas na Bob Go: confira o Store domain. "Rates at checkout is not enabled" (HTTP 401) significa que o recurso está desativado para o canal. Verifique também se o cliente informou uma cidade ou um CEP e, para lojas que não usam ZAR, se a ZAR conversion rate está definida. Ative o Debug log, recarregue a finalização da compra e veja o campo Log. Com Bob Go live rates, fixed prices if Bob Go returns no rates, os clientes continuam recebendo o preço fixo enquanto você corrige o problema.
Minha loja não usa rand: a Bob Go cota em ZAR. Informe quanto vale 1 ZAR na moeda da sua loja. Sem esse valor, a extensão não solicita tarifas à Bob Go. Os preços fixos continuam funcionando.
A página avisa que a África do Sul não tem zonas: adicione as províncias da África do Sul em System > Localisation > Zones; caso contrário, a Bob Go não recebe província para endereços sul-africanos.
O imposto é cobrado duas vezes no envio: as tarifas da Bob Go normalmente incluem o IVA. Defina Tax class como No tax.
As tarifas parecem desatualizadas após uma mudança: clique em Save na página da extensão. Isso limpa as tarifas da Bob Go em cache. As alterações na sua conta Bob Go são recebidas após o cache de 1 hora ou quando você salva as configurações.
A página diz "Warning: You do not have permission to modify VibeFox Bob Go!": o seu grupo de usuários administradores pode apenas visualizar as configurações. Dê ao grupo a permissão de modificação para extension/shipping/vfd_bob_go (OpenCart 3) ou extension/vfd_bob_go/shipping/vfd_bob_go (OpenCart 4) em System > Users > User Groups.
Para desenvolvedores: o endereço da API da Bob Go pode ser substituído pela configuração vfd_bobg_api_url (para testes); ela não tem campo na página de configurações.
Desinstalação
Acesse Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Bob Go. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre redefine Enable Bob Go, Sort order, Tax class e Geo zone. As tarifas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações da Bob Go e o log 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. O serviço da Bob Go salvo com os pedidos é sempre mantido, e os pedidos existentes mantêm o método de envio e o custo.
No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Bob Go na lista de extensões instaladas; em seguida, clique em Delete (o botão vermelho de lixeira) para remover o pacote enviado.
A Bob Go é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Bob Go.