VibeFox Instabee for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e versões posteriores (testado na versão 4.1.0.3).

PHP: 8.0 ou superior.

Credenciais da API Budbee (somente para a seleção da caixa de encomendas): uma chave de API e um segredo de API. A Instabee as emite para lojistas com contrato de entrega. Peça ao seu contato na Instabee ou use o portal de lojistas da Instabee. A documentação da API está em developer.budbee.com. Sem credenciais, o método continua funcionando com preços fixos, mas os clientes não escolhem uma caixa de encomendas.

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 o README.txt, o pacote do OpenCart 3 vfd_instabee-oc3-(version).ocmod.zip e o pacote do OpenCart 4 vfd_instabee.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, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_instabee-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 deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Instabee e clique em Install (o botão verde +).

3. Clique em Edit (o botão com lápis) para abrir a página de configurações.

4. Insira 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. Preencha a seção Prices e, para o seletor de caixa de encomendas, a sua API key e o seu API secret da Budbee (veja Configuração). Ative Enable/Disable e clique em Save.

OpenCart 4

1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo vfd_instabee.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. Vá em Extensions > Extensions e escolha o tipo de extensão Shipping. Encontre VibeFox Instabee, clique em Install (o botão verde +) e depois em Edit (o botão com lápis).

4. Insira 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.

Após a instalação, o método fica desativado até que você ative Enable/Disable e salve. Se você reinstalar a extensão depois de desinstalá-la, as configurações da Instabee que você manteve serão usadas novamente.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. As seções aparecem à esquerda. Um único botão Save salva a página inteira sem recarregá-la. Cada salvamento também limpa as listas de caixas em cache e o último erro da API. Somente usuários administradores com permissão de modificação para esta extensão podem salvar as configurações.

Os avisos acima das configurações informam quando apenas uma das credenciais da API foi preenchida, quando não há credenciais da API, quando não há preços por país nem custo de reserva, quando a última requisição à API da Budbee falhou (com data, hora e motivo), e quando a loja não tem uma classe de peso com a unidade kg e a unidade da classe de peso padrão não é reconhecida (nesse caso, os pesos são tratados como kg; adicione uma classe de peso kg em System > Localisation > Weight Classes).

Se Method name estiver vazio ou for longo demais, se Min weight (kg) for maior que Max weight (kg), se Sort order não for um número inteiro, ou se a classe de imposto ou a zona geográfica não existir, nada é salvo e um erro é exibido.

Geral

Enable/Disable: mostra ou oculta a Instabee na finalização de compra. Padrão: off.

Method name: o nome do método de envio mostrado ao cliente na finalização de compra. Padrão: Instabee parcel box. Obrigatório, no máximo 64 caracteres.

Tax class: None (the prices are final) (padrão) significa que os preços abaixo são finais. Uma classe de imposto acrescenta o imposto de envio dessa classe aos preços abaixo.

Sort order: a posição da Instabee entre os métodos de envio na finalização de compra. Um número inteiro.

Seletor de caixa de encomendas (API Budbee)

Com as credenciais da API, o cliente escolhe na finalização de compra uma caixa de encomendas perto do CEP dele, e a caixa é salva no pedido. Os dois campos são necessários. O seletor permanece desativado até que ambos estejam preenchidos.

API key: a sua chave de API da Budbee (o nome de usuário do HTTP Basic).

API secret: o seu segredo de API da Budbee (a senha do HTTP Basic). Ele nunca é gravado no log.

Após salvar, os dois campos ficam vazios e exibem Saved - leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para apagar as credenciais salvas, marque Remove the saved API key and secret e salve. Quando nada estiver salvo, a página exibe No credentials saved.

Test environment: usa a API de homologação da Budbee (api.staging.budbee.com). Ative-a somente com credenciais de homologação fornecidas pela Instabee. Lojas em produção deixam-na desativada (api.budbee.com). Padrão: off.

Preços (o título da seção mostra a moeda padrão da sua loja)

Todos os preços estão na moeda padrão da loja, sem impostos. Vírgula e ponto decimal são aceitos (49,90 = 49.90). O preço é exibido ao cliente na moeda dele.

Calculation type: como o preço é aplicado.

Country prices: uma tabela com as colunas Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg e XL >5 kg. Clique em Add country para adicionar uma linha e no botão × para remover uma. Escolha * Any other country para uma linha que se aplique a todos os países sem linha própria. Uma faixa vazia ou igual a 0 usa a coluna Price. Um Price de 0 significa entrega gratuita. Se a linha do país não tiver preço para o peso do carrinho, usa-se a linha * e, depois, o Fallback cost. Ao salvar, um preço que não seja um número igual ou maior que 0 é apagado, e uma linha com país desconhecido é removida; um aviso as lista. Os pesos dos produtos são convertidos da classe de peso do OpenCart para kg.

Fallback cost: usado quando nem a linha do país de destino nem a linha * fornecem um preço. Deixe em branco para ocultar o método nesses países.

Condições

Min weight (kg): oculta o método abaixo deste peso do carrinho. Padrão: 0 (sem limite).

Max weight (kg): oculta o método acima deste peso do carrinho. As caixas de encomendas suportam até cerca de 20 kg. Padrão: 20. 0 significa sem limite. Não pode ser menor que Min weight (kg).

Minimum order amount: exibe o método somente quando o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) atinge este valor. Deixe em branco para exibi-lo sempre.

Free shipping from: o subtotal dos produtos que precisam de envio (após o cupom, antes dos impostos) a partir do qual o método é gratuito. Deixe em branco para nunca torná-lo gratuito.

Se um valor nesses campos ou em Fallback cost não for um número igual ou maior que 0, ele não é salvo, o valor anterior permanece e um aviso indica o campo.

Disponibilidade

Geo zone: ofereça a Instabee somente para endereços nesta zona geográfica. All zones (padrão) significa em todos os lugares. A zona geográfica não é verificada quando Ignore shipping zones está ativado. As zonas geográficas são gerenciadas em System > Localisation > Geo Zones.

Ignore shipping zones: quando ativado, a Geo zone não é verificada e o método é oferecido para os países abaixo. Quando desativado (padrão), apenas a Geo zone se aplica.

Countries: os países de destino para esse modo. Deixe em branco para permitir todos os países. Este campo só é usado quando Ignore shipping zones está ativado.

Avançado

Debug log: grava mensagens de depuração em storage/logs/vfd_ibee_debug.log.php (no OpenCart 4, system/storage/logs/vfd_ibee_debug.log.php). O arquivo não pode ser lido pela web. Erros da API e pedidos feitos sem caixa enquanto a API estava funcionando são sempre registrados, mesmo quando esta opção está desativada. Chaves de API e dados de clientes nunca são registrados. Quando o arquivo atinge 5 MB, ele é movido para vfd_ibee_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, desinstalar a extensão apaga as configurações, as listas de caixas em cache, o log e as caixas de finalizações de compra não concluídas. Quando desativado (padrão), as configurações são mantidas para uma reinstalação. As caixas de encomendas salvas nos pedidos são sempre mantidas.

Importar / Exportar

Export: clique em Download JSON para salvar as configurações em um arquivo JSON. A chave e o segredo da API não são exportados.

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 e o segredo da API salvos são mantidos.

Como funciona na finalização de compra

Quando o OpenCart exibe os métodos de envio, ele pede à extensão o preço da Instabee. Com Ignore shipping zones ativado, a Instabee é oferecida somente quando o país é permitido (a zona geográfica não é verificada). Caso contrário, se uma Geo zone estiver definida e o endereço estiver fora dela, a Instabee não é oferecida. Somente produtos com Requires Shipping definido como Yes contam: os demais produtos não adicionam peso e não entram no valor do pedido. O valor do pedido é o preço dos produtos que precisam de envio, após o desconto do cupom e antes dos impostos. A extensão verifica o peso do carrinho e o valor mínimo do pedido. Se o subtotal atingir Free shipping from, o preço é 0. Caso contrário, o preço é obtido da linha Country prices do país de destino, da linha * ou do Fallback cost. Se não houver preço, o método fica oculto. O preço é calculado na moeda padrão da loja, arredondado conforme as casas decimais dela e exibido na moeda do cliente com o imposto da Tax class selecionada.

Quando o cliente seleciona a Instabee na etapa de método de entrega e as credenciais da API estão definidas, aparece um bloco Parcel box abaixo do método para Suécia, Finlândia, Dinamarca, Países Baixos e Bélgica. Ele lista as caixas próximas ao CEP do endereço de entrega, ordenadas por distância, com nome, endereço e distância. O cliente pode digitar outro CEP e clicar em Search (ou pressionar Enter). Até que um CEP seja informado, o bloco o solicita. Se nenhuma caixa for encontrada, o cliente é orientado a tentar outro CEP ou a escolher outro método de envio. Para os demais países, o método é oferecido sem caixa.

A caixa de encomendas é obrigatória. A caixa escolhida só é salva para a finalização de compra se estiver na lista da Budbee para aquele CEP. Um CEP digitado sem clicar em Search não é usado. Quando o cliente clica em Continue na etapa de método de entrega, a extensão verifica a caixa novamente no servidor. Caso contrário, o cliente vê Please choose an Instabee parcel box. O nome da caixa é obtido da lista da Budbee, não do navegador. Se o cliente alterar o país de entrega ou o CEP do endereço, a escolha anterior é descartada.

No OpenCart 4, o cliente clica em Choose no bloco do método de envio da página de finalização de compra e escolhe a Instabee na janela Shipping method options. O bloco Parcel box aparece nessa janela, abaixo da opção Instabee, e funciona da mesma forma. O botão Continue da janela não avança sem uma caixa da lista, com as mesmas mensagens.

A extensão envia à Budbee somente o país de destino e o CEP, nunca nomes, endereços, e-mails ou dados do pedido. As listas de caixas ficam em cache por 12 horas por CEP, um CEP sem caixas por 1 hora e uma requisição com falha por 5 minutos, para que uma API lenta ou com defeito não atrase cada atualização da finalização de compra. A página de finalização de compra em si nunca espera pela Budbee: a lista é carregada em segundo plano assim que o método é selecionado. O tempo limite da API é de 10 segundos.

Se a API da Budbee não puder ser acessada, o cliente vê Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one. O pedido é então sinalizado, e você escolhe a caixa ao reservar o envio. Uma caixa escolhida antes que não possa ser verificada naquele momento é mantida e marcada como não verificada.

A extensão não calcula tarifas em tempo real, não agenda envios, não imprime etiquetas, não fornece números de rastreamento ou e-mails de rastreamento, não oferece horários de entrega Budbee Home e não exibe um mapa. Agende a encomenda para a caixa escolhida nas ferramentas de lojista da Instabee / Budbee.

Pontos de retirada

Quando o pedido é criado, a caixa é verificada mais uma vez e salva no pedido. A partir daí, a loja não pode alterá-la. No OpenCart 4, a finalização de compra usa um único pedido, que é atualizado sempre que o cliente confirma de novo, e a caixa do pedido é atualizada junto com ele. Se o cliente mudar esse pedido para outro método de envio, a caixa é removida. A caixa aparece nestes locais:

Método de envio do pedido: a caixa é adicionada ao nome do método, por exemplo Instabee parcel box: (o nome do método) seguido do nome e do endereço da caixa. Este texto aparece nas páginas de pedidos do admin e da conta do cliente, nos e-mails do pedido e na nota fiscal.

Página do pedido no admin (Sales > Orders): um painel Instabee parcel box com o nome da caixa, o endereço e o Box ID. Se a caixa não puder ser verificada na finalização de compra, ela é marcada como not verified (Budbee API was unavailable at checkout). Se nenhuma caixa foi escolhida porque a API estava indisponível, o painel diz Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment. O painel é somente leitura e é exibido mesmo quando o método está desativado. No OpenCart 4 ele aparece acima de History.

E-mail de novo pedido para a loja: o nome da caixa com o seu ID, ou Instabee parcel box: not chosen (Budbee API unavailable at checkout).

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 Instabee é o primeiro bloco da página Extensions > Extensions > Shipping > VibeFox Instabee > Edit, acima das configurações. Insira a chave em License key e clique em Activate. Depois, 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: opencart-shipping-instabee e o link Manage licenses and domains in your account, que abre a sua conta em 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 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 do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, o método de envio Instabee não é exibido aos clientes na finalização de compra e nenhuma tarifa é calculada. Um usuário administrador conectado ao admin no mesmo navegador continua vendo 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 que você 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 do admin ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Não é preciso 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 Instabee não aparece na finalização de compra: verifique se a licença está ativa e se Enable/Disable está ativado. Confira Geo zone ou, se Ignore shipping zones estiver ativado, se o país está permitido em Countries. Confira se o país tem um preço, ou se existe uma linha * ou um Fallback cost. Confira os limites de peso e o Minimum order amount, e se os produtos têm Requires Shipping definido como Yes. Um aviso acima das configurações informa quando nenhum preço está configurado. Ative o Debug log para ver o motivo no campo Log.

Os clientes não veem a lista de caixas de encomendas: a lista aparece somente quando API key e API secret estão definidos, para Suécia, Finlândia, Dinamarca, Países Baixos ou Bélgica, e depois que um CEP é informado. O último erro da API é exibido acima das configurações. Os detalhes estão no campo Log na página da extensão. Ative o Debug log para mais detalhes.

HTTP 401 ou 403 no log: a Budbee rejeitou a chave ou o segredo da API. Verifique-os e confira se Test environment corresponde às suas credenciais (credenciais de homologação somente com o ambiente de teste ativado).

Nenhuma caixa para um CEP: a Budbee não atende esse CEP. O cliente pode pesquisar outro CEP ou escolher outro método de envio.

O cliente não consegue continuar pela etapa de método de entrega: uma caixa de encomendas precisa ser escolhida na lista, a menos que a API da Budbee não possa ser acessada. Uma caixa que não está na lista do CEP pesquisado não é salva, e o cliente vê This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.

Listas de caixas antigas após uma alteração: clique em Save na página da extensão. Isso limpa as listas de caixas em cache.

A página diz "Warning: You do not have permission to modify VibeFox Instabee!": o seu grupo de usuários administradores pode ter apenas permissão de visualização das configurações. Conceda ao grupo a permissão de modificação para extension/shipping/vfd_instabee (OpenCart 3) ou extension/vfd_instabee/shipping/vfd_instabee (OpenCart 4) em System > Users > User Groups.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Shipping e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Instabee. 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 listas de caixas em cache são sempre removidas. Se Remove data on uninstall estiver ativado, as configurações, o log e as caixas escolhidas em finalizações de compra que nunca viraram pedidos também são removidos. Se estiver desativado, as demais configurações são mantidas e reutilizadas quando você reinstalar a extensão. As caixas de encomendas salvas nos pedidos são sempre mantidas, e os pedidos existentes preservam o método de envio e o custo.

No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer após a desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Instabee na lista de extensões instaladas. Em seguida, clique em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Instabee e a Budbee são marcas de seus respectivos proprietários. Esta extensão não é afiliada nem endossada pela Instabee ou pela Budbee.